API endpoint 参考

包含所有 FourA API endpoint、request 参数及 response 格式的参考文档。

基础 URL

https://eu.api.foura.ai/api

身份验证

每个 request 都需要在 X-API-Key header 中包含您的 API key:

curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method": "GET", "url": "https://example.com"}'

在 控制台 中创建和管理 API 密钥。密钥使用 pk_live_ 前缀。

响应头

来自 /api/* 的响应包含两个关联标头:

Header Value Description
X-FourA-Request-Id UUID 分配给该请求的唯一 ID。在所有响应中返回(包括 4xx 和 5xx),但 FourA 完全无法读取请求体的情况除外: 400 Invalid JSON in request body 和 413 会在分配 ID 之前被拒绝。建议在您的系统记录此 ID。
X-FourA-Credits integer 该请求消耗的积分。在到达引擎的所有响应中返回,无论是成功还是失败(工作已执行)。在引擎运行前被 FourA 拒绝的调用(缺少或无效的密钥、套餐或平台限制、被拒绝的目标或代理 ID)不包含此项。有关哪些结果计费,请参见 请求结果。

相同的请求 ID 用作控制台 活动日志(保留 24 小时,每个密钥最近 200 条)中请求和响应载荷预览的键,因此您稍后可以查找确切的请求,并从活动日志直接重放到 Playground。联系支持人员时附上此 ID,可在数秒内精准定位该请求。

$ curl -i -X POST https://eu.api.foura.ai/api/single/ \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"method": "GET", "url": "https://example.com"}'

HTTP/2 200
content-type: application/json
x-foura-request-id: 8f3e2a14-7b6c-4d1a-9e2f-5a3b8c1d4e7f
x-foura-credits: 2
...

完整列表及使用提示请参阅 Response Headers。

端点

通过 MCP 使用这些端点? @fouradata/mcp 服务已将所有四个端点封装为原生 MCP 工具(foura_auto、foura_single、foura_proxy、foura_browser),具备相同的输入结构,并额外提供 offload_large 选项以支持对 token 友好的大响应处理。主要差异:foura_browser 不包含 lean 字段,且 foura_proxy 暂不支持 出口位置字段。

FourA 提供四个 request 端点,分别针对不同场景进行了优化:

Endpoint 适用场景
POST /auto/ 智能抓取。传入 URL 后,FourA 会选择成本最低的有效路径(轮换 proxy 或浏览器,以及包含 forceProxy: false 的直连 request),并记住每个主机的有效方案。
POST /single/ 快速 HTTP request、静态页面、API
POST /proxy/ 受保护的站点,具备自动 proxy 轮换,支持可选的目标可见国家范围限定
POST /browser/ JavaScript 渲染的页面、SPA
GET /profiles 适用于 single 和 proxy 的浏览器配置文件目录。公开,无需 API key。

有关各端点选型的深入指南,请参阅 选择合适的端点 以及 Smart Fetch 指南。

目标 URL 限制

解析为私有、回环或保留 IP 地址范围(RFC 5735、RFC 6598、IPv6 保留块)的目标会在 request 离开 FourA 之前被拒绝并返回 400。仅转发公共主机名和 IP。

{ "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts." }

指向 FourA 自身 API 主机(eu.api.foura.ai 或 api.foura.ai)的目标也会在所有四个 endpoint 上被拒绝并返回 400,此操作发生在任何抓取或计费之前。包含空格或控制字符的 URL 同样会在 Single、Proxy 和 Auto 上被拒绝并返回 400;请将空格编码为 %20(Browser 模式会按 Chrome 的方式抓取)。FourA 唯一会抓取的此类页面是 /inspect。

{ "error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL." }

智能获取 (Auto)

POST /api/auto/

传入目标 URL 以及可选的 validate 规则。FourA 会按成本优先阶梯逐级尝试(轮换 proxy,随后完整浏览器),并在首个返回符合规则响应的层级停止。启用 forceProxy: false 时,会先执行低成本的直连探测。针对同一主机的后续调用,会重放预热 session,从而降低二次请求成本。

无需手动调优重试次数、池大小或 proxy 数量,FourA 会针对每个主机自动学习。

请求体

参数 类型 必填 默认值 描述
url string 是 - 目标 URL
method string 否 "GET" HTTP 方法
headers [string, string][] 否 - 发送到目标的 headers,格式为 [name, value] 键值对。除浏览器层级外,所有层级都会发送这些 headers。你发送的 Cookie 将原样到达目标站点,已存储 session 的 cookie 仅会在名称不冲突时补充添加。已存储 session 的 userAgent 会替换你传入的 User-Agent。Proxy 层级会忽略条件 headers(如 If-None-Match),除非你的 validate.status.accept 明确列出了 304。
data any 否 - 非 GET 请求的请求体
validate object 否 - 成功判定条件,格式与 Single Request 的 validate 相同(见下文)。向 auto 描述正常页面的特征,以便区分真实内容与验证页面。
returnSession boolean 否 true 在响应中包含胜出的 session(proxy、cookies、userAgent),以便通过 /api/single/ 或 /api/browser/ 进行重放。
forceProxy boolean 否 true 始终通过轮换 proxy 路由。设置为 false 可在目标允许时使用成本更低的直连路径(部分防御机制对 proxy 流量更为严格)。
timeout_ms integer 否 120000 整个调用的总时间预算,单位为毫秒。所有子尝试均在此预算内运行。最小值为 5000,最大值为 180000。
ignoreProxies string[] 否 - 所有子尝试中需要规避的 proxy ID。使用此前 /api/auto/ 或 /api/proxy/ 响应返回的 ID。
followRedirects integer 否 5 低成本阶梯层级中跟随的最大重定向次数。设为 0 表示禁用。最大值为 20。
exitClass string 否 - standard 或 premium,用法同 Proxy Request。premium 允许在标准池无法访问页面时将调用升级至高级出口。需要包含高级出口的套餐支持。请参阅 Smart Fetch 中的 exitClass。

响应

{
  "status": 200,
  "data": "<!doctype html>...",
  "headers": [{"content-type": "text/html"}],
  "meta": {
    "rung": "cache",
    "solved": false,
    "attempts": 1,
    "credits": 2,
    "attemptsByEngine": {"single": 1, "proxy": 0, "browser": 0},
    "browserRequests": 0
  },
  "session": {
    "proxy": "A1B2C3",
    "cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
    "userAgent": "Mozilla/5.0..."
  }
}
字段 类型 说明
status number 目标返回的 HTTP 状态码。
data string 响应体文本,无论由哪一级阶梯返回。JSON 页面将作为 JSON 文本返回,需自行解析。
headers array or object 目标响应 headers。Single 和 proxy 阶梯返回逐跳 header 对象的数组;browser 阶梯返回扁平对象。
meta.rung string 交付响应的阶梯层级。取值之一:probe(低成本直连 request,仅限 forceProxy: false)、proxy(轮换 proxy)、browser(完整浏览器渲染)、cache(复用预热会话)、warmup(先抓取站点入口页并利用其 cookie 打开深层 URL)或 fail(没有阶梯产生有效响应)。
meta.solved boolean 页面是否需要额外步骤(验证页面)且已在本次调用中完成。
meta.attempts number 成功前进行的子重试次数。
meta.credits number 本次调用消耗的总积分。与 X-FourA-Credits 一致。
meta.attemptsByEngine object 发送到 single、proxy 和 browser 的 request 数。因已被发送,套餐拒绝的浏览器 request 也会计入。
meta.browserRequests number 占用每日配额槽位的浏览器 request 数。套餐拒绝的浏览器 request 不占用配额。
meta.exitClass string 交付响应的出口类别,当 request 指定了 exitClass 时存在:premium 或 standard。相同值也会通过 X-FourA-Exit-Class 响应 header 传递。
session.proxy string 交付响应的 proxy 编码 ID。可在 Single 或 Browser request 中复用。当 returnSession 为 true 时存在。
session.cookies array 供复用的 cookie 列表,每项至少包含 name 和 value。browser 阶梯返回浏览器的 cookie jar。proxy 阶梯或直连探测仅返回解锁页面所需的 cookie(例如站点验证页设置的 cookie),不会返回页面设置的所有 cookie,因此列表可能为空。当 returnSession 为 true 时存在。
session.userAgent string 成功尝试中所使用的 User-Agent。当 returnSession 为 true 时存在。
error string 调用失败时的错误信息。
attemptReport object 调用失败时按原因分类的未返回页面的引擎 request。参见 Smart Fetch。

示例

curl -X POST https://eu.api.foura.ai/api/auto/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}}
  }'

注意事项

  • Auto 是一个协调器。它在内部调用 Single、Proxy 或 Browser,并将您的 API key 转发给每个子调用。Auto 调用在您的 Activity Log 和 Overview 中计为一次 request,消耗其子调用积分的总和;子调用作为尝试记录列在其下方,绝不会单独计为独立的 request。
  • 传入 validate.data.accept,并附带仅真实页面才包含的子字符串。若没有它,Auto 无法区分真实的 200 状态与返回状态码 200 的质询插页。
  • 页面被移除属于站点的正常响应,而非拒绝服务。当两个出口节点返回相同的 404 或 410 且您的 validate 不接受它时,调用将以此 status 结束,并返回以 the site answered 开头的 error。将该状态列入 validate.status.accept,Auto 就会交付首个具有该状态且通过您其余 validate 的 response。您在此处列出的任何其他状态同样适用,但 403、429、503 和 202 除外,站点在返回质询页面时也会发送这些状态。
  • timeout_ms 限制整个调用的总耗时。对受保护站点的首次冷请求可能需要数十秒;复用预热 session 通常在一秒内完成。

Smart Fetch 上的 exitClass

exitClass 在 Smart Fetch 上的机制与在 Proxy Request 上相同:它是一种配额许可,而非强制指令。Auto 会首先尝试标准池。当标准池无法访问该页面且 request 指定了 premium 时,Auto 会通过高级出口在浏览器中打开页面。在此建立的 session 将服务于后续同样指定 premium 且访问同一站点的调用;未指定它的调用绝不会复用该 session。

用尽配额不属于错误。一旦您套餐中的高级流量在当前计费周期内耗尽,调用将在标准池中继续进行,且 meta.exitClass 会显示 standard。在不包含高级出口的套餐中,发送 exitClass: premium 的调用将在开始执行前被拒绝,返回带有 X-FourA-Limit: plan_limit_premium 的 403。

高级流量的统计方式与 Proxy Request 相同。在浏览器中打开页面所加载的内容多于页面本身,因此高级 Smart Fetch 页面消耗的高级流量要高于通过 Proxy Request 获取的同一页面。为了降低流量消耗,高级 Smart Fetch 页面加载时不包含图片、字体和媒体,并会拦截来自已知广告、分析和用户同意管理提供商的脚本。


Single Request

POST /api/single/

发送具有高度拟真浏览器级底层网络特征的 HTTP request,无需启动真实浏览器。这是速度最快的 endpoint。

请求体

参数 类型 必填 默认值 描述
method string 是 - HTTP 方法: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
url string 是 - 目标 URL。在 URL 任意位置使用 {ts} 可插入当前时间戳以防止缓存。
headers [string, string][] 否 - 自定义 headers,格式为 [name, value] 键值对
unblocker boolean 否 true 发送真实的浏览器 headers (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding)。默认开启。设置为 false 时,FourA 不会添加任何浏览器 headers,仅发送你传入的内容。
timeout_ms number 否 15000 总超时时间,单位为毫秒 (最大值: 120000)
connect_timeout_ms number 否 5000 连接超时时间,单位为毫秒
accept_timeout_ms number 否 5000 接收超时时间,单位为毫秒 (等待连接建立的时间)
server_response_timeout_ms number 否 15000 服务器响应超时时间,单位为毫秒 (等待首字节的时间)
dns_cache_timeout_sec number 否 120 DNS 缓存 TTL,单位为秒 (最大值: 240)
followRedirects number 否 disabled 最大重定向跟随次数 (0-20)。省略则禁用。
tryJsonData boolean 否 false 若可能,将 response body 解析为 JSON
returnBuffer boolean 否 false 返回原始 buffer 而非解码后的字符串
data any 否 - 请求 body (字符串或对象,自动序列化为 JSON)
proxy string 否 - 来自先前 response 的 proxy ID,用于固定相同的出口。原样传回该不透明字符串即可。原始 proxy 地址会被拒绝并返回 400 Invalid proxy format。部分 ID 无法固定: 参见 固定出口。
browser string 否 Chrome 伪装的浏览器: Chrome, Edge, Safari, Firefox 或 Tor。参见 浏览器配置文件。
os string 否 - 伪装的操作系统: Windows, macOS, Android 或 iOS。系统族名称可匹配其任意版本。
version string 否 newest 伪装的浏览器版本,如目录中所列。若有多个匹配项,则选用最新版本。
profile string 否 - 来自 GET /api/profiles 的确切 profile id,用于替代上述三个字段。
validate object 否 - 响应校验规则 (见下文)

浏览器配置文件

默认情况下,request 会伪装为最新的 Google Chrome。某些目标仅接受特定浏览器而拒绝其他浏览器,因此可通过 browser、os 和 version 筛选已测量的配置文件目录,或通过 profile 按 id 直接指定。

{
  "method": "GET",
  "url": "https://example.com",
  "browser": "Firefox",
  "os": "Windows"
}

规则:

  • 筛选需要 unblocker(默认开启)。若 unblocker 关闭,则不会发送任何浏览器 header,因此请求会被拒绝,而不是处于部分应用状态。
  • 当多个 profile 匹配时,优先使用最新版本。
  • 如果目录中不存在该组合,将返回错误并列出可用项;未知的 profile id 会返回 unknown profile '<id>'。请求绝不会伪装成其他浏览器发送。
  • 这四个字段同样适用于 POST /proxy/ 的 request 对象。

GET /api/profiles 会返回完整目录,且无需 API key:

{
  "profiles": [
    { "id": "...", "browser": "Chrome", "version": "...", "os": "...", "osFamily": "macOS" }
  ],
  "default": "..."
}

构建选择器时,osFamily 是用于过滤的值;os 保留发布名称以供展示。

验证规则

validate 对象用于定义成功和失败的条件。如果命中 fail 条件,request 将被视为失败。如果设置了 accept 条件,则仅匹配的 response 会被视为成功。

{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}
字段 类型 说明
validate.status.accept number[] 允许接收的 HTTP 状态码
validate.status.fail number[] 判定拒绝的 HTTP 状态码
validate.headers.accept object 在任意重定向跳转中只要有一对匹配,response 即判定通过。名称和值不区分大小写,支持部分文本匹配。
validate.headers.fail object 触发失败的 header 键值对
validate.data.accept string[] 当 body 包含这些字符串中的至少一个时,response 判定通过
validate.data.fail string[] response body 中触发失败的字符串

示例

curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://example.com/products",
    "timeout_ms": 10000
  }'

Response:

{
  "status": 200,
  "headers": [{"result": {"version": "HTTP/2", "code": 200, "reason": ""}, "content-type": "text/html", "server": "...", "set-cookie": ["session=abc", "tracker=xyz"]}],
  "data": "<!doctype html>...",
  "total_time": 0.342
}

当目标在返回响应主体前执行 Bot 检测时,响应中还会携带一个 defense 对象,指明供应商名称以及检测是否已通过:

{
  "status": 200,
  "data": "<!doctype html>...",
  "total_time": 3.61,
  "defense": {
    "vendor": "sgcaptcha",
    "solved": true,
    "present": ["sgcaptcha"],
    "ms": 3412,
    "cookie": "_I_=<clearance>"
  }
}
字段 类型 说明
status number 目标返回的 HTTP 状态码
headers array 每个重定向跃点一个对象。每个对象均包含一个包含状态行和所有 response header 的 result 字段。多值 header (Set-Cookie, Link, WWW-Authenticate) 以字符串数组形式返回。
data string/object 响应体 (若 tryJsonData 为 true 则为 JSON)
total_time number 总请求耗时,单位为秒
proxy string 请求所经 proxy 的编码 ID (仅在请求中提供了 proxy 时返回)。在后续调用中复用它可以固定相同的出口。
defense object 当目标对此请求运行了 Bot 检查,或使用站点自身 cookie 重试并获取到响应体时出现。defense.solved 表示是否通过了检查,defense.retry 表示重试是否获取到了内容。查看 站点检查 了解所有字段和系统的完整列表。
error string 请求失败时的错误信息

Proxy 请求

POST /api/proxy/

通过轮换 proxy 路由您的请求,失败时自动重试。可选将节点选择限定在目标可见的出口国家范围内。

请求体

参数 类型 必填 默认值 描述
request object 是 - 单个 request body (字段与上文的 Single Request 相同)
timeout_ms number 否 45000 所有尝试的总超时时间,单位为毫秒 (最大值: 120000)
maxTries number 否 5 失败次数达到此阈值后,FourA 将停止发起新的尝试 (最大值: 90)。由于尝试是并行运行的,实际完成的次数可能会略多于该数值。
ignoreProxies string[] 否 - 需要从轮换中排除的 proxy ID 列表 (使用之前 response 返回的 ID)
exitCountries string[] 否 - 目标可见的双字母国家代码严格允许列表 (例如 ["CZ", "GB"])。传入的值会自动去除首尾空格、转为大写并去重。标准池中未知国家的出口会被排除,且标准池绝不会回退到未请求的国家。premium 出口同样会从所列国家之一发起。
exitClass string 否 - standard 或 premium。当标准池在受保护的目标上遇到困难时,premium 允许 request 升级到 premium 出口。需要包含 premium 出口的套餐计划。
exitState string 否 - 出口所在的地区。需要设置 exitClass: premium 且在 exitCountries 中仅指定一个国家。请参阅 Exit location。
exitCity string 否 - 出口所在的城市。需要设置 exitClass: premium 且在 exitCountries 中仅指定一个国家。
exitAsn string 否 - 出口所在的网络 (按 AS 号指定),例如 8866。需要设置 exitClass: premium 且在 exitCountries 中仅指定一个国家。
exitOs string 否 - windows、android、ios 或 mac: 该地址所属的设备类型。需要设置 exitClass: premium。
exitLifetimeMin integer 否 - 出口保持其地址的分钟数,范围为 3 到 1440。需要设置 exitClass: premium。

exitCountries 作用域

选择机制使用最新可用的目标可见国家元数据,通常在大约十分钟内刷新。这并不是 request 期间的实时地理位置查询。请勿从 proxy 主机地址推断提供服务的国家。

如果当前池中没有与所请求国家匹配的节点,且 request 未指定 exitClass: premium,则 response 将返回带有错误包装的 HTTP 200:

{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}

保留请求的 scope 并在稍后重试。仅在工作流的国家/地区要求明确发生变更时,才进行更改或放宽。

示例

curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 3,
    "exitCountries": ["CZ", "GB"],
    "request": {
      "method": "GET",
      "url": "https://example.com/prices"
    }
  }'

Response:

{
  "status": 200,
  "headers": [{"result": {"code": 200}, "content-type": "text/html", "set-cookie": ["a=1", "b=2"]}],
  "data": "<!doctype html>...",
  "total_time": 1.204,
  "proxy": "A1B2C3",
  "exitCountry": "CZ",
  "total": 2.341
}
字段 类型 说明
proxy string 所使用 proxy 的编码标识符。在 Single 或 Browser request 中将其作为 proxy 字段传入以复用,或在下一次 Proxy request 中通过 ignoreProxies 跳过它。
exitCountry string 处理该 request 的 proxy 所在目标可见两位国家代码。仅当 request 设置了 exitCountries 时存在,无论由哪类出口节点处理。在信任 response 之前,请务必核对它是否属于您请求的代码之一。
exitClass string 处理此 request 的出口节点类别,当 request 指定了类别并在成功响应时返回。premium 表示由高级出口返回 body;standard 表示由标准池返回。失败的调用未处理任何内容,因此不包含 exitClass;请查看其 attemptReport 获取各次尝试遇到的情况。
total number 外部实际耗时,单位为秒(浮点数)。包含 proxy 选择、重试以及成功的尝试。total_time 仅指内部 request 耗时;total 始终 >= total_time。
profile string 轮换选择的浏览器配置,仅在它与您请求的配置不一致时出现。缺失表示 request 完全按原样发出。在后续调用中将该 ID 作为 profile 传回,以保留正常工作的浏览器。
error string request 失败时的错误信息。发生作用域未命中时,code 为 no_eligible_proxy,且 details.exitCountries 会回显规范化后的作用域。
attemptReport object 存在于每一个失败的 Proxy 调用中。统计尝试过程中遇到的情况,以避免被封禁的池、失效的池以及从未匹配的 validate 规则显示为完全相同的错误。详见下文。
request object 存在于失败的 Proxy 调用中:包含 FourA 运行的 request,已填充默认值并保留您发送的原样 ignoreProxies。

所有 Single Request response 字段均包含在内,其中包括 defense:遇到 Bot 检查的 proxy 尝试会以与 Single 相同的方式报告。

Proxy 调用失败的原因

无论尝试过程如何,Download maxTry limit reached 的显示内容都是一致的,因此每个失败的 Proxy response 都会在错误信息旁附带一个 attemptReport:

{
  "error": "Download maxTry limit reached",
  "attemptReport": {
    "total": 25,
    "noResponse": 0,
    "defense": 0,
    "contentRejected": 25,
    "statusRejected": 0,
    "other": 0,
    "vendors": [],
    "profilesTried": ["default"],
    "summary": "25 attempt(s): 25 returned HTTP 200 with no defense present and were rejected only by your validate.data - the page was fetched, your content rule did not match it"
  },
  "total": 34.812
}
字段 类型 说明
total integer 尝试次数
noResponse integer 出口节点未响应,因此从未访问到目标站点
defense integer 站点已响应,且在响应中识别出 Bot 验证
contentRejected integer HTTP 200,无 Bot 验证,仅被您的 validate.data 拒绝
statusRejected integer 站点已响应,无 Bot 验证,被您的 validate.status 拒绝
other integer 已响应,且不属于上述任何情况
vendors string[] 在任务中任一环节识别出的 Bot 验证供应商
profilesTried string[] 任务发送的浏览器 Profile,按首次使用顺序排列。default 表示您的 request 未作修改直接发出。
summary string 基于计数值生成的一句话描述,可安全记录到日志

error 字符串保持不变,因此匹配该值的客户端仍可正常工作。针对各项计数的处理方式:Proxy Request 耗尽尝试次数的原因。

exitClass

某些目标无论尝试多少次,都会拒绝标准池中的出口节点。exitClass: premium 会指示 Proxy,此类 request 除了在标准池内轮换外,还可以升级至 premium 出口。

{
  "exitClass": "premium",
  "request": { "method": "GET", "url": "https://example.com/report" }
}

发送前有三点需要了解。

**它是一种配额,而非强制指令。**标准池仍会优先竞速获取响应,且通常会胜出。仅当标准池在请求上消耗了一定的预算重试,或者目标明确拒绝时,高级出口才会介入。在尝试任何高级出口前,若标准池已成功响应,则计为普通成功,不消耗高级流量。一旦尝试了高级出口,其流量即被计费,具体说明如下。

**高级出口会严格遵循 exitCountries。**指定国家/地区列表时,高级出口会从其中某个国家/地区发出,响应中的 exitCountry 会注明该国家/地区,机制与标准池相同。

**响应会告知实际提供服务的资源。**指定 class 时,响应会返回 exitClass:

{
  "status": 200,
  "exitClass": "premium",
  "proxy": "Y2QXVK",
  "data": "..."
}

premium 表示响应正文由高级出口返回。standard 表示由标准池返回。当无法获取高级出口,或者当前账单周期内套餐包含的高级流量(加上额外购买的流量)已耗尽时,也会返回该结果。这两种情况均非错误,你可以基于每个 request 对账高级流量,而无需依赖月度汇总数据。该值也会通过 X-FourA-Exit-Class 响应 header 返回(参见 Response Headers)。

高级流量按网络传输量统计。 高级尝试会统计其通过网络发送和接收的实际数据量(包含传输过程中的压缩与加密开销),无论最终是否成功返回页面。当另一个出口已返回响应时,仍在进行的尝试会立即终止,其截至终止前产生的流量同样计入统计。高级流量计入你的高级配额,同时也包含在总带宽中:同一批字节会被分别上报两次,但不会累加。当高级出口交付页面时,该出口的流量即为该 request 的全部流量,因此该页面不会再计入标准流量。你的 Usage & Limits 页面会显示总流量、高级流量占比以及用于衡量的基准高级配额。

省略该字段或发送 standard 都会使 request 保持在标准池中运行:仅 premium 允许使用高级出口。显式指定 class 的成功 request 会在 response 中返回 exitClass,省略该字段的 request 则不会返回。

额度耗尽不是错误。 配额用尽后,指定 premium 的 request 仍可继续工作:由标准池提供服务,且 response 标识为 standard。唯一的例外是指定了 exit location 的 request:标准池无法满足此要求,因此会被拒绝。

exitClass: premium 需要包含高级出口的套餐。在未包含高级出口的套餐上,request 绝不会消耗高级出口:在执行任何操作之前,它会被直接拒绝并返回 403 及 X-FourA-Limit: plan_limit_premium(参见 Rate Limits)。

出口位置

高级出口可以从特定国家/地区内的某个位置发出,并根据你的需求持续保留其地址:

{
  "exitClass": "premium",
  "exitCountries": ["BG"],
  "exitCity": "sofia",
  "exitLifetimeMin": 15,
  "request": { "method": "GET", "url": "https://example.com/" }
}

response 会指明出口节点以及请求流出的国家或地区:

{
  "status": 200,
  "exitClass": "premium",
  "exitCountry": "BG",
  "proxy": "1EM4GZY",
  "data": "..."
}

该 proxy ID 保留所有这些配置。将其传递给 Single 或 Browser,request 将从同一位置发出,无需附带其他字段。请参阅 Pinning an Exit。

规则:

  • 包含 exitState、exitCity、exitAsn、exitOs 和 exitLifetimeMin 中的任意一项,都会仅通过高级出口发送 request。标准池不会进行尝试,因为它无法支持这些选项。
  • 它们需要 exitClass: premium。若缺少该字段,request 将被拒绝并返回指出该字段的 400 错误。
  • exitState、exitCity 和 exitAsn 仅存在于单一国家/地区内,因此需要在 exitCountries 中精确指定一个国家/地区。exitOs 和 exitLifetimeMin 可对应多个国家/地区:出口会采用其中之一,并在 response 的 exitCountry 中指明。
  • exitState、exitCity、exitAsn 和 exitOs 需要同时包含地理定位和高级出口的套餐。
  • 若无剩余高级流量,request 将被拒绝并返回带有 X-FourA-Limit: plan_limit_premium 的 403 错误,因为标准池无法提供服务。
  • 如果该位置没有高级出口响应,response 将是一个类似于 exitCountries scoping 下的错误载荷,包含错误 No premium exit answered for this request 和 code: no_eligible_proxy。如果您发送了国家/地区列表,则会包含 details.exitCountries。

这些术语与 proxy port 中用于 state、city、asn 和 os 的术语一致。

浏览器配置文件轮换

Proxy 会轮换出口。当目标站点拒绝 FourA 呈现的浏览器而非其来源出口时,Proxy 还会切换到目录中的另一个浏览器系列。它不会增加尝试次数:轮换只会改变重试时发送的内容,绝不会决定是否发生重试。

Proxy 还会临时记住站点上次接受的系列,因此后续对同一站点的调用可以直接使用该系列开始,而非使用默认系列。与轮换选择的任何系列一样,response 会在 profile 中指明它。

内部 request 上显式设置的 profile、browser、os 或 version 绝不会被覆盖;自带 User-Agent 或 Cookie header 的 request 也同样不会被覆盖,因为 clearance 与获取它时所用的签名绑定。


浏览器请求

POST /api/browser/

在 Chrome 浏览器实例中打开您的 URL。页面加载完成,JavaScript 执行完毕,您将获得完整渲染的 HTML 以及 cookie 容器。

请求体

参数 类型 必填 默认值 描述
url string 是 - 目标 URL
headers object 否 - 键值对形式的自定义 header
cookies array 否 - 要设置的 Cookie:[{name, value, domain?}]
userAgent string 否 - 自定义 User-Agent 字符串
unblocker boolean 否 true 完成页面加载前要求的检查(质询页面或类似的关卡)。默认开启。设置为 false 则按原样渲染页面返回的任何内容,包括质询页面。
proxy string 否 - 来自先前响应的 proxy ID,用于固定相同的出口。请原样传回该不透明字符串。原始 proxy 地址会被拒绝并返回 400 Invalid proxy format。
timeout_ms number 否 30000 页面加载超时时间,单位为毫秒(最大值:120000)
checkStatus number 否 - 预期的 HTTP 状态码(如果不一致则请求失败)
checkText string 否 - 渲染后的页面中必须出现的文本
lean boolean 否 false 排除图片、字体和媒体文件,以及发往已知广告、分析、授权同意和社交服务的请求。页面本身、其自身的脚本和样式,以及验证步骤所需的任何内容仍会加载。可用于降低页面消耗的流量,例如通过固定的高级出口。

将浏览器时钟与出口匹配

页面可以读取浏览器的时区,并将其与检测到的 IP 所在国家/地区进行比对。时区不匹配是 Bot 检测程序成本最低的识别信号之一,而消除这种不匹配无需任何成本。

你无需执行任何操作。FourA 会从 proxy ID 中读取国家/地区,浏览器则会报告属于该国家/地区的时区。

  • 这是出口国家/地区,即目标看到的国家/地区,而不是 proxy 的托管地。这两者经常不一致,足以产生影响。
  • 当 FourA 不知道出口的国家/地区时,它会保持浏览器时钟不变,而不是凭空猜测。当你在 Proxy Request 上使用 exitCountries 请求了指定国家/地区时,高级出口就具有已知的国家/地区。
  • 只有时钟会跟随国家/地区调整。Accept-Language 以及站点提供的内容保持不变,因此页面不会突然为你切换语言。

userAgent 参数

发送 userAgent 后,页面、其 Worker 以及目标看到的都将是该精确字符串。FourA 还会据此推导出匹配的 Client Hints(sec-ch-ua、sec-ch-ua-platform、navigator.platform,以及检测程序按名称请求的高熵值),确保请求不会在 header 中声明一种浏览器,而在 JavaScript 中呈现另一种。

响应中的 userAgent 即为实际呈现的值。这在重放通过凭证时非常重要:cf_clearance cookie 与获取它的出口以及 User-Agent 绑定,因此请传回响应所报告的字符串,而不是你认为使用的字符串。请参阅 Site checks。

发送非 Chromium 字符串(例如 Firefox User-Agent),系统会原样呈现,且不附加 Chromium 品牌列表。

示例

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/spa-app",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'

Response:

{
  "status": 200,
  "headers": {"content-type": "text/html"},
  "body": "<!doctype html>...",
  "cookies": [{"name": "session", "value": "abc123", "domain": "example.com", "path": "/", "expires": 1735689600, "httpOnly": true, "secure": true, "sameSite": "Lax"}],
  "userAgent": "Mozilla/5.0...",
  "defenseSolved": true,
  "defenses": {"present": ["cloudflare"], "cleared": ["cloudflare"]}
}
字段 类型 说明
status number 目标返回的 HTTP 状态码
headers object 响应 headers
body string or object 完整渲染的页面内容。当 content-type 为 HTML 时为字符串形式的 HTML;当页面返回 JSON 并被自动解析时为对象。
cookies array 来自页面的完整 cookie 对象数组。每个 cookie 均包含 name、value、domain、path、expires、httpOnly、secure、sameSite 以及其他 cookie 属性。
userAgent string 所使用的浏览器 User-Agent
defenseSolved boolean 若本次调用遇到并成功绕过机器人防御则为 true,否则为 false。用于决定本次调用扣除 5 点还是 10 点积分。
defenses object present 列出页面加载期间识别出的所有供应商,cleared 列出最终页面已获得放行凭证的供应商。某个供应商可能出现在 present 中,但从未出现在 cleared 中。请参阅 站点检测。
proxy string 本次请求所通过代理的已编码 ID(仅当请求中提供了 proxy 时返回)。可在后续调用中复用它以保持相同的出口。
error string 请求失败时的错误信息

固定出口

在 Single 或 Browser 请求中传入 proxy 值可以固定先前调用所使用的出口。请原样回传该不透明 ID,切勿传入代理地址。来自指定了国家、地点或生命周期的 Proxy 请求的 ID 会保留这些设置,因此固定请求无需传入其他字段。

以下三种值会被拒绝,均返回 400 状态码:

错误 含义
Invalid proxy format 该值并非 FourA 颁发的 ID。直接传入原生代理地址会触发此错误。
Proxy not found ID 已成功解码,但不再解析到活跃的出口。请通过新的调用获取新 ID。
Managed exit: this proxy id cannot be pinned to a request 出口存在,但 FourA 不会为指定请求保留它。当您的套餐中已无可用高级流量额度时,高级出口的 ID 会触发此错误。可复用返回该 ID 的会话,或通过 POST /api/proxy/ 发起调用并采用其自动选择的出口。

固定的高级出口按高级流量计费。响应中包含 X-FourA-Exit-Class: premium,方便您按请求进行查看。无论目标站点是否返回您所需的页面,该出口传输的流量都会计入您 用量与限制 页面中的高级流量以及总带宽。固定出口需要您的套餐支持高级出口且尚有剩余额度;否则该 ID 将被拒绝并返回上述 managed-exit 400 错误。

HTTP 状态码

状态码 含义
200 请求已完成(检查内部 status 以获取目标响应)
400 无效的请求体、参数、目标 IP 位于私有/保留网段、目标指向 FourA 自身的 API 主机、URL 内部包含未编码的空格(Single、Proxy、Auto),或无法固定 proxy ID。在 Single、Proxy 和 Browser 上,未通过验证的字段会明确标注:Invalid request: <field>: <reason>,最多五个字段。不计费。Auto 对相同的错误返回 HTTP 200 并在响应体中包含 status: 400。
401 缺少 API key 或 API key 无效
403 该 endpoint 或参数未包含在您的套餐中。X-FourA-Limit 会指明具体项:plan_limit_feature 或 plan_limit_premium。
404 Not Found:该路径下不存在 endpoint。
413 JSON 请求体超过 100 KB。响应不是 JSON,且不包含 X-FourA-Request-Id。
429 套餐额度限制(已设置 X-FourA-Limit)或平台的共享每分钟配额(无 header)
500 内部服务器错误
502 Upstream unavailable:FourA 无法连接至其引擎。Malformed JSON from backend:引擎已响应,但 FourA 无法读取回复。请重试。
503 服务暂时停用或已达容量上限,当 FourA 暂时无法验证您的密钥时返回 API key check temporarily unavailable(请在 Retry-After 后重试),或在引擎重启期间返回 Backend service unavailable。在 Browser 上,当所有实例繁忙时,页面最多等待 10 秒以获取空闲浏览器,如果超时仍无空闲实例则返回 Backend service unavailable。
504 Upstream timeout。引擎未在此请求的时间预算内完成。请增大 timeout_ms 或重试。

后续步骤

更新于: 2026年11月13日