Oxygent Crawl API Developer

最小请求

所有请求使用 Bearer Token 鉴权。示例里的 token 使用环境变量占位，不要把真实 token 写进文档。

curl -X POST "https://crawl.oxygent.org.cn/crawl" \
  -H "Authorization: Bearer ${CRAWL_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/page"],
    "include_html": false
  }'

集群容量

GET /capacity 使用同一个 Bearer Token 鉴权，返回当前 token 可用的 worker 池、槽位占用和建议并发。这个接口不会增加 token 调用次数。

curl -X GET "https://crawl.oxygent.org.cn/capacity" \
  -H "Authorization: Bearer ${CRAWL_TOKEN}"

字段	说明
`capacity.available_slots`	当前 token 可用池中的剩余并发槽位。
`pools`	按 `online_reserved` / `shared` 展开的 worker 池容量；离线 token 只看到 shared。
`advice.state`	`open`、`limited`、`throttle` 或 `closed`，用于客户端调节请求频率。
`advice.recommended_concurrency`	建议客户端当前最大并发。
`advice.recommended_rps`	建议客户端当前请求速率。

请求结构

字段	类型	说明
`urls`	`string[]`	必填。支持单 URL 或多 URL 批量抓取。
`strategy`	`string`	默认 `auto`。按低成本到高成本依次尝试 curl、CloakBrowser CDP、CloakBrowser direct。
`browser_config`	`object`	浏览器身份配置，例如 locale、headers、cookies、viewport、proxy。
`crawler_config`	`object`	抓取行为配置，例如超时、wait_for、滚动、delay、sitemap 限制。
`extraction`	`object`	结构化抽取配置，支持 CSS schema 和 XPath schema。
`include_html`	`boolean`	是否返回 HTML。调试 selector 时建议开启。
`extracted_data_only`	`boolean`	有 extraction 时默认只返回数据；设为 false 可同时返回 envelope 和 HTML。
`max_concurrency`	`number`	批量 URL 的客户端请求内并发，默认 1。

CSS Schema 示例

baseSelector 应该匹配一个逻辑输出项；详情页可使用 html 或稳定详情容器。

{
  "urls": ["https://example.com/products"],
  "extracted_data_only": false,
  "extraction": {
    "type": "css_schema",
    "schema": {
      "name": "products",
      "baseSelector": "article.product-card",
      "fields": [
        { "name": "title", "selector": "h2", "type": "text", "transform": "strip" },
        { "name": "href", "selector": "a", "type": "attribute", "attribute": "href" },
        { "name": "url", "type": "computed", "expression": "\"https://example.com\" + href if href.startswith(\"/\") else href" },
        { "name": "price", "selector": ".price", "type": "text", "transform": "strip" }
      ]
    }
  }
}

返回值约定

HTTP 状态码表示控制面、调度和目标站访问的外层结果；是否拿到可用内容，以响应体里的 success、error_type、action_required 和 results 为准。

HTTP	响应体特征	含义	处理建议
`200`	`success=true`，或直接返回抽取数组	已拿到有效内容；正常空结果也会在有页面证据时计为成功。	消费 `results`、`extracted_data` 或 HTML。
`200`	`success=false` / `empty_extraction`	页面可访问，但抽取规则没有拿到有效记录。	开启 `include_html=true` 和 `extracted_data_only=false` 调试 selector。
`400`	`detail`	请求 JSON、URL 或 schema 参数非法。	修正请求体后重试。
`401`	`detail`	Token 缺失、错误或已禁用。	检查 Bearer Token。
`429`	`action_required=true`，`error_type=proxy_required` / `blocked_fetch`	目标站触发机器人校验、验证码、Akamai、DataDome、Cloudflare、403/429，或站点级冷却中；这不是网关故障。	降低频率，补 locale/header/cookie，或传入可用代理后重试。
`500`	`success=false`	控制面内部异常。	记录 `X-Crawl-Control-Request-Id` 联系平台排查。
`502`	`request_error` / `upstream_5xx` / `upstream_error`	worker 调用、浏览器运行时、网络或目标上游 5xx 等平台/链路异常。	按指数退避重试；持续出现时联系平台排查。
`503`	`no_worker` 或 `no available crawl worker`	当前没有可用 worker 或服务池槽位耗尽。	调用 `/capacity` 降低并发，稍后重试。

{
  "success": false,
  "detail": "node-a: proxy_required Amazon robot check | proxy required for retry",
  "error_type": "proxy_required",
  "action_required": true
}

用户自带代理

为控制成本，调用方可以在请求里传自己的代理。平台会同步到 curl、浏览器和 CloakBrowser 路径。明确的反爬阻断默认不会盲目换节点重试；带代理后会继续按调度策略重试。

字符串格式

{
  "urls": ["https://example.com/page"],
  "proxy": "http://user:pass@proxy.example.com:8080"
}

结构化格式

{
  "urls": ["https://example.com/page"],
  "proxy_config": {
    "server": "http://proxy.example.com:8080",
    "username": "user",
    "password": "pass"
  }
}

{
  "urls": ["https://example.com/page"],
  "proxy": "http://user:pass@proxy.example.com:8080",
  "control_config": {
    "max_attempts": 3
  }
}

交互调试台

Token 只在当前页面内存中使用，不写入浏览器存储。

ready

crawl-api-extraction Skill

这个 skill 用来帮助 Codex 生成、复核和调试 Crawl API 请求体。

下载 zip

能力	说明
请求体生成	按目标 URL、业务字段和页面类型生成可复用的 `/crawl` payload。
Schema 设计	选择 CSS/XPath baseSelector，设计 text、attribute、computed、nested 字段。
调试流程	通过 `include_html` 和 `extracted_data_only=false` 检查原始 HTML 和缺失字段。
结果分类	区分 ok、empty、blocked_fetch、request_error、extraction_error 和 skill_issue。

mkdir -p ~/.codex/skills
unzip crawl-api-extraction.zip -d ~/.codex/skills/

错误和结果判断

状态	含义	处理建议
`success=true`	抓取结果通过有效内容判断；有抽取配置时，拿到有效抽取记录，或页面证据证明正常无结果。	直接消费 `results[0].extracted_data` 或 HTML。
`blocked_fetch`	目标返回 Akamai、DataDome、Cloudflare、验证码或 403/429。	降低频率，补 locale/header/cookie/proxy，必要时使用用户代理。
`empty_extraction`	候选策略都没提取到有效记录，且没有足够证据证明这是正常空结果。	开启 HTML 返回，检查查询词、baseSelector 和字段 selector；业务允许空结果时也可设置 `allow_empty_extraction=true`。
`request_error`	网络、超时、worker 或上游 5xx 异常。	重试或提高超时；批量压测时降低并发。

Crawl API 使用文档