统一 API Key

以 API v2 构建检测能力，按需使用同步查询

API v2 是面向批量、多类型与自动化检测的主线产品；API v1 提供同步单域名 DNS 污染检测，适合少量、需要在当前请求中直接取得结果的场景。两者使用同一个账户 API Key。

两种互补的调用方式

优先使用 API v2 构建新集成；仅在单域名、低频且需要同步结果时选择 API v1。

主线产品 · 异步批量

API v2 · 批量与多类型自动化检测

支持全部七种检测方式。创建批次后使用 batch_id 和 check_id 查询结果，适合规模化任务与跨境网络环境。

响应方式: 异步批次
适用场景: 批量检测、持续自动化、多节点结果分析
检测范围: 七种检测方式，单次最多 1,000 个目标

快速开始查看完整 API 文档

同步单域名

API v1 · 少量即时 DNS 污染检测

每次检测一个域名，并在同一次 HTTP 请求中直接取得 DNS 污染判定，无需创建批次或轮询结果。

响应方式: 同步响应
适用场景: 人工排障、域名上线前校验、低频自动化
检测范围: DNS 污染检测，每次一个域名

快速开始查看完整 API 文档

API v2

API v2 快速开始

以下示例创建一个异步 GFW 全量检测批次。创建成功只代表任务已接受，结果需要通过批次或单项结果接口查询。

Base URL: https://api.weavebit.com/v2/
身份验证: 使用 Authorization: Bearer 提交账户统一 API Key。API Key 仅用于确认用户身份，不与检测类型绑定。

查看完整 API 文档查看 API Key

最小创建请求

curl -X POST 'https://api.weavebit.com/v2/task/create' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_REQUEST_ID' \
  -d '{
    "check_type": "gfw_full_domain_check",
    "target": [{"domain": "example.com"}],
    "nodes": ["cn-fj-zhangzhou-ct"]
  }'

异步创建响应

{
  "code": 0,
  "message": "ok",
  "batch_id": "...",
  "execution_deadline_at": "...Z",
  "expires_at": "...Z",
  "datas": [{"check_id": "...", "target": {"domain": "example.com"}}]
}

API v2 基本流程

从节点选择到结果保存，批次生命周期分为五个明确步骤。

1
获取节点
读取当前可用于检测的节点。
2
估算费用
按需预估目标与节点组合的费用。
3
创建批次
取得 batch_id 与每个目标的 check_id。
4
查询结果
查询批次进度或单项检测结果。
5
保存数据
在创建后 24 小时内保存所需结果。

API v2 批次规则

提交批量检测前需要了解的执行、保留和域名规范化规则。

单次上限

每次最多提交 1,000 个目标。

执行期限

每个批次最长执行 6 小时；未完成项目在截止后进入最终状态。

隐私与保留

批次和结果在创建后 24 小时彻底清理，请调用方及时保存需要的数据。

国际化域名

输入将规范化为小写 ASCII Punycode。创建响应和结果均返回规范化后的域名，建议使用 check_id 关联。

API v1

API v1 快速开始

API v1 用于同步、单域名 DNS 污染检测。请求会在同一连接中等待检测完成并直接返回判定。

正式地址: https://api.weavebit.com/v1/task/pollute
身份验证: 使用 application/x-www-form-urlencoded 提交 key 与 host。推荐使用 POST，避免 API Key 出现在 URL 和访问日志中。

适合 API v1 的场景

人工排障临时检查一个域名，无需维护批次状态。
上线前校验在发布或切换域名前执行一次 DNS 污染检查。
低频自动化业务流程偶尔检查单个域名，并直接处理返回结果。

调用边界: 同步表示结果在同一次 HTTP 请求中返回，不代表固定响应时长。调用端必须判断 error_code；result=0 表示未发现污染，result=1 表示发现污染，result=-1 表示暂未获得有效结果。批量、高并发或其他检测类型应使用 API v2。

查看完整 API 文档 API Explorer

最小同步请求

curl -X POST 'https://api.weavebit.com/v1/task/pollute' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'key=YOUR_API_KEY' \
  --data-urlencode 'host=example.com'

同步检测响应

{
  "error_code": 0,
  "error_msg": "执行成功",
  "result": 0
}

统一 API Key

一个账户，两种调用方式

API v1 与 API v2 共用身份、余额和用户侧工具，切换调用方式不需要维护第二套账户。

统一身份: 同一个账户 API Key 可用于 API v1 与 API v2。
统一余额与用量: 费用从同一账户余额结算，并在 Console 中统一查看。
统一开发工具: 在 Console 中切换查看两版文档，并可通过 API Explorer 验证请求。