← 返回 DataDome API documentation

清晰输入，明确终态。

DataDome 求解请求使用 X-API-Key 鉴权，与 Cloudflare 共用账号和额度。每次受理预扣 1 个额度，超时失败自动退回；响应返回剩余额度。

打开测试台 OpenAPI / Swagger

POST/solver/v1/solve/datadome

DataDome Challenge

处理无感验证与简单滑块，在同一 Session 中完成挑战并访问目标，返回最终 Cookie 与页面验证结果。

必填: url
可选: proxy cookies allow_interactive
终态: datadome + verification_passed

PROXYHTTP(S) / SOCKS5(H)

你的目标，你的出口。

不设网站域名白名单，可传入任意公网 HTTP / HTTPS 目标。支持带用户名密码的代理；不传代理则由服务器直连。

代理格式: 协议://用户名:密码@主机:端口
使用范围: 仅用于你拥有或获授权的目标
能力边界: 图片拼图、音频挑战和 hard-block 暂不支持

Request reference

鉴权与请求参数

Content-Type: application/json · X-API-Key: capi_live_…

参数	类型 / 默认值	说明
`url`	string · 必填	8–2048 字符；公网 HTTP / HTTPS URL，支持有效自定义端口；不能包含用户名密码。
`proxy`	string / null · null	最多 2048 字符；支持 http、https、socks5、socks5h，必须指定端口；空字符串或 null 表示直连。
`cookies`	object · {}	初始 Cookie 的名称到字符串值映射；最多 50 项，每项值不超过 8192 字符。
`timeout`	number · 30	单次网络请求超时，1–60 秒。
`flow_timeout`	number · 90	求解流程超时，10–300 秒；队列等待和进程启动另计，客户端应留出余量。
`allow_interactive`	boolean · true	允许 noPuzzle=true 简单滑块交互；不代表支持图片拼图或音频挑战。

代理使用说明

例如 http://user:password@proxy.example.com:8080 或 socks5h://user:password@proxy.example.com:1080。用户名和密码中的 @、:、/ 等特殊字符需分别进行 URL 编码。代理由服务器访问，不能填写本机或私网代理。

目标访问、挑战请求和最终验收使用同一代理。目标与代理必须解析到公网 IP；目标由服务端解析并固定，因此 socks5h 不将目标域名交给远端自由解析，HTTP(S) 代理需支持 CONNECT。TLS 仍验证原始域名。代理凭据不回显、不写调用记录。

不限制域名不等于所有挑战都可通过。复用 Cookie 时应保持相同代理出口、User-Agent 和相关会话上下文；图片拼图、音频挑战或 hard-block 会返回失败。

Quick start

请求示例

设置 WANXIANG_API_KEY；可选设置 DATADOME_PROXY，不设置则直连。

Python · requests

import os
import requests

response = requests.post(
    "https://your-host/solver/v1/solve/datadome",
    headers={"X-API-Key": os.environ["WANXIANG_API_KEY"]},
    json={
        "url": "https://www.tripadvisor.com/Tourism-g24971875-Universal_Orlando_Resort_Orlando_Florida-Vacations.html",
        "proxy": os.getenv("DATADOME_PROXY") or None,
        "cookies": {},
        "timeout": 30,
        "flow_timeout": 90,
        "allow_interactive": True,
    },
    timeout=360,
)
if response.status_code == 504:
    print("请求超时，是否扣费：", response.json().get("charged"))
response.raise_for_status()
result = response.json()
assert result["verification_passed"]
cookie = result["datadome"]
user_agent = result["user_agent"]

cURL · 替换目标与代理示例值

curl --request POST 'https://your-host/solver/v1/solve/datadome' \
  --header "X-API-Key: $WANXIANG_API_KEY" \
  --header 'Content-Type: application/json' \
  --max-time 360 \
  --data '{
    "url": "https://your-authorized-site.example/page",
    "proxy": "http://user:password@proxy.example.com:8080",
    "timeout": 30,
    "flow_timeout": 90,
    "allow_interactive": true
  }'

Response reference

响应字段与错误处理

以下为结构示例，不代表目标实测通过。

HTTP 200 · 主要字段示例

{
  "mode": "datadome",
  "datadome": "<最终 Cookie 值，不含 datadome= 前缀>",
  "verification_passed": true,
  "verification_status": 200,
  "verification_url": "https://your-authorized-site.example/page",
  "verification_checks": {"http_200": true, "no_challenge_page": true},
  "user_agent": "<本次会话 User-Agent>",
  "fingerprint_profile": "<本次画像 ID>",
  "proxy_enabled": true,
  "session_request_count": 6,
  "completion_branch": "automatic",
  "total_elapsed_seconds": 12.5,
  "request_id": "<调用编号>",
  "quota": {"limit": 20, "used": 1, "remaining": 19}
}

verification_checks 为验收项，各目标可能不同；completion_branch 为 automatic 或 simple-slider；page_sha256 为正文摘要（可为 null）。响应还包含原始 url；成功响应头提供 X-RateLimit-Limit 和 X-RateLimit-Remaining。API Key、Cookie 与 request_id 不能互换。

HTTP 状态	含义	处理与计费
401 / 403	Key 无效；测试未登录或 CSRF 校验失败	检查 Key / 重新登录；未受理不扣费。
409	挑战类型不支持	检查挑战类型；已受理的非超时失败仍扣 1 个额度。
422	参数无效、目标或代理被安全规则拒绝	检查 URL、协议、端口和参数范围；已受理仍按现有规则计费。
429	额度不足	充值后重试；不额外扣费。
502	代理失败、hard-block 或最终验证未通过	检查出口和挑战；已受理的非超时失败仍扣 1 个额度。
503	运行环境未就绪，或超时退费记账异常	未就绪不扣费；记账异常请保留 request_id，由管理员核对。
504	网络或流程超时	返回 charged=false、charge_units=0 和更新后的 quota，自动退回本次额度。
500	内部异常	保留调用记录联系管理员；非超时不自动退费。

HTTP 504 · 超时响应示例

{
  "detail": "请求超时，本次未扣费。",
  "charged": false,
  "charge_units": 0,
  "request_id": "<调用编号>",
  "quota": {"limit": 20, "used": 0, "remaining": 20}
}

其他错误通常返回 {"detail":"错误说明"}，参数类型错误的 detail 可能为数组。取消等待不代表后端停止求解或自动退费，以控制台调用记录为准；不要无条件重试，以免重复扣费。