智能获取 (Auto)

您向 FourA 提供一个 URL 以及一条用于定义真实页面应包含内容的 validate 规则。FourA 会处理其余工作：它沿着成本感知的阶梯逐级尝试，在第一个返回符合规则的响应阶梯处停止，并按主机记住有效配置，以便对同一站点的下一次调用保持低成本。

本指南将解释 auto 的底层机制、适用场景以及如何解析其响应。有关参数参考，请参阅 API Endpoints。

核心概念

大多数抓取方案要求您预先选择引擎。Single 最快，Proxy 增加了轮换，Browser 负责处理 JavaScript。一旦预判错误，就会浪费额度或被拦截。

Auto 改变了这种模式。您只需声明成功条件 (validate)，而无需指定方法。FourA 会逐级向上尝试，直到某一阶梯成功：

低成本探测（single，直接通过 FourA 自身网络发起）
Browser，直接通过 FourA 自身网络发起，支持 JavaScript 并在站点发起质询时调用求解器
轮换 proxy single
通过 proxy 运行 Browser，用于处理难度最高的目标

只要某个阶梯返回符合您 validate 规则的响应，Auto 就会立即停止。

还有一个阶梯独立于该顺序之外。当出口节点能够访问站点但站点拒绝了您请求的深层 URL 时，auto 会通过同一出口获取该站点的入口页面，保留入口页面分发的 cookie，并携带这些 cookie 再次请求您的 URL。这就是 warmup 阶梯。它仅在 URL 深于站点根路径且直接尝试失败后才会运行，并且它只会增加成功的可能，绝不会产生负面影响。

forceProxy 默认为 true，因此阶梯 1 和 2 会被跳过，目标站点绝不会看到 FourA 自身的地址。大多数调用随后会在阶梯 3 或通过重放预热会话完成。当您确知目标对纯净地址的接受度高于轮换地址时，请设置 forceProxy: false，阶梯 1 和 2 将恢复启用。

发送内容

最少需要提供一个 URL 和一个 validate 子字符串。Auto 本身能识别常见的质询页面，但如果没有 validate.data.accept，它无法区分真实页面与未知的验证页面，也无法判断页面加载时是否缺少您的内容，从而可能将两者都误判为成功。

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"]}}
  }'

可选配置项（完整详情请参阅 endpoint 参考）：

returnSession（默认 true）：返回胜出的 { proxy, cookies, userAgent } 以便重放。
forceProxy（默认 true）：跳过直连出口阶梯。仅在确定目标站点对纯净 IP 比对免费轮换 proxy 更友好时设置 false。
timeout_ms（默认 120000）：整个调用的总预算。阶梯机制会将其分配到各个阶梯。
ignoreProxies：每次子尝试中需要规避的 proxy ID。
followRedirects（默认 5）：低成本阶梯上的最大重定向次数。

返回内容

{
  "status": 200,
  "data": "<!doctype html>...",
  "headers": [{"content-type": "text/html"}],
  "meta": {
    "rung": "cache",
    "solved": false,
    "attempts": 1,
    "credits": 2
  },
  "session": {
    "proxy": "A1B2C3",
    "cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
    "userAgent": "Mozilla/5.0..."
  }
}

需要读取的三项内容：

status 和 data：目标的响应内容。data 在每个阶梯上均为文本：即使由浏览器提供服务，JSON 页面也会作为 JSON 字符串返回，因此需要在您的端进行解析。status 是目标的 HTTP 状态，而不是调用 FourA 的传输状态。对于 single 和 proxy 阶梯，headers 是一个逐跳数组。对于 browser 阶梯，headers 是一个扁平对象。
meta：阶梯执行操作的跟踪记录，阶梯启动后会出现在每个 response 中。meta.rung 标明交付 response 的步骤，meta.attempts 统计子调用尝试次数，meta.solved 标记是否完成了质询页面，meta.credits 是调用的总花费（与 X-FourA-Credits header 中的数值相同）。
session：成功破解目标的三元组 { proxy, cookies, userAgent }。使用它通过 /api/single/ 或 /api/browser/ 对同一主机进行重放。

