AISA Crawler Access Verify API

概述

/api/v1/access/verify 是 AISA 平台的访问验证 API，实现 HTTP 402 Payment Required 标准，支持价格意图（Price Intent）机制。

核心特性

价格意图支持：自动支付（推荐）、价格发现、精确价格、最高价格四种模式
多种认证方式：自定义 Header（推荐）或 Body 参数
参数别名：agent- 和 crawler- 前缀可互换
数据兼容：与旧版 API 共享数据表
标准化响应：统一错误码和交易信息格式

设计目标
为 AI Agent 和爬虫访问内容网站时，提供付费访问控制和价格协商机制。

接口信息

接口地址	`/api/v1/access/verify`
完整 URL	`https://cdn.aisa.one/api/v1/access/verify`
请求方法	`POST`
Content-Type	`application/json`
支持协议	HTTP 402 Payment Required

认证方式

API 支持两种认证方式，推荐使用自定义 Header：

方式 1: 自定义 Header（推荐）

HTTP

POST /api/v1/access/verify
X-AISA-Crawler-Token: 
Content-Type: application/json

{
  "publisherDomain": "example.com",
  "resourceUrl": "/premium/article.html"
}

方式 2: Body 参数

JSON

{
  "publisherDomain": "example.com",
  "resourceUrl": "/premium/article.html",
  "crawlerToken": "crawler_abc123..."
}

认证优先级
如果同时提供两种认证方式，优先级为：X-AISA-Crawler-Token Header > Body 参数

⚠️ 关于 Authorization: Bearer 头
2026-04 安全评审后已不再支持以 Authorization: Bearer <crawler-token> 传递 crawler token。原因：Authorization 是 HTTP 通用鉴权头，经过中间件（nginx / Cloudflare / WAF / 日志平台 / AI 网关）时常被特殊处理或记录，容易把 token 意外泄漏到日志、缓存 vary、上游重写等场景。已迁移到自定义 X-AISA-Crawler-Token 头避开这些通用链路。
如仍以 Authorization: Bearer 发送，服务端将忽略该头，按"无 Token"走完整流程并返回 402 + invalid_token。

请求参数详解

必需参数

参数名	类型	必需	说明
`publisherDomain`	string	必需	Publisher 的域名或邮箱示例：`example.com` 或 `[email protected]` 说明：用于识别内容提供者，系统会查找对应的 Publisher 配置和访问规则
`resourceUrl`	string	必需	要访问的资源 URL 示例：`/premium/article-123.html` 或 `https://example.com/article` 说明：可以是相对路径或完整 URL，系统会根据 URL 模式匹配对应的访问规则
`crawlerToken`	string	必需*	Crawler 认证 Token 示例：`crawler_abc123...` 说明：如果已在 `X-AISA-Crawler-Token` Header 中提供，Body 中可省略格式：通常以 `crawler_` 或 `agent_` 开头的长字符串

可选参数 - 价格意图

参数名	类型	必需	说明
`crawlerAutoPrice`	boolean	推荐	自动支付模式（推荐）值：`true` 说明：自动按资源定价扣费，无需提前知道价格，余额足够即直接扣款。一次请求即可完成支付，无需价格协商优势：请求次数减半、处理速度更快、集成代码最简洁用途：AI Agent 自动化调用、批量内容访问、实时数据获取
`crawlerExactPrice`	string	可选	精确价格意图格式：`"USD 0.10"` 或 `"EUR 0.08"` 说明：表示只愿意支付精确的价格，价格必须完全匹配资源价格才会扣费用途：用于价格确认场景（先发现价格，再确认支付）
`crawlerMaxPrice`	string	可选	最高价格意图格式：`"USD 0.50"` 说明：表示愿意支付的最高价格，只要资源价格 ≤ 最高价格就会扣费用途：用于预算控制场景（设置价格上限，避免超支）
重要说明 1. `crawlerExactPrice`、`crawlerMaxPrice`、`crawlerAutoPrice` 三者互斥，只能提供其中一个 2. 如果都不提供，则为价格发现模式（返回 402 + 价格信息） 3. 支持参数别名：`agentExactPrice` / `agentMaxPrice` / `agentAutoPrice`

可选参数 - 其他

参数名	类型	必需	说明
`crawlerAgent` 推荐	string	可选	原始爬虫的 User-Agent 字符串示例：`Mozilla/5.0 (compatible; GPTBot/1.0; +https://openai.com/gptbot)` 重要：这是原始 AI 爬虫的 User-Agent，不是 ESA/CDN 网关的 User-Agent。如果通过 ESA 调用本 API，ESA 应将拦截到的原始爬虫 UA 填入此字段。用于爬虫类型识别和统计分析（正则匹配 → 识别为 GPTBot/ClaudeBot 等类型）。填法：ESA 已识别 → 填爬虫 identifier（如 `"gptbot"`）；ESA 未识别 → 填原始 UA 字符串与 HTTP Header `X-ESA-Original-Crawler-Agent` 配合形成双通道传递。完整识别流程详见爬虫识别（双通道）章节兼容旧参数名 `userAgent`，但建议迁移到 `crawlerAgent`
`metadata`	object	可选	附加元数据示例：`{"orderId": "order_123", "requestId": "req_456", "source": "agent-platform"}` 说明：可传递订单号、请求 ID 等信息，会保存在访问日志中
`timestamp`	number	可选	Unix 时间戳（秒）示例：`1738051200` 说明：用于测试场景，可指定记录时间。不提供则使用当前时间

