教程
为什么你的 hiapi 任务回调没有触发，以及如何修复
为什么你的 hiapi 任务回调没有触发
你向 POST https://api.hiapi.ai/v1/tasks 提交了一个任务，并带上了 callback 对象；任务完成了（当你 GET /v1/tasks/{taskId} 时可以看到 status: "success"），但你的端点从未收到终态通知。没有任何请求到达你的服务器。没有重试。日志里也没有任何内容。
hiapi 回调是以服务器到服务器的 HTTPS POST 形式从你的网络外部投递的。如果这条路径上任何环节出了问题——URL 无法从公网访问、TLS 无法协商、你的处理程序没有足够快地返回 2xx，或者你这一侧的签名校验拒绝了请求——那么从你应用的角度来看，这条通知就是“静默”的。好消息是：这几乎总是少数几种配置错误之一，而且每一种都很容易验证。
常见原因（按可能性排序）
- 回调 URL 无法从公网访问。
localhost、127.0.0.1、你 VPC 内的 IP，或者已经过期的 ngrok 隧道——hiapi 都访问不到。 - HTTPS / TLS 问题。 自签名证书、过期证书、缺少中间证书，或者主机名不匹配。hiapi 只会向
https://开头的 URL 发起 POST，并校验证书链。 - 你的处理程序没有在超时时间内返回
2xx。 如果你在回调处理程序里同步执行耗时操作（数据库写入、下载图片、发送通知），请求会在你返回200之前就超时。从 hiapi 的角度看，这就是一次失败。 - 你从未注册 Webhook Sign Key，而你的处理程序又拒绝了未签名请求。 如果未在 Settings 中生成签名密钥，hiapi 投递的请求体将不带签名头——你编写的任何校验中间件都会把该请求视为无效并丢弃。
- 提交时遗漏了
callback对象。 它是可选的。如果你在POST /v1/tasks时没有包含它，那就没有什么会触发。你必须改为轮询GET /v1/tasks/{taskId}。 - 任务仍在运行。 回调只在终态（
success或fail）触发。当status是queued、handling或archiving时，还不会发送回调。 - 回调 URL 的主机在拒绝名单上 / 公司防火墙阻止了向其的出站流量。 不太常见，但如果你身处严格的外围网络环境中，值得检查一下。
修复方法：7 步检查清单
- 确认任务确实到达了终态。
curl -H "Authorization: Bearer $HIAPI_KEY" https://api.hiapi.ai/v1/tasks/tk-hiapi-...。如果status是queued或handling，回调还没有触发——先等待，不要调试。 - 确认你提交了
callback对象。 重新阅读你发送到POST /v1/tasks的请求体。如果缺少callback，那答案就是这个——补上并重新提交，或者改为轮询。 - 从公网测试回调 URL。 从你网络之外的任何机器（使用蜂窝网络的手机、云 shell、在线 curl 工具）运行
curl -i -X POST https://your.domain.example/hiapi/callback -d '{}' -H "Content-Type: application/json"。你必须从自己的服务器收到 HTTP2xx响应。如果得到连接被拒绝、DNS 错误，或任何非2xx的响应，请先修复这个问题。 - 验证 TLS 证书链。
curl -vI https://your.domain.example/hiapi/callback 2>&1 | grep -i 'ssl\|cert'。查找SSL certificate problem。如果看到该错误，请安装完整证书链（叶子证书 + 中间证书），或使用托管证书（Let's Encrypt、CDN、ACM）。 - 立即返回
200，然后异步处理。 在你的处理程序内部：将请求负载写入队列 / 数据表，返回200 OK，然后在后台 worker 中处理工作。不要让响应被缓慢的下游调用阻塞。 - 生成 Webhook Sign Key 并统一你的校验方式。 前往
/en/dashboard/settings→ Webhook Sign Key → Generate，保存该密钥。如果你的处理程序会校验签名，请使用保存的密钥；如果不校验，请暂时禁用校验，确认投递正常后再重新启用。 - 检查
/en/dashboard/logs。 调用日志会显示请求及其终态。将你调用日志中的request_id与你的服务器实际收到的内容（如果有）进行对比，是定位“回调是否离开 hiapi”与“回调是否到达我的服务器”的最快方式。
最小验证示例
使用以下内容端到端确认你的 API 密钥、创建任务路径和回调端点。选择一个快速的图像模型做冒烟测试；根据公开文档，模型 ID 包含能力后缀：
curl -X POST https://api.hiapi.ai/v1/tasks \
-H "Authorization: Bearer $HIAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2/text-to-image",
"input": {"prompt": "a cute cat"},
"callback": {"url": "https://your.domain.example/hiapi/callback"}
}'
你应该会立即收到一个包含 taskId 的 JSON 响应，形如 tk-hiapi-...。然后，一旦任务变为 success 或 fail，就观察你的服务器日志，看是否有发往 /hiapi/callback 的入站 POST。如果创建任务这一步本身返回 401 Unauthorized，那么问题出在密钥上——请参阅 为什么 hiapi 返回 429（以及该怎么办），了解 hiapi 的错误信封机制如何工作（同一套 hiapi_error 结构适用于所有状态码）。
相关链接
- API Keys — 验证你的密钥是否有效且权限范围正确
- Settings — 生成或轮换你的 Webhook Sign Key
- Call Logs — 确认 hiapi 已发送回调以及响应状态
- API Reference — 完整的
POST /v1/tasks和GET /v1/tasks/{id}规范 - hiapi 429 速率限制 — 针对相关“你收到了状态但没有回调”这类问题，详解错误信封
FAQ
hiapi 会重试失败的回调吗？
只有当你的端点返回 2xx 响应时，回调才被视为已投递。如果你的处理程序返回 5xx、超时，或 TLS 握手失败，请将回调视为未投递。最稳健的模式是：对于任何你提交时带了回调的任务，始终以轮询 GET /v1/tasks/{taskId} 作为兜底。这样即使回调路径上出现一次故障，也不会丢失结果。
回调 URL 可以使用 HTTP 而不是 HTTPS 吗？
不可以。只接受 https:// 开头的 URL。如果你在本地测试，请使用为你终止 TLS 的隧道（Cloudflare Tunnel、ngrok、tailscale funnel），并将回调指向公网 HTTPS 端点。
为什么我的处理程序收到了请求体，但签名校验失败？ 要么是 (a) 你在提交任务之后才生成 Webhook Sign Key——请求是用旧密钥（或没有密钥）签名的——所以请重新生成、保存，并提交新任务；要么是 (b) 你的校验代码重建规范字符串的方式与 hiapi 不同。记录你服务器收到的请求体的精确字节，并对这些精确字节重新运行 HMAC，中间不要做任何 JSON 重新序列化。
taskId 显示 success，但我没有收到回调，也没有结果 URL。
重新请求 GET /v1/tasks/{taskId}，查看 output 数组。output[*].url 中的 URL 有时间限制（expireAt）；请立即下载。回调投递和 URL 时效是两个独立的问题——即使没有回调，GET 端点也是事实来源。
我在 /en/dashboard/logs 中看到了回调，但我的服务器从未记录它。
这说明问题在你的外围网络，而不是 hiapi。常见原因包括：CDN / WAF 规则阻止了没有你团队可识别 User-Agent 的 POST 请求、防火墙上的 IP 允许列表，或者你的反向代理改写了路径。请在防火墙上允许该入站 POST，然后重新运行。
回调 URL 会占用我账户的速率限制吗？
不会。回调是 hiapi 向你进行的投递，与你的 POST /v1/tasks 速率预算无关。
