Web Unblocker API 用于获取目标网页在指定国家/地区下的页面内容。你只需要提交目标 URL 和少量控制参数，我们系统会负责完成代理、解锁、可选渲染、页面等待和结果返回。
该接口适合用于访问存在基础反爬、地域差异或需要稳定抓取链路的公开网页。
登录后抓取数据通常涉及访问个人或敏感信息，许多网站在其服务条款中明确禁止。
为了帮助您遵守目标网站的规定并避免任何潜在的法律问题，我们专注于提供仅抓取公开可用数据的工具。
Web Unblocker API 优先保证可用性和稳定性，不提供复杂结构化抽取能力，后续将推出带有抽取能力的服务，如需要特殊数据清洗服务可联系我们进行定制；
接口地址 #
POST /v1/web-unblocker/query认证方式 #
请求需要携带 API Key。
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json响应头 #
每次请求都会返回链路 ID，建议在客户端日志中记录，方便排查问题。
X-Request-Id: request-id请求参数 #
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
target_url | string | 是 | – | 目标网页 URL，必须是合法的 http 或 https 地址 |
js_render | integer | 否 | 0 | 是否启用 JavaScript 渲染。支持 0 = 关闭，1 = 启用 |
format | array | 否 | ["html"] | 返回格式数组。元素可选值：html、png |
country | string | 否 | – | 访问目标网页时使用的两位大写国家/地区代码，例如 US。不传或传空表示不指定国家/地区 |
headers | object | 否 | – | 透传给目标网页的请求头，必须是字符串键值对 |
cookies | object | 否 | – | 透传给目标网页的 Cookie，必须是字符串键值对 |
参数说明 #
target_url
target_url 是需要抓取的目标网页地址。
示例：
{
"target_url": "https://example.com"
}要求：
- 必须以
http://\或https://\开头。 - 必须包含合法 host。
- 不支持内网地址、本地地址和非法 URL。
- 建议传入最终页面 URL，避免过多跳转影响稳定性和响应时间。
country
country 用于指定访问目标网站时使用的出口国家/地区。
示例：
{
"country": "US"
}如果目标网站存在明显地域差异，建议显式传入该参数。不传或传空时，不指定国家/地区，由系统按默认策略处理。
js_render
js_render 用于控制是否启用 JavaScript 渲染。
示例：
{
"js_render": 1
}取值说明：
| 值 | 说明 |
1 | 开启 JavaScript 渲染。 |
0 | 关闭 JavaScript 渲染。 |
如果目标页面是普通静态 HTML，建议不传或传 0，可以获得更快响应速度。
建议仅在以下场景开启：
- 页面主体内容由 JavaScript 动态生成。
- 直接请求 HTML 时拿不到有效内容。
- 目标页面需要等待前端接口加载后才展示内容。
- 需要返回
png截图。
format
format 用于指定返回内容格式，类型为字符串数组。
可选值：
| 数组元素 | 说明 |
html | 返回解锁后的原始 HTML 内容。 |
png | 返回目标页面截图内容。 |
示例：
{
"format": ["html"]
}如果需要同时返回 HTML 和截图，可以传入：
{
"format": ["html", "png"]
}format 包含 png 时，需要同时开启 js_render=1。如果请求参数组合不满足要求，接口会返回请求条件不满足类错误。
headers
headers 用于向目标网页透传请求头。
示例：
{
"headers": {
"User-Agent": "Mozilla/5.0",
"Accept-Language": "en-US,en;q=0.9"
}
}参数要求：
- 必须是对象。
- key 去除首尾空格后不能为空。
- value 必须是字符串。
- 空对象
{}合法。
请不要传入包含敏感凭证的请求头，除非你明确知道目标网站需要这些信息。
cookies
cookies 用于向目标网页透传 Cookie。
示例：
{
"cookies": {
"session_id": "example-session"
}
}要求：
- 必须是对象。
- key 去除首尾空格后不能为空。
- value 必须是字符串。
- 空对象
{}合法。
请谨慎传入 Cookie，避免把账号凭证、登录态或其他敏感信息用于不可信目标网站。
请求示例 #
最小请求
curl -X POST "https://api.example.com/v1/web-unblocker/query" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"target_url": "https://example.com"
}'成功响应 #
成功时接口返回统一 JSON 结构。
format = [“html”]
{
"code": 200,
"message": "success",
"data": {
"html": "<!doctype html><html>...</html>",
"http_status": 200
}
}format = [“png”]
{
"code": 200,
"message": "success",
"data": {
"image": "base64-image-content",
"http_status": 200
}
}字段说明：
| 字段 | 类型 | 说明 |
html | string | format 包含 html 时返回，解锁后的原始 HTML 内容。 |
image | string | format 包含 png 时返回，目标页面 PNG 截图的 Base64 内容。 |
http_status | integer | 目标页面 HTTP 状态码。 |
响应字段按请求 format 数组返回，未请求的格式字段不会出现在响应中。
公开响应不会返回账号信息、密钥或其他敏感信息。
失败响应 #
失败时接口返回统一错误结构。业务失败的 HTTP 状态码固定为 200，请以响应体中的 code 判断请求是否成功。
{
"code": 120404,
"message": "Request timed out. Please increase the timeout or retry later.",
"data": null
}常见错误码：
| code | 说明 |
100001 | 服务暂时异常，请稍后重试。 |
100301 | 请求参数错误，例如 target_url 缺失、URL 格式错误、await_ms 超出允许范围、js_render 或 format 类型、元素取值非法。 |
110102 | API Key 缺失、格式错误、无效或已被轮换。 |
110103 | API Key 已停用。 |
110104 | API Key 状态异常，请刷新后重试。 |
110205 | 套餐状态异常，请刷新后重试。 |
110301 | 余额不足，无法发起本次请求。 |
120401 | 请求未通过执行前校验，例如目标 URL 不允许访问、用户 QPS 超限等。 |
120402 | 当前服务繁忙，并发连接数较多，可联系客服为您调整连接节点或者稍后重试。 |
120403 | 爬虫请求执行失败。 |
120404 | 请求执行超时。 |
120405 | 服务暂时不可用，请稍后重试。 |
120406 | 当前不支持该请求参数值，例如某个 country、format 或 await_ms 暂不支持。 |
120407 | 当前不支持该参数组合。 |
120408 | 请求条件未满足，例如 format 包含 png 但未开启必要的渲染能力。 |
更详细的响应说明请查看 响应码 一章