参数别名支持

为了兼容不同场景，以下参数支持别名：

标准参数名	别名	说明
`crawlerToken`	`agentToken`	认证 Token
`crawlerAutoPrice`	`agentAutoPrice`	自动支付（推荐）
`crawlerExactPrice`	`agentExactPrice`	精确价格
`crawlerMaxPrice`	`agentMaxPrice`	最高价格

响应格式详解

响应结构

所有响应都采用统一的 JSON 格式，包含以下核心字段：

字段名	类型	必含	说明
`accessGranted`	boolean	是	是否授予访问权限 `true`：可以访问资源 `false`：不能访问（需付费/被拒绝/未授权）
`message`	string	是	人类可读的消息示例：`"Access granted - payment processed"` 说明：简短描述本次请求的结果
`statusCode`	number	是	HTTP 状态码示例：`200`, `402`, `403` 说明：对应的 HTTP 状态码（也会在 HTTP Response 中返回）
`timestamp`	string	是	响应时间戳格式：ISO 8601 格式（`2026-04-16T10:30:00Z`）说明：服务器处理请求的时间

付费相关字段（仅在涉及付费时出现）

字段名	类型	说明
`requiresPayment`	boolean	是否需要付费 `true`：需要付费才能访问通常在 402 响应中出现
`charged`	boolean	是否已扣费 `true`：本次请求已扣费成功通常在 200 响应（付费访问成功）中出现
`chargeAmount`	number	扣费金额示例：`0.10` 说明：实际扣除的金额（仅在扣费成功时出现）
`currency`	string	货币代码示例：`USD`, `EUR`, `CNY` 说明：价格的货币单位
`price`	number	资源价格示例：`0.10` 说明：该资源的定价（在 402 价格发现响应中出现）

价格意图相关字段

字段名	类型	说明
`priceDiscovery`	boolean	是否为价格发现模式 `true`：客户端未提供价格意图，服务器返回价格信息通常在 402 响应中出现
`priceTooHigh`	boolean	价格是否超过预算 `true`：资源价格超过了 crawlerMaxPrice 设置的上限通常在 402 响应中出现
`insufficientBalance`	boolean	余额是否不足 `true`：Crawler 账户余额不足以支付资源价格通常在 402 响应中出现

对象信息字段

字段名	类型	说明
`publisher`	object	Publisher 信息包含：`id`, `email`, `domain` 示例：`{"id": 1, "email": "[email protected]", "domain": "example.com"}`
`crawler`	object	Crawler 信息包含：`id`, `email`, `remainingBalance` 示例：`{"id": 123, "email": "[email protected]", "remainingBalance": 49.90}`
`rule`	object	匹配的规则信息包含：`id`, `urlPattern`, `accessMode`, `price`, `billingType` 示例：`{"id": 67, "urlPattern": "/premium/*", "accessMode": "pay", "price": 0.10}`
`transaction`	object	交易信息包含：`transactionUuid`, `timestamp` 示例：`{"transactionUuid": "txn-abc-123", "timestamp": "2026-04-16T10:30:00Z"}`
`crawlerIdentification`	object	爬虫识别结果（每个响应都会返回，AISA → ESA 透传）包含：`recognized` (boolean)、`identifier` (string) 示例：`{"recognized": true, "identifier": "gptbot"}` 未识别时：`{"recognized": false, "identifier": "unknown"}` 详细说明见爬虫识别（双通道）章节

错误相关字段

字段名	类型	说明
`onboarding`	string	爬虫引导注册页面 URL 示例：`https://cdn.aisa.one/cdn/guide.html` 仅在 402 响应中返回（包括 Token 缺失/无效、余额不足、价格发现等所有需要付费侧动作的场景）。该页面向爬虫说明 HTTP 402 Payment Required 协议、Pay-per-Crawl 付费模式，并引导爬虫注册 AISA 账户获取 Token。 ESA 可以将此 URL 返回给未注册的爬虫，引导其完成注册和充值流程。
`error`	string	错误码 402 错误为小写蛇形：`invalid_token`、`insufficient_balance`、`price_required`、`price_mismatch`、`price_too_high` 403 错误为小写蛇形：`access_blocked` 400/500 错误为大写：`MISSING_REQUIRED_FIELD`、`INVALID_PARAMETER`、`INVALID_PRICE_FORMAT`、`INTERNAL_ERROR` 说明：机器可读的错误标识，详见错误码细分章节
`missingFields`	array	缺少的必需字段示例：`["publisherDomain", "resourceUrl"]` 说明：仅在参数验证失败时出现

