拨测 API 怎么调？宝塔拨测开放接口的请求与返回，覆盖 HTTP、PING、TCP、DNS、SSL 五类检测

想在脚本里批量提交拨测、而不是每次手动打开网页点按钮，用宝塔拨测的开放 API。它是宝塔拨测（https://t.bt.cn/api-console/）提供的 HTTP 接口，服务地址 https://t.bt.cn，覆盖 HTTP、PING、TCP、DNS、SSL 证书五类即时拨测，还带两个免费接口：节点列表和积分余额。官方客户端示例支持 Shell、Ruby、Node.js、PHP、Python。

先看入口长什么样：

开放 API 是什么、怎么算钱

按官方 API 文档，宝塔拨测开放 API（v1）是「针对网络性能检测的系统，支持 HTTP 检测、PING 检测、DNS 检测、TCP 检测、SSL 证书检测等即时（快速）拨测能力」。

计费规则是两条（来自 API 文档概览）：

• 网站检测 / PING 检测 / TCP 检测 / DNS 检测：1 额度/节点/次
• SSL 检测：10 额度/次
• 检测结果最多保存 30 分钟

调用前先在控制台生成 API 密钥，之后每个请求都带 key 参数。所有接口的返回值统一用 status（0=成功）或 error_code（0=成功）表示成败，非 0 时看 msg/error 字段拿提示。

两个免费接口：先摸清节点和余额

这两个接口不扣额度，适合先用来验证密钥、看有哪些节点可用。

节点列表：GET /api/v1/open-api/nodes，返回当前有可用自有节点的地区列表（国内 / 港澳台 / 海外统一口径）。

参数	必填	说明
key	是	API 密钥
area	否	默认省份节点；可选 city（城市节点）/ oversea（海外节点）
isp_type	否	按运营商筛选，2=电信、3=移动、4=联通、7=海外、8=港澳台

返回的 list 里每项是 id（节点 ID，创建检测任务时要用）、node_name（如「河北」）、isp_name（运营商名）、isp_code（运营商码）。

积分余额：GET /api/v1/open-api/balance，返回 available_credits（可用积分）和 frozen_credits（冻结积分，文档说明冻结通道在途、当前以快通道为主通常为 0）。

五类检测：统一的「创建 + 轮询」两步

五类检测接口结构一致，都是两步走：

1. 创建任务：POST /api/v1/open-api/tasks/{类型}，返回 data.id（任务 ID）和 data.max_node（节点数）。
2. 轮询结果：GET /api/v1/open-api/tasks/{类型}/{id}，返回 done 布尔值，直到为 true 或 5 分钟为止（文档建议每 10 秒请求一次）。

创建任务统一需要 key 和 node_ids（地区节点 ID，多个用英文逗号隔开，如 7,8,9）。各类型的差异在目标参数：

类型	创建接口	查询接口	额外参数
网站检测	POST /tasks/http	GET /tasks/http/{id}	host：检测目标网址
PING 检测	POST /tasks/ping	GET /tasks/ping/{id}	host：域名或 IP
TCP 检测	POST /tasks/tcp	GET /tasks/tcp/{id}	host：域名或 IP；port：端口（1～65535）
DNS 检测	POST /tasks/dns	GET /tasks/dns/{id}	host：域名或 IP；record_type：A（默认）/AAAA/CNAME/MX/NS/TXT
SSL 检测	POST /tasks/ssl	GET /tasks/ssl/{id}	host：域名（不含协议/端口/IP/路径）；refresh：是否忽略 15 分钟缓存强制重测

轮询结果的公共字段：error_code（0=成功）、error（错误信息）、done（是否完成）、id（任务 ID）、max_node（节点数）、list（结果数据数组；进行中时为已完成节点的部分结果，顺序即槽位顺序）。

几个接口特有的点：

• 网站检测的 host 传完整网址（文档示例是 https://example.com/），结果 list 里是各节点的分段耗时（DNS 解析、连接、首字节等）与 HTTP 状态码。
• TCP 检测多一个必填 port，因为 TCP 拨测测的是指定端口能不能建立连接。
• DNS 检测多了 record_type，默认查 A 记录，也能查 AAAA、CNAME、MX、NS、TXT。
• SSL 检测的 host 不能带协议、端口、IP、路径（例如传 bt.cn，不能传 https://bt.cn）；max_node 固定为 1，done=true 时 list[0] 就是该域名完整证书检测结果。

创建任务时还可以带 X-Idempotency-Key、X-Request-Id 两个请求头做幂等控制，避免重复提交。

一段最小可跑的调用

以网站检测为例，先查节点拿 ID，再创建任务、轮询结果：

# 1. 查节点（免费）
curl --request GET \
  --url 'https://t.bt.cn/api/v1/open-api/nodes?key=tbt_你的密钥'

# 2. 创建网站检测任务（node_ids 用上一步拿到的 id，host 传完整网址）
curl --request POST \
  --url 'https://t.bt.cn/api/v1/open-api/tasks/http?key=tbt_你的密钥&node_ids=7,8,9&host=https%3A%2F%2Fexample.com%2F'

# 3. 用返回的 id 轮询结果，每 10 秒一次，直到 done=true
curl --request GET \
  --url 'https://t.bt.cn/api/v1/open-api/tasks/http/任务ID?key=tbt_你的密钥'

创建任务返回形如 {"error_code":0,"error":"","data":{"id":"v2-...","max_node":3}}；轮询到 done:true 后，list 里就是每个节点的检测结果。整个流程和网页版「提交后等节点陆续返回」是一致的，只是换成了接口轮询。

本文接口字段、参数、额度与返回结构均以宝塔拨测开放 API 文档（https://t.bt.cn/api-console/）为准，密钥生成入口也在同一页面的「控制台」。