OxyLabs AI Studio Python SDK

一个简单的 Python SDK，用于无缝对接 Oxylabs AI Studio API 服务，包括 AI-Scraper（AI 爬虫）、AI-Crawler（AI 抓取器）、AI-Browser-Agent（AI 浏览器代理）以及其他数据提取工具。

要求

• python 3.10 及以上版本
• API 密钥

安装

pip install oxylabs-ai-studio

使用方法

抓取 (AiCrawler.crawl)

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="United States",
)
print("结果:")
for item in result.data:
    print(item, "\n")

参数:

• url (str): 起始抓取的 URL (必填)
• user_prompt (str): 指导提取的自然语言提示 (必填)
• output_format (Literal["json", "markdown", "csv", "toon"]): 输出格式 (默认值: "markdown")
• schema (dict | None): 结构化提取的 JSON Schema（当输出格式为 "json"、"csv" 或 "toon" 时必填）
• render_javascript (bool): 是否渲染 JavaScript (默认值: False)
• return_sources_limit (int): 返回来源的最大数量 (默认值: 25)
• geo_location (str): 代理位置，支持 ISO2 格式或国家规范名称。详见 文档
• max_credits (int | None): 最大使用的积分数量 (可选)

刮取 (AiScraper.scrape)

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", "csv", "screenshot", "toon"]): 输出格式 (默认值: "markdown")
• schema (dict | None): 结构化提取的 JSON Schema（当输出格式为 "json"、"csv" 或 "toon" 时必填）
• render_javascript (bool | string): 渲染 JavaScript。可以设置为 "auto"，表示服务会自动检测是否需要渲染 (默认值: False)
• geo_location (str): 代理位置，支持 ISO2 格式或国家规范名称。详见 文档
• user_agent (str): User-Agent 请求头。更多信息请参阅 https://developers.oxylabs.io/scraping-solutions/web-scraper-api/features/http-context-and-job-management/user-agent-type.

浏览器代理 (BrowserAgent.run)

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 = "查找商店中是否有游戏 '超级马里奥奥德赛'。如果有，找到其价格。使用搜索栏查找该游戏。"
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", "csv", "toon"]): 输出格式 (默认值: "markdown")
• schema (dict | None): 结构化提取的 JSON Schema（当输出格式为 "json"、"csv" 或 "toon" 时必填）
• geo_location (str): 代理位置，支持 ISO2 格式或国家规范名称。例如 'Germany'（首字母大写）。

搜索 (AiSearch.search)

from oxylabs_ai_studio.apps.ai_search import AiSearch


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

query = "lasagna recipe"
result = search.search(
    query=query,
    limit=5,
    render_javascript=False,
    return_content=True,
)
print(result.data)

# 或者快速搜索
result = search.instant_search(
    query=query,
    limit=10,
)
print(result.data)

参数:

• query (str): 搜索内容 (必填)
• limit (int): 返回结果的最大数量 (默认值: 10，最大值: 50)
• render_javascript (bool): 是否渲染 JavaScript (默认值: False)
• return_content (bool): 是否在结果中返回 Markdown 内容 (默认值: True)
• geo_location (string): 支持 ISO 两位字母格式、国家名称或坐标格式。更多信息请参阅 SERP 本地化.

注意: 当 limit <= 10 且 return_content=False 时，搜索会自动使用即时端点 (/search/instant)，无需轮询即可立即返回结果，从而提供更快的响应时间。

即时搜索支持的参数：

• query (string): 搜索查询。
• limit (integer): 返回搜索结果的最大数量。最大值：10。
• geo_location (string): Google 的规范位置名称。更多信息请参阅 Google Ads 地理目标。

地图 (AiMap.map)

from oxylabs_ai_studio.apps.ai_map import AiMap


ai_map = AiMap(api_key="<API_KEY>")
payload = {
    "url": "https://career.oxylabs.io",
    "search_keywords": ["career", "jobs", "vacancy"],
    "user_prompt": "job ad pages",
    "max_crawl_depth": 2,
    "limit": 10,
    "geo_location": "Germany",
    "render_javascript": False,
    "include_sitemap": True,
    "max_credits": None,
    "allow_subdomains": False,
    "allow_external_domains": False,
}
result = ai_map.map(**payload)
print(result.data)