爬虫引导注册（Onboarding）

当爬虫未携带 Token、Token 无效或资源需要付费时，API 响应中都会包含 onboarding 字段，指向一个引导页面。该页面向爬虫/用户解释 HTTP 402 Payment Required 协议，说明按需付费模式，并引导其注册 AISA 账户。

注意（2026-04 起）：原来的 401 状态码已合并到 402， Token 缺失/无效场景对外统一返回 HTTP 402 + error: "invalid_token"。详见 HTTP 状态码章节。

响应示例（402 - 未携带 Token）

JSON · HTTP 402

{
  "accessGranted": false,
  "requiresPayment": true,
  "error": "invalid_token",
  "message": "Crawler token is missing, invalid, or inactive. Please register or activate your account.",
  "onboarding": "https://cdn.aisa.one/cdn/guide.html",
  "timestamp": "2026-04-16T10:00:00Z"
}

引导流程

爬虫状态	API 响应	ESA 可执行的操作
未注册 / Token 无效	402 + `error: "invalid_token"` + `onboarding` URL	透传 402 给爬虫，附带引导页 URL，引导爬虫注册
已注册但余额不足	402 + `onboarding` URL + `insufficientBalance`	返回 402 给爬虫，附带余额不足信息和充值引导
已注册但未携带价格意图	402 + `onboarding` URL + `price`	返回价格信息，爬虫可在下次请求中携带价格意图完成支付
已注册、余额充足、携带价格意图	200（无 `onboarding`）	放行，返回内容

引导页面

onboarding 指向的页面（/cdn/guide.html）包含以下内容：

HTTP 402 Payment Required 协议说明（RFC 9110 标准，非错误）
Pay-per-Crawl 按需付费模式介绍（无订阅、无月费）
一个 Token 通行所有 Publisher 的优势
注册和使用步骤
注册入口（跳转至 /agent/login.html）

价格意图机制

价格意图（Price Intent）机制是本 API 的核心特性，支持四种灵活的访问模式：

模式 1: 自动支付（Auto Price） — 推荐

场景：AI Agent 自动化调用，不需要知道价格，余额够就直接扣

做法：提供 crawlerAutoPrice: true 参数

响应：余额足够 → 200 + 按资源定价扣费；余额不足 → 402

为什么推荐自动支付？
1. 一次请求：无需先发现价格再确认，直接完成支付，请求次数减半
2. 处理更快：省去价格协商环节，平均响应时间更短
3. 集成简单：只需 Header 带 Token + Body 加 "crawlerAutoPrice": true，代码最简洁
4. 适合自动化：AI Agent、批量爬取、实时数据获取等场景的最佳选择

请求示例（推荐）

curl -X POST https://cdn.aisa.one/api/v1/access/verify \
  -H "Content-Type: application/json" \
  -H "X-AISA-Crawler-Token: crawler_abc123" \
  -d '{
    "publisherDomain": "example.com",
    "resourceUrl": "/premium/article-123",
    "crawlerAutoPrice": true
  }'

响应示例 - 成功 (200)

{
  "accessGranted": true,
  "charged": true,
  "chargeAmount": 0.10,
  "currency": "USD",
  "crawler": {
    "id": 123,
    "email": "[email protected]",
    "remainingBalance": 49.90
  },
  "crawlerIdentification": {
    "recognized": true,
    "identifier": "gptbot"
  },
  "transaction": {
    "transactionUuid": "txn-abc-123",
    "timestamp": "2026-04-16T10:30:00Z"
  },
  "message": "Access granted - payment processed",
  "statusCode": 200
}

模式 2: 价格发现（Price Discovery）

场景：首次访问资源，不知道价格，希望先查询定价

做法：不提供任何价格参数

响应：返回 402 + 资源价格信息（不会扣费）

请求示例

{
  "publisherDomain": "example.com",
  "resourceUrl": "/premium/article-123",
  "crawlerToken": "crawler_xxx"
}

响应示例 (402)

{
  "accessGranted": false,
  "requiresPayment": true,
  "priceDiscovery": true,
  "error": "price_required",
  "price": 0.10,
  "currency": "USD",
  "rule": {
    "id": 456,
    "urlPattern": "/premium/*",
    "accessMode": "pay",
    "price": 0.10,
    "billingType": "one-time"
  },
  "crawlerIdentification": {
    "recognized": false,
    "identifier": "unknown"
  },
  "message": "Payment required - price discovery",
  "statusCode": 402,
  "onboarding": "https://cdn.aisa.one/cdn/guide.html",
  "timestamp": "2026-04-16T10:30:00Z"
}

模式 3: 精确价格（Exact Price）

场景：已知价格，需要确认价格后支付（二次请求）

做法：提供 crawlerExactPrice 参数

响应：价格匹配 → 200 + 扣费；价格不匹配 → 402 + 错误信息

请求示例

