# Python SDK

我们提供一个简单的 Python SDK，用于无缝交互 [Oxylabs AI Studio API](https://aistudio.oxylabs.io/) 服务，包括 AI-Scraper、AI-Crawler、AI-Browser-Agent 以及其他数据提取工具。

## 要求

* `python 3.10` 及以上
* AI Studio API key

## 安装

```
pip install oxylabs-ai-studio
```

## 用法

### 爬取（`AiCrawler.crawl`)

```python
from oxylabs_ai_studio.apps.ai_crawler import AiCrawler

crawler = AiCrawler(api_key="<API_KEY>")

url = "https://oxylabs.io"
result = crawler.crawl(
    url=url,
    user_prompt="查找所有包含代理产品定价的页面",
    output_format="markdown",
    render_javascript=False,
    return_sources_limit=3,
    geo_location="US",
)
print("结果:")
for item in result.data:
    print(item, "\n")
```

#### **输入参数**

* `url` (str): 要爬取的起始 URL（**必需**)
* `user_prompt` (str): 用于引导提取的自然语言提示（**必需**)
* `output_format` (Literal\["json", "markdown"]): 输出格式（默认："markdown"）
* `schema` (dict | None): 用于结构化提取的 OpenAPI schema（若 output\_format 为 "json" 则必需）
* `render_javascript` (bool): 是否渲染 JavaScript（默认：False）
* `return_sources_limit` (int): 返回来源的最大数量（默认：25）
* `geo_location` (str): 以 ISO2 格式表示的代理位置。

### 抓取（`AiScraper.scrape`)

```python
from oxylabs_ai_studio.apps.ai_scraper import AiScraper

scraper = AiScraper(api_key="<API_KEY>")

schema = scraper.generate_schema(prompt="想要解析开发者、平台、类型、价格、游戏标题、类型（数组）和描述")
print(f"生成的 schema: {schema}")

url = "https://sandbox.oxylabs.io/products/3"
result = scraper.scrape(
    url=url,
    output_format="json",
    schema=schema,
    render_javascript=False,
)
print(result)
```

#### **输入参数**

* `url` (str): 要抓取的目标 URL（**必需**)
* `output_format` (Literal\["json", "markdown"]): 输出格式（默认："markdown"）
* `schema` (dict | None): 用于结构化提取的 OpenAPI schema（若 output\_format 为 "json" 则必需）
* `render_javascript` (bool): 是否渲染 JavaScript（默认：False）
* `geo_location` (str): 以 ISO2 格式表示的代理位置。

### Browser Agent（`BrowserAgent.run`)

```python
from oxylabs_ai_studio.apps.browser_agent import BrowserAgent

browser_agent = BrowserAgent(api_key="<API_KEY>")

schema = browser_agent.generate_schema(
    prompt="游戏名称、平台、评分星级和价格"
)
print("schema: ", schema)

prompt = "查找商店中是否有游戏 'super mario odyssey'。如果有，查找其价格。使用搜索栏查找该游戏。"
url = "https://sandbox.oxylabs.io/"
result = browser_agent.run(
    url=url,
    user_prompt=prompt,
    output_format="json",
    schema=schema,
)
print(result.data)
```

#### **输入参数**

* `url` (str): 要浏览的起始 URL（**必需**)
* `user_prompt` (str): 用于提取的自然语言提示（**必需**)
* `output_format` (Literal\["json", "markdown", "html", "screenshot"]): 输出格式（默认："markdown"）
* `schema` (dict | None): 用于结构化提取的 OpenAPI schema（若 output\_format 为 "json" 则必需）
* `geo_location` (str): 以 ISO2 格式表示的代理位置。

### 搜索（`AiSearch.search`)

```python
from oxylabs_ai_studio.apps.ai_search import AiSearch


search = AiSearch(api_key="<API_KEY>")

query = "千层面食谱"
result = search.search(
    query=query,
    limit=5,
    render_javascript=False,
    return_content=True,
)
print(result.data)
```

#### **输入参数**

* `query` (str): 要搜索的内容（**必需**)
* `limit` (int): 返回结果的最大数量（默认：10，最大：50）
* `render_javascript` (bool): 是否渲染 JavaScript（默认：False）
* `return_content` (bool): 是否在结果中返回 markdown 内容（默认：True）
* `geo_location` (str): 以 ISO2 格式表示的搜索代理位置。

#### 地图（`AiMap.map`)

```python
from oxylabs_ai_studio.apps.ai_map import AiMap


ai_map = AiMap(api_key="<API_KEY>")
payload = {
    "url": "https://career.oxylabs.io",
    "user_prompt": "招聘广告页面",
    "return_sources_limit": 10,
    "geo_location": None,
    "render_javascript": False,
}
result = ai_map.map(**payload)
print(result.data)
```

#### **输入参数**

* `url` (str): 要爬取的起始 URL（**必需**)
* `user_prompt` (str): 用于引导提取的自然语言提示（**必需**)
* `render_javascript` (bool): 是否渲染 JavaScript（默认：False）
* `return_sources_limit` (int): 返回来源的最大数量（默认：25）
* `geo_location` (str): 以 ISO2 格式表示的代理位置。

### 用法示例

请参阅我们 GitHub 中的 [examples](https://github.com/oxylabs/oxylabs-ai-studio-py/tree/main/examples) 文件夹，获取每个方法的详细用法示例（每个方法都有对应的 `async` 版本）。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.oxylabs.io/integrations/cn/ai-studio-integrations/python-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.