接收异步结果(轮询与 webhook)
完成后,稍后才出结果的图片、视频、音频任务能到达最终状态,积分随之扣除或退回。
很多图片、视频、音频供应商先返回任务 ID,稍后才给出结果。你可以为每个 Provider(或 Provider 场景)选择由应用查询状态,还是由供应商回调。文本始终是直接返回,对话模型可以跳过本指南。
准备工作
- 一个用于图片、视频或音频模型、已设置响应解析的 Provider 和 Provider 场景,见 接入 AI 服务商。
- 一个可查询的状态 URL,或一个供应商能回调到的公网部署地址。本地
127.0.0.1收不到回调。 - 拥有
ai.read和ai.write的管理员账号。
选择结果的获取方式
有两处会请求状态 URL
客户端通过 GET /api/status?taskId=... 读取任务、且已到轮询间隔时,会请求一次状态 URL。没有人读取的任务由定时任务 ai-channel-tasks 每分钟推进一次,因此仍会结束并结算积分。这个任务只在后台任务正常运行的部署上执行。
读取任务状态
发起任务后,按返回的 statusUrl 读取状态。读取状态需要会话或带 查询 AI 任务状态 的 API Key,且只返回调用者自己的任务。
curl -X POST https://your-domain.example/api/video-creation/generate \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"海岸线上空的航拍镜头","mediaType":"video"}'
# => { "taskId": "ai_task_...", "status": "running", "statusUrl": "/api/status?taskId=...",
# "estimatedPriceCredits": 12, "resultMode": "polling" }
curl "https://your-domain.example/api/status?taskId=ai_task_..." \
-H "Authorization: Bearer $API_KEY"任务成功后,输出中的 URL 会被复制到用户存储的 /generated 目录。没有配置 文件存储 时任务仍会成功,任务事件中会记录跳过了存储导入。
验证
- 在用户的
/app/ai/<taskId>页面,任务从running变为succeeded或failed,并显示扣除或退回的积分。 - 平台 → AI Tasks(
/admin/ai/tasks)显示最终状态。失败任务在/admin/ai/failed中列出。 pnpm validate:ai-channel会检查 webhook 签名、轮询和退款。
常见问题
异步任务一直处于运行中
确认轮询填写了 状态查询 URL 模板,并且要么有客户端在读取 GET /api/status?taskId=...,要么后台任务在正常运行、定时任务 ai-channel-tasks 能推进该任务。Webhook 模式下,确认供应商会携带任务 ID 调用 webhook URL。
Webhook 返回 401
Webhook secret is not configured. 表示 Provider 和 Provider 场景都没有保存 Webhook 签名密钥,请填写并保存。Webhook signature verification failed. 表示 x-ai-signature 缺失,或不是对原始请求体计算的 HMAC。任务状态不会改变。
Webhook 返回 400
回调没有指明任务(taskId is required.)、回调 URL 指向了其他 Provider(Webhook channel does not match task.),或请求体不是 JSON。任务状态不会改变。
任务状态或输出不对
解析配置读取了供应商响应中错误的字段。在 Provider 表单中粘贴一段真实响应,点击 测试解析,修正 结果路径 或 状态映射。