只要阶梯运行过，Auto 就会返回 HTTP 200，即使每个阶梯都失败了也是如此。请读取 body 中的 status 和 error 来了解实际情况，而不是根据传输状态码判断。来自 /api/auto/ 的非 200 响应意味着调用根本没有到达阶梯：401 表示密钥无效，400 表示 body 不是有效的 JSON 或目标位于私有网络中，502、503 或 504 则表示服务无法接收调用或已超时。Auto 在网关处不占用 slot，因此平台的共享限制不会拒绝调用本身：当限制拒绝阶梯发出的调用时，返回的内容为 HTTP 200，并在 body 中附带 status: 429 或 503 以及 retryAfter。未通过验证的字段也会以 HTTP 200 返回，并附带 status: 400。阶梯内部达到的计划限制同样以 HTTP 200 返回，并在 body 中包含拒绝信息（请参阅当您的计划限制遇到阶梯时）。

使用 Session 进行重放

在 auto 返回 session 之后，您可以直接进入 Single 或 Browser 处理同一主机上的后续页面。无需重新爬升阶梯，也无需重新探测。

import requests

API = "https://eu.api.foura.ai"
KEY = "YOUR_API_KEY"
H = {"X-API-Key": KEY, "Content-Type": "application/json"}

# 1) First call: let auto figure it out.
r = requests.post(f"{API}/api/auto/", headers=H, json={
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}},
}).json()

session = r["session"]
proxy = session["proxy"]
user_agent = session["userAgent"]

# 2) Follow-up pages: replay through single with the same proxy + UA.
for sku in ("43", "44", "45"):
    r = requests.post(f"{API}/api/single/", headers=H, json={
        "method": "GET",
        "url": f"https://example.com/product/{sku}",
        "proxy": proxy,
        "headers": [["User-Agent", user_agent]],
    }).json()
    print(sku, r["status"])

Session 的有效期完全取决于目标站点的策略。某些站点会将通关凭据与 cookie 绑定数小时，而另一些站点每隔几分钟就会轮换。如果重放请求再次触发验证挑战，只需再次调用 /api/auto/ 进行刷新。

何时使用 Auto

适合使用 Auto	适合手动使用 single、proxy 或 browser
针对新目标站点且不确定其反爬需求	已经明确适用的引擎
希望通过单次调用自动处理 direct、proxy 和 browser 降级重试	需要完全控制单次调用的重试机制与超时时间
能够接受首次调用花费数秒进行策略探测	首次调用的延迟要求高于自动化发现
需要获取已学习的 session 以便低成本重放	正在对已知正常的目标站点优化高频循环调用

Auto 并不总是成本最低的选择。如果已知目标站点可以通过 single + unblocker 正常访问，直接调用 Single 只需 2 个点数且延迟可控。而在相同目标上使用 Auto，则会按阶梯探测实际消耗计费，若站点触发降级升级，成本可能会更高。

Validate 用于告知 Auto 什么是“成功”

最重要的参数是 validate。如果不设置该参数，Auto 仅会拦截它能识别的挑战页面，因此未知的验证页面或返回 HTTP 200 的空页面都会被误判为正常内容。

通过 validate.data.accept 指定仅真实页面才包含的子字符串：

{
  "validate": {
    "data": {
      "accept": ["sku-42-add-to-cart", "Customer reviews"]
    }
  }
}

对于 JSON API，接收你预期的字段名称：

{
  "validate": {
    "data": { "accept": ["\"products\":["] },
    "status": { "accept": [200] }
  }
}

对于确实会合法返回非 200 状态码的站点（例如需要忽略的国家/地区限制，或未登录 endpoint 上预期的 403），可以通过 validate.status.accept 予以允许：

{
  "validate": {
    "status": { "accept": [200, 451] }
  }
}

若没有 validate，对于未识别为质询的页面，auto 会回退到“HTTP 200 = 成功”逻辑，因此无法捕获目标站点返回 200 状态码的未知验证页面。

读取 `meta.rung` 以了解执行过程

meta.rung 是最有价值的调试信号。具体取值：

probe - 通过低成本 direct request 成功解决。成本最低的路径。
proxy - 需要轮换 proxy 才能通过。
browser - 需要完整的浏览器渲染，可能包含质询求解。
cache - 复用了先前 auto 调用的预热 session。重复调用时的最低成本路径。
warmup - 站点允许访问入口页但拦截了深层 URL，因此 auto 先获取入口页，保留其下发的 cookie，并携带这些 cookie 再次请求。该层级存储的 session 不绑定特定出口，后续调用即可命中低成本层级。
fail - 所有层级均未生成符合您规则的 response。