{
  "publisherDomain": "example.com",
  "resourceUrl": "/premium/article-123",
  "crawlerToken": "crawler_xxx",
  "crawlerExactPrice": "USD 0.10"
}

响应示例 - 成功 (200)

{
  "accessGranted": true,
  "charged": true,
  "chargeAmount": 0.10,
  "currency": "USD",
  "crawler": {
    "id": 123,
    "email": "[email protected]",
    "remainingBalance": 49.90
  },
  "crawlerIdentification": {
    "recognized": true,
    "identifier": "gptbot"
  },
  "transaction": {
    "transactionUuid": "txn-abc-123",
    "timestamp": "2026-04-16T10:30:00Z"
  },
  "message": "Access granted - payment processed",
  "statusCode": 200
}

响应示例 - 价格不匹配 (402)

{
  "accessGranted": false,
  "requiresPayment": true,
  "error": "price_mismatch",
  "price": 0.15,
  "currency": "USD",
  "crawlerIdentification": {
    "recognized": true,
    "identifier": "gptbot"
  },
  "message": "Price mismatch - offered exact price does not match resource price",
  "statusCode": 402,
  "onboarding": "https://cdn.aisa.one/cdn/guide.html"
}

模式 4: 最高价格（Max Price）

场景：设置价格上限，只要资源价格不超过上限就自动支付

做法：提供 crawlerMaxPrice 参数

响应：价格 ≤ 上限 → 200 + 扣费；价格 > 上限 → 402 + 价格信息

请求示例

{
  "publisherDomain": "example.com",
  "resourceUrl": "/premium/article-123",
  "crawlerToken": "crawler_xxx",
  "crawlerMaxPrice": "USD 0.50"
}

响应示例 - 成功 (200)

{
  "accessGranted": true,
  "charged": true,
  "chargeAmount": 0.10,
  "currency": "USD",
  "crawlerIdentification": {
    "recognized": true,
    "identifier": "gptbot"
  },
  "message": "Access granted - payment processed",
  "statusCode": 200
}

响应示例 - 超过预算 (402)

{
  "accessGranted": false,
  "requiresPayment": true,
  "priceTooHigh": true,
  "error": "price_too_high",
  "price": 0.60,
  "currency": "USD",
  "crawlerIdentification": {
    "recognized": true,
    "identifier": "gptbot"
  },
  "message": "Resource price exceeds crawler maximum price",
  "statusCode": 402,
  "onboarding": "https://cdn.aisa.one/cdn/guide.html"
}

重要提示
1. crawlerAutoPrice、crawlerExactPrice、crawlerMaxPrice 三者互斥，不能同时提供
2. 价格格式必须为："货币代码金额"，如 "USD 0.10"（仅 exactPrice/maxPrice 需要）
3. 模式 1 自动支付适合大多数场景，模式 3 适合二次确认，模式 4 适合预算控制

爬虫识别（Crawler Identification）

AISA 与 ESA 之间通过双通道传递爬虫信息，实现「ESA 识别 + AISA 兜底识别」的健壮性方案。每个 API 响应都会返回 crawlerIdentification 字段，将识别结果回传给 ESA。

两个传递通道

通道	内容	谁来填、何时填
通道 1：Body 字段 `crawlerAgent`	识别成功：填爬虫标识符（如 `"gptbot"`）识别失败：填原始 UA 字符串	由 ESA 在转发请求时填入。 ESA 已识别 → 填 identifier（如 `"gptbot"`），AISA 直接查表命中。 ESA 未识别 → 填原始 UA，AISA 用自己的爬虫识别库做兜底识别 —— 该库综合了爬虫账户注册时声明的类型、合作伙伴（如阿里）提供的爬虫数据以及内置的 UA 正则规则，覆盖面比单一来源更广。
通道 2：HTTP Header `X-ESA-Original-Crawler-Agent`	始终填原始爬虫 UA 字符串（如 `"Mozilla/5.0 (compatible; GPTBot/1.0; ...)"`）	由 ESA 始终冗余传递，作为审计依据和二次识别兜底。不会被中间件污染（自定义 header 名）。即使 body `crawlerAgent` 已填 identifier，header 仍冗余传递原始 UA。

为什么不直接用标准 User-Agent header？
因为 ESA 作为网关，转发请求时会把标准 User-Agent 改写成自己的（如 AliyunESA/1.0），原始爬虫 UA 会丢失。这与 X-Forwarded-For 出现的原因完全相同 —— 中间代理污染了标准字段，必须用自定义 header 单独传递原始信息。

服务端识别优先级（5 步）

#	数据来源	匹配方式
1	body `crawlerAgent`	作为已知 identifier 直接查表命中（快路径，ESA 已识别成功的场景）
2	body `crawlerAgent`	作为原始 UA 字符串，匹配 AISA 爬虫识别库（`ai_crawler_types.user_agent_pattern`，包含合作方数据 + 内置规则）
3	header `X-ESA-Original-Crawler-Agent`	同上，匹配 AISA 爬虫识别库（兜底二次识别）
4	账户注册数据	爬虫账户在 AISA 平台注册时声明的 `crawler_type`，按 identifier 匹配
5	—	兜底：`identifier = "unknown"`，`recognized = false`