参数:

• url (str): 起始 URL 或域名进行映射 (必填)
• search_keywords (list[str]): 用于 URL 路径过滤的关键词 (默认值: None)
• user_prompt (str | None): 自然语言提示，用于关键词搜索。可以与 'search_keywords' 一起使用或单独使用 (可选)
• max_crawl_depth (int): 最大爬取深度 (1..5, 默认值: 1)
• limit (int): 返回的最大 URL 数量 (默认值: 25)
• geo_location (str): 代理位置，采用 ISO2 格式或国家规范名称。详见 文档
• render_javascript (bool): 是否渲染 JavaScript (默认值: False)
• include_sitemap (bool): 是否将站点地图作为种子包含 (默认值: True)
• max_credits (int | None): 使用的最大积分数量 (可选)
• allow_subdomains (bool): 是否包含子域名 (默认值: False)
• allow_external_domains (bool): 是否包含外部域名 (默认值: False)

---

有关每个方法的使用示例，请参阅 examples 文件夹。每个方法都有对应的异步版本。

OxyLabs AI Studio Python SDK 快速上手指南

环境准备

在开始使用 oxylabs-ai-studio-py 之前，请确保满足以下要求：

• Python 版本：需要 Python 3.10 或更高版本。
• API 密钥：您需要从 Oxylabs AI Studio 获取一个有效的 API 密钥。

安装步骤

通过 pip 安装 SDK：

pip install oxylabs-ai-studio

如果您在中国大陆，建议使用国内镜像源加速安装，例如：

pip install oxylabs-ai-studio -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是最简单的使用示例，帮助您快速上手。

1. 爬取网页 (AiCrawler.crawl)

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="Find all pages with proxy products pricing",
    output_format="markdown",
    render_javascript=False,
    return_sources_limit=3,
    geo_location="United States",
)
print("Results:")
for item in result.data:
    print(item, "\n")

2. 抓取数据 (AiScraper.scrape)

from oxylabs_ai_studio.apps.ai_scraper import AiScraper

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

schema = scraper.generate_schema(prompt="want to parse developer, platform, type, price game title, genre (array) and description")
print(f"Generated schema: {schema}")

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

3. 浏览器代理操作 (BrowserAgent.run)

from oxylabs_ai_studio.apps.browser_agent import BrowserAgent

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

schema = browser_agent.generate_schema(
    prompt="game name, platform, review stars and price"
)
print("schema: ", schema)

prompt = "Find if there is game 'super mario odyssey' in the store. If there is, find the price. Use search bar to find the game."
url = "https://sandbox.oxylabs.io/"
result = browser_agent.run(
    url=url,
    user_prompt=prompt,
    output_format="json",
    schema=schema,
)
print(result.data)

4. 搜索 (AiSearch.search)

from oxylabs_ai_studio.apps.ai_search import AiSearch

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

query = "lasagna recipe"
result = search.search(
    query=query,
    limit=5,
    render_javascript=False,
    return_content=True,
)
print(result.data)

# 或者使用快速搜索
result = search.instant_search(
    query=query,
    limit=10,
)
print(result.data)

5. 网站映射 (AiMap.map)

from oxylabs_ai_studio.apps.ai_map import AiMap

ai_map = AiMap(api_key="<API_KEY>")
payload = {
    "url": "https://career.oxylabs.io",
    "search_keywords": ["career", "jobs", "vacancy"],
    "user_prompt": "job ad pages",
    "max_crawl_depth": 2,
    "limit": 10,
    "geo_location": "Germany",
    "render_javascript": False,
    "include_sitemap": True,
    "max_credits": None,
    "allow_subdomains": False,
    "allow_external_domains": False,
}
result = ai_map.map(**payload)
print(result.data)

---

以上是 oxylabs-ai-studio-py 的基本使用方法。更多高级用法和示例，请参考 examples 文件夹。