meta.solved: true 表示在调用期间遇到并完成了质询页面。meta.attempts 是成功前的子调用重试次数。有关其背后的详细信息，请查看 single 和 proxy 层级返回的 defense 字段：参见站点检查。

如果您预期为 probe 但站点始终停留在 browser，请考虑更严格（或更宽松）的 validate 规则是否能让更低成本的层级通过。请注意，forceProxy 默认为 true，因此除非显式关闭，否则会跳过直连出口探测。

错误与边界情况

当 auto 失败时，response 会携带 status（通常是最后一个失败层级的状态）以及一个 error 字符串：

{
  "status": 502,
  "error": "could not find a working exit for the target",
  "attempts": 7,
  "meta": {
    "rung": "fail",
    "solved": false,
    "attempts": 7,
    "credits": 47
  }
}

status 是自动重试最终拒绝时目标网站的响应，例如 403。如果所有尝试均未获取到目标网站的响应，通常为 502 或 504，且 error 会说明是未找到可用出口还是 timeout_ms 预算已耗尽。status: 0 仅表示目标主机名无法解析，该响应不包含 meta，因为阶梯重试从未启动。

检查 meta.attempts 和 meta.credits 可以查看预算消耗情况。如果浏览器阶梯尝试后 meta.attempts 较高且 meta.rung 为 fail，目标可能需要更长的 timeout_ms、更严格的 validate 规则，或者当前无法通过轮换 proxy 访问。

套餐限制与阶梯重试机制

Auto 的子调用是在您的 API Key 下发起的普通 Single、Proxy 和 Browser 请求，因此适用您的套餐限制。阶梯重试机制会读取拒绝响应中的 X-FourA-Limit 代码，并对两种情况进行不同处理。

阶梯中的某一梯级关闭不会影响其他梯级。 plan_limit_browser_daily（当天的 Browser 请求已耗尽）和 plan_limit_concurrency（该 endpoint 并发请求数已达套餐上限）只会关闭对应梯级。Auto 会继续尝试其他梯级，因此只要轮换出口或预热 session 可以获取内容，您仍能收到页面响应，且已尝试的出口不会因为套餐限制导致的拒绝而被标记失效。没有任何出口会被封禁，也不会丢弃任何 session。

账户额度耗尽将终止阶梯重试。 plan_limit_credits、plan_limit_bandwidth、plan_limit_rate、plan_limit_feature 和 plan_limit_premium 无法通过切换其他梯级解决，因此 auto 会立即返回，避免继续消耗额度。拒绝信息会在响应 body 中返回，包含子调用的状态以及直连 endpoints 所使用的相同 reason 字段：

{
  "status": 429,
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z",
  "meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}

来自子调用的完整拒绝 body 会被透传，外加 status 和 meta。请从 body 中读取 status，而不是根据传输状态判断：此处 auto 仍会返回 HTTP 200，因为阶梯策略已执行完毕。plan_limit_feature 或 plan_limit_premium 拒绝也会以相同方式返回并带有 status: 403。被拒绝的子调用不会产生扣费，因此 meta.credits 仅计算实际到达目标站点的阶梯尝试。

单次 auto 调用在阶梯升级过程中可能会占用多个槽位，因此并行批量执行 auto 调用时，达到并发上限所需的调用量会比预期更少。Run Requests in Parallel 介绍了如何评估批处理规模。

Auto 不支持的功能

它不会改变法律合规限制。如果某个站点拒绝了 FourA 能访问的所有出口，auto 将直接返回该拒绝结果。
它不会缓存内容。每次调用仍会直接请求目标站点。"预热会话" 指的是 proxy 和 cookie，而非 response。
它在 Activity Log 中仅占用一行记录，对应你收到的 request id，并显示其所有子调用消耗的点数总和。展开该记录即可查看 auto 代表你发起的 Single / Proxy / Browser 子调用尝试，每项尝试均有独立的结果。这些调用会计入你的 Single、Proxy 和 Browser 配额限制，绝不会计入你的 request 次数或成功率统计。