响应字段：`crawlerIdentification`

每个响应（200 / 402 / 403 / 错误）都会返回此字段，将 AISA 的识别结果回传给 ESA。 ESA 拿到结果后可用于：

更新自己的爬虫识别策略（学习我们的判断）
记录审计日志
对未识别爬虫做特殊处理

字段结构

JSON

{
  "crawlerIdentification": {
    "recognized": true,        // boolean — 是否成功识别
    "identifier": "gptbot"     // string  — ai_crawler_types.identifier；未识别时固定为 "unknown"
  }
}

字段说明

字段	类型	说明
`recognized`	`boolean`	`true` = 成功识别为已知爬虫类型 `false` = 未识别（identifier 固定为 `"unknown"`）
`identifier`	`string`	爬虫类型标识符，对应 `ai_crawler_types.identifier` 列。已识别示例：`gptbot`、`perplexitybot`、`claudebot`、`amazonbot` 等未识别时固定为字符串 `"unknown"`（不会返回 `null`，避免弱类型语言踩坑）

典型示例

① ESA 识别成功（推荐：走快路径）

请求

POST /api/v1/access/verify
X-AISA-Crawler-Token: crawler_xxx
X-ESA-Original-Crawler-Agent: Mozilla/5.0 (compatible; GPTBot/1.0; +https://openai.com/gptbot)
Content-Type: application/json

{
  "publisherDomain": "example.com",
  "resourceUrl": "/premium/article-1",
  "crawlerAgent": "gptbot",
  "crawlerAutoPrice": true
}

响应

{
  "accessGranted": true,
  "crawlerIdentification": {
    "recognized": true,
    "identifier": "gptbot"
  },
  ...
}

② ESA 未识别 → AISA 通过 header 兜底识别成功

请求

POST /api/v1/access/verify
X-AISA-Crawler-Token: crawler_xxx
X-ESA-Original-Crawler-Agent: Mozilla/5.0 (compatible; GPTBot/1.0; +https://openai.com/gptbot)
Content-Type: application/json

{
  "publisherDomain": "example.com",
  "resourceUrl": "/premium/article-1",
  "crawlerAutoPrice": true
}

响应

{
  "accessGranted": true,
  "crawlerIdentification": {
    "recognized": true,
    "identifier": "gptbot"
  },
  ...
}

③ 双方都未识别（unknown）

响应

{
  "accessGranted": true,
  "crawlerIdentification": {
    "recognized": false,
    "identifier": "unknown"
  },
  ...
}

注意：未识别（recognized: false）不等于拦截。是否放行仍由 Publisher 配置的访问规则决定（allow / pay / block）。 crawlerIdentification 字段只是把识别结果透出，不影响放行逻辑。

HTTP 状态码

✅ 最简集成：只看 accessGranted 一个字段

每个响应都返回顶层 boolean 字段 accessGranted：
• true → 放行（免费 allow / 付费成功 / 无规则匹配 / Publisher 不存在默认放行）
• false → 拦截（invalid_token / 余额不足 / 价格不匹配 / blocked / 任何错误）
ESA 等中间层最简集成只需读这一个字段，无需解析 HTTP 状态码或 error 字段。精细化客户端可以再读 statusCode + error 做差异化处理（充值引导、价格回填等）。

重要变更（2026-04 起生效）：401 已合并到 402

所有非授权失败场景统一返回 HTTP 402，由响应 Body 中的 error 字段做机器可读的细分。
这样客户端只需根据 error 字段分发到不同的处理逻辑（引导注册、引导充值、回填价格重试等），无需在 401/402 之间二次判断。

对外只暴露这 5 种状态码

状态码	含义	说明
`200`	访问已授予	请求成功，可以访问资源。场景：免费资源；或付费资源 + 余额充足 + 扣费成功。响应中 `accessGranted: true`，付费场景另含 `charged`、`chargeAmount`、`transaction`。
`400`	请求参数错误	请求本身格式有误，与"是否付费"无关。场景：缺少 publisherDomain / resourceUrl；价格格式非法；同时提供多种价格模式。
`402`	需要付费侧动作	统一错误码：所有"无法直接放行、需要客户端做某种付费侧动作"的场景全部返回 402。具体原因通过 Body 中的 `error` 字段区分（见下方"402 错误细分"表）。所有 402 响应都附带 `onboarding` URL 作为兜底跳转。
`403`	访问被禁止	Publisher 明确把该 URL 配置为 `block` 模式，主动拒绝爬取。与 402 语义不同：402 是"花钱可以解决"，403 是"再有钱也不让你爬"。客户端收到 403 应停止重试，不应引导充值。
`500`	服务器内部错误	服务器处理出错。建议：稍后重试，或联系技术支持。

已废弃的状态码

原状态码	原用途	当前行为
`401`	Token 缺失 / 无效 / 账户禁用	已合并到 402，响应 Body 携带 `error: "invalid_token"`。历史接入方需注意：不要再依赖 401 状态码做"未认证"判断，请改用 `error === "invalid_token"`。

402 错误细分（error 字段）

所有 HTTP 402 响应都会在 Body 中携带一个 error 字段，用机器可读的小写蛇形命名标识具体错误类型。客户端应当根据这个字段而不是状态码本身决定后续动作。

error 值	触发条件	客户端建议动作
`invalid_token`	Token 缺失、格式错误、不存在、已删除或账户被禁用。（原 401 场景）	引导用户/爬虫到 `onboarding` URL 注册或激活账户，获取有效 Token 后重试。
`insufficient_balance`	Token 有效，但 Crawler 账户余额不足以支付资源价格。	引导用户充值。响应中 `crawler.balance`、`crawler.required`、`crawler.shortfall` 给出具体金额。
`price_required`	资源是付费的，但客户端未携带任何价格意图（无 `crawlerExactPrice` / `crawlerMaxPrice` / `crawlerAutoPrice`）。（即"价格发现"场景）	读取响应中的 `price` + `currency`，回填价格意图后重试请求。
`price_mismatch`	使用 `crawlerExactPrice` 模式，但提供的精确价格与资源实际价格不一致。	改用价格发现（不传价格参数）拿到准确价格，再发起精确价格请求。
`price_too_high`	使用 `crawlerMaxPrice` 模式，但资源实际价格高于客户端设置的预算上限。	要么提高 `crawlerMaxPrice`，要么放弃访问该资源。

非 402 错误码

error 值	状态码	说明
`MISSING_REQUIRED_FIELD`	`400`	缺少 publisherDomain 或 resourceUrl，请检查请求 Body。
`INVALID_PARAMETER`	`400`	同时提供了多种价格模式（autoPrice / exactPrice / maxPrice），三者互斥。
`INVALID_PRICE_FORMAT`	`400`	价格格式错误，必须为 `"USD 0.10"` 这种 `货币金额` 形式。
`access_blocked`	`403`	Publisher 明确把该 URL 配置为 `block` 模式，主动拒绝爬取。客户端应停止重试，不应引导充值。
`INTERNAL_ERROR`	`500`	服务器异常，稍后重试或联系技术支持。

402 响应示例

① Token 缺失/无效（原 401）

JSON · HTTP 402

{
  "accessGranted": false,
  "requiresPayment": true,
  "error": "invalid_token",
  "message": "Crawler token is missing, invalid, or inactive. Please register or activate your account.",
  "onboarding": "https://cdn.aisa.one/cdn/guide.html",
  "statusCode": 402
}

② 余额不足

JSON · HTTP 402

{
  "accessGranted": false,
  "requiresPayment": true,
  "insufficientBalance": true,
  "error": "insufficient_balance",
  "message": "Insufficient balance: required USD 0.10, current USD 0.02",
  "price": 0.10,
  "currency": "USD",
  "crawler": {
    "balance": 0.02,
    "required": 0.10,
    "shortfall": 0.08
  },
  "onboarding": "https://cdn.aisa.one/cdn/guide.html",
  "statusCode": 402
}

③ 价格发现（未携带价格意图）

JSON · HTTP 402

{
  "accessGranted": false,
  "requiresPayment": true,
  "priceDiscovery": true,
  "error": "price_required",
  "message": "Payment required - price discovery",
  "price": 0.10,
  "currency": "USD",
  "rule": {
    "urlPattern": "/premium/*",
    "accessMode": "pay",
    "billingType": "per-request"
  },
  "onboarding": "https://cdn.aisa.one/cdn/guide.html",
  "statusCode": 402
}

典型使用场景

场景 1: AI Agent 自动支付（推荐）

步骤：一次请求，自动完成支付

cURL

curl -X POST https://cdn.aisa.one/api/v1/access/verify \
  -H "Content-Type: application/json" \
  -H "X-AISA-Crawler-Token: crawler_abc123" \
  -H "X-ESA-Original-Crawler-Agent: Mozilla/5.0 (compatible; GPTBot/1.0; +https://openai.com/gptbot)" \
  -d '{
    "publisherDomain": "techblog.com",
    "resourceUrl": "/premium/ai-article-2024",
    "crawlerAutoPrice": true,
    "crawlerAgent": "gptbot"
  }'

# 双通道传递原始爬虫信息：
#   body crawlerAgent="gptbot"  → ESA 已识别成功的快路径
#   header X-ESA-Original-Crawler-Agent → 始终冗余传递原始 UA，作审计和兜底

响应 (200 - 自动扣费成功)

JSON

{
  "accessGranted": true,
  "charged": true,
  "chargeAmount": 0.10,
  "currency": "USD",
  "crawler": {
    "id": 123,
    "email": "[email protected]",
    "remainingBalance": 99.90
  },
  "crawlerIdentification": {
    "recognized": true,
    "identifier": "gptbot"
  },
  "transaction": {
    "transactionUuid": "txn-20260329-001",
    "timestamp": "2026-04-16T10:30:00Z"
  },
  "message": "Access granted - payment processed",
  "statusCode": 200
}

场景 2: 价格发现 + 确认支付（两步流程）

步骤：价格发现 → 价格确认 → 访问资源

步骤 1: 价格发现

cURL

curl -X POST https://cdn.aisa.one/api/v1/access/verify \
  -H "Content-Type: application/json" \
  -H "X-AISA-Crawler-Token: crawler_abc123" \
  -d '{
    "publisherDomain": "techblog.com",
    "resourceUrl": "/premium/ai-article-2024"
  }'

响应 (402 - 价格发现)

JSON

{
  "accessGranted": false,
  "requiresPayment": true,
  "priceDiscovery": true,
  "error": "price_required",
  "price": 0.10,
  "currency": "USD",
  "rule": {
    "id": 67,
    "urlPattern": "/premium/*",
    "accessMode": "pay",
    "price": 0.10,
    "billingType": "one-time"
  },
  "crawlerIdentification": {
    "recognized": false,
    "identifier": "unknown"
  },
  "message": "Payment required - price discovery",
  "statusCode": 402,
  "onboarding": "https://cdn.aisa.one/cdn/guide.html"
}

步骤 2: 确认支付

cURL

curl -X POST https://cdn.aisa.one/api/v1/access/verify \
  -H "Content-Type: application/json" \
  -H "X-AISA-Crawler-Token: crawler_abc123" \
  -d '{
    "publisherDomain": "techblog.com",
    "resourceUrl": "/premium/ai-article-2024",
    "crawlerExactPrice": "USD 0.10",
    "crawlerAgent": "Mozilla/5.0 (compatible; GPTBot/1.0; +https://openai.com/gptbot)"
  }'

响应 (200 - 访问授予)

JSON

{
  "accessGranted": true,
  "charged": true,
  "chargeAmount": 0.10,
  "currency": "USD",
  "crawler": {
    "id": 123,
    "email": "[email protected]",
    "remainingBalance": 99.90
  },
  "crawlerIdentification": {
    "recognized": true,
    "identifier": "gptbot"
  },
  "transaction": {
    "transactionUuid": "txn-20240701-001",
    "timestamp": "2026-04-16T10:35:00Z"
  },
  "message": "Access granted - payment processed",
  "statusCode": 200
}

场景 3: 使用最高价格预算控制

适用：批量访问，设置价格上限，避免超支

cURL

curl -X POST https://cdn.aisa.one/api/v1/access/verify \
  -H "Content-Type: application/json" \
  -H "X-AISA-Crawler-Token: crawler_abc123" \
  -d '{
    "publisherDomain": "news.example.com",
    "resourceUrl": "/article/breaking-news-123",
    "crawlerMaxPrice": "USD 0.50",
    "crawlerAgent": "Mozilla/5.0 (compatible; GPTBot/1.0; +https://openai.com/gptbot)"
  }'

响应 A - 价格在预算内 (200)

JSON

{
  "accessGranted": true,
  "charged": true,
  "chargeAmount": 0.25,
  "currency": "USD",
  "crawlerIdentification": {
    "recognized": true,
    "identifier": "gptbot"
  },
  "message": "Access granted - payment processed",
  "statusCode": 200
}

响应 B - 价格超过预算 (402)

JSON

{
  "accessGranted": false,
  "requiresPayment": true,
  "priceTooHigh": true,
  "error": "price_too_high",
  "price": 0.80,
  "currency": "USD",
  "crawlerIdentification": {
    "recognized": true,
    "identifier": "gptbot"
  },
  "message": "Resource price exceeds crawler maximum price",
  "statusCode": 402,
  "onboarding": "https://cdn.aisa.one/cdn/guide.html"
}

场景 4: 访问免费资源

cURL

curl -X POST https://cdn.aisa.one/api/v1/access/verify \
  -H "Content-Type: application/json" \
  -H "X-AISA-Crawler-Token: crawler_abc123" \
  -d '{
    "publisherDomain": "blog.example.com",
    "resourceUrl": "/free/public-article-456"
  }'

响应 (200 - 免费访问)

JSON

{
  "accessGranted": true,
  "charged": false,
  "rule": {
    "id": 68,
    "urlPattern": "/free/*",
    "accessMode": "allow"
  },
  "crawlerIdentification": {
    "recognized": false,
    "identifier": "unknown"
  },
  "message": "Access granted - free resource",
  "statusCode": 200
}

场景 5: 访问被拒绝

cURL

curl -X POST https://cdn.aisa.one/api/v1/access/verify \
  -H "Content-Type: application/json" \
  -H "X-AISA-Crawler-Token: crawler_abc123" \
  -H "X-ESA-Original-Crawler-Agent: Mozilla/5.0 (compatible; GPTBot/1.0; +https://openai.com/gptbot)" \
  -d '{
    "publisherDomain": "private.example.com",
    "resourceUrl": "/blocked/secret-data"
  }'

响应 (403 - 拒绝访问)

JSON

{
  "accessGranted": false,
  "error": "access_blocked",
  "rule": {
    "id": 69,
    "urlPattern": "/blocked/*",
    "accessMode": "block"
  },
  "crawlerIdentification": {
    "recognized": true,
    "identifier": "gptbot"
  },
  "message": "Access denied by publisher rule",
  "statusCode": 403
}

API 在线测试

在下方输入参数，直接测试 API 功能：

API Playground

Select Test Crawler 快捷选择

Select Test Resource 快捷选择

认证方式

Crawler Token 可选

已填入测试 Token，可直接使用或替换为自己的 Token。留空可测试"完全陌生爬虫"路径（服务端返回 402 + 引导注册）

Publisher Domain 必需

Publisher 的域名或邮箱，如 example.com 或 [email protected]

Resource URL 必需

要访问的资源路径

价格意图模式

Exact Price

格式：货币代码金额，如 USD 0.10

Max Price

格式：货币代码金额，如 USD 0.50

Body: crawlerAgent 可选通道 1

ESA 已识别 → 填爬虫 identifier（如 gptbot）；ESA 未识别 → 填原始 UA 字符串。详见爬虫识别（双通道）。

Header: X-ESA-Original-Crawler-Agent 可选通道 2

始终冗余传递的原始爬虫 UA 字符串。即使 body crawlerAgent 已填 identifier，header 仍可冗余传递原始 UA 用于审计和兜底识别。

Metadata (JSON) 可选

附加元数据，必须是有效的 JSON 对象

Quick Test — 一键 cURL 测试

点击「运行」直接在页面测试，或复制 cURL 到终端执行。Token 和 Domain 使用上方填写的值。

自动价格模式推荐

cURL

curl -s -X POST "https://cdn.aisa.one/api/v1/access/verify" \
  -H "Content-Type: application/json" \
  -H "X-AISA-Crawler-Token: aisa_crawler_65a6b17e97bd10d076d84871f16e8ac5fb4c676ff1b0714d1b653b1a43686d7d" \
  -d '{
    "publisherDomain": "[email protected]",
    "resourceUrl": "/premium/test-auto.html",
    "crawlerAutoPrice": true
  }'

精确价格模式

cURL

curl -s -X POST "https://cdn.aisa.one/api/v1/access/verify" \
  -H "Content-Type: application/json" \
  -H "X-AISA-Crawler-Token: aisa_crawler_65a6b17e97bd10d076d84871f16e8ac5fb4c676ff1b0714d1b653b1a43686d7d" \
  -d '{
    "publisherDomain": "[email protected]",
    "resourceUrl": "/premium/test-exact.html",
    "crawlerExactPrice": "USD 0.10"
  }'

最高价格模式

cURL

curl -s -X POST "https://cdn.aisa.one/api/v1/access/verify" \
  -H "Content-Type: application/json" \
  -H "X-AISA-Crawler-Token: aisa_crawler_65a6b17e97bd10d076d84871f16e8ac5fb4c676ff1b0714d1b653b1a43686d7d" \
  -d '{
    "publisherDomain": "[email protected]",
    "resourceUrl": "/premium/test-max.html",
    "crawlerMaxPrice": "USD 1.00"
  }'

Crawler Access Verify API v1

概述

核心特性

接口信息

认证方式

方式 1: 自定义 Header（推荐）

方式 2: Body 参数

请求参数详解

必需参数

可选参数 - 价格意图

可选参数 - 其他

参数别名支持

响应格式详解

响应结构

付费相关字段（仅在涉及付费时出现）

价格意图相关字段

对象信息字段

错误相关字段

爬虫引导注册（Onboarding）

引导流程

引导页面

价格意图机制

模式 1: 自动支付（Auto Price） — 推荐

模式 2: 价格发现（Price Discovery）

模式 3: 精确价格（Exact Price）

模式 4: 最高价格（Max Price）

爬虫识别（Crawler Identification）

两个传递通道

服务端识别优先级（5 步）

响应字段：crawlerIdentification

字段结构

字段说明

典型示例

HTTP 状态码

对外只暴露这 5 种状态码

已废弃的状态码

402 错误细分（error 字段）

非 402 错误码

402 响应示例

① Token 缺失/无效（原 401）

② 余额不足

③ 价格发现（未携带价格意图）

典型使用场景

场景 1: AI Agent 自动支付（推荐）

响应 (200 - 自动扣费成功)

场景 2: 价格发现 + 确认支付（两步流程）

步骤 1: 价格发现

响应 (402 - 价格发现)

步骤 2: 确认支付

响应 (200 - 访问授予)

场景 3: 使用最高价格预算控制

响应 A - 价格在预算内 (200)

响应 B - 价格超过预算 (402)

场景 4: 访问免费资源

响应 (200 - 免费访问)

场景 5: 访问被拒绝

响应 (403 - 拒绝访问)

API 在线测试

Quick Test — 一键 cURL 测试

响应字段：`crawlerIdentification`