Webhook

什么是 Webhook

Token360 可以在异步视频生成任务结束时通知你的服务，因此你的应用不需要持续轮询视频状态接口。

Webhook 允许你在通过 POST /v1/videos 创建视频任务时提供 callback_url。当任务进入终态后，Token360 会向你的回调地址发送 HTTP POST 请求，并携带最终任务状态和视频结果。

适合在应用需要后台处理视频任务结果时使用，例如更新订单、保存生成视频 URL，或通知终端用户。

如何启用 Webhook

调用 POST /v1/videos 时传入两个字段：

callback_url：你的 HTTPS 接收端地址，用于接收回调 POST 请求。
request_id：你的业务 ID，例如订单号。Token360 会在回调信封中原样回传该值，方便你匹配本地业务记录。

Shell

1curl -X POST https://api.token360.ai/v1/videos \
2  -H "Authorization: Bearer sk-your-api-key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "model": "seedance-2.0-fast",
6    "prompt": "A paper crane unfolds into a real bird and flies away.",
7    "resolution": "480p",
8    "duration": 5,
9    "aspect_ratio": "16:9",
10    "generate_audio": false,
11    "callback_url": "https://your-app.example.com/webhooks/video",
12    "request_id": "your-order-id-001"
13  }'

未提供 callback_url 时，不会触发回调，你仍需通过 GET /v1/videos/{video_id} 主动轮询结果。

回调触发时机

Token360 仅在视频任务到达终态时发送回调：completed 或 failed。
中间状态，例如 queued 和 in_progress，不会触发回调。
同一个视频任务最多成功投递一次回调。如果所有投递尝试都失败，Token360 将放弃投递。

重试与超时

单次投递超时：30 秒。
最大投递次数：共 3 次，包含首次投递。
重试间隔：第 2 次投递前等待 1 秒，第 3 次投递前等待 3 秒。
任意一次返回 2xx 即停止重试，并标记投递成功。
跟随重定向后，最终响应为非 2xx 才会触发重试。如果重定向链最终返回 2xx，则视为投递成功。
3 次均失败后，Token360 放弃投递且不会补发。如需恢复最终状态，请使用 GET /v1/videos/{video_id} 查询。

幂等性

同一个视频任务 id 最多成功投递一次回调。
如果多个视频任务复用同一个 request_id，每个任务仍可能各自成功投递一次回调。
网络重试仍可能导致极少数重复投递。
请将接收端实现为幂等，例如使用 id 和 status 去重。

查询 callback_url

认证

Token360 向 callback_url 发送的 POST 请求不携带鉴权 Header。你应通过以下方式保护接收端：

仅暴露 HTTPS 端点。
使用不可猜测的随机路径，或在回调 URL 中嵌入校验 token。
在处理 payload 前，使用 request_id 与本地业务记录进行比对。

Request Body

idstringrequired

视频任务 ID。与提交响应返回的 id 一致。

request_idstring

创建视频任务时传入的业务 ID。未提供时该字段缺省。

statusenum<string>required

视频任务终态。

Available options: completed failed

errorobject | null

错误详情。仅在 status 为 failed 时返回。

error.codestring

供应商或平台错误代码。

error.messagestring

可读错误信息。

payloadobjectrequired

完整视频对象。字段与 GET /v1/videos/{video_id} 的响应一致，包括 id、object、status、model、prompt、url、video_url、duration、parameters、content、usage，以及可用时的 error 字段。

Response

status_codeintegerrequired

返回任意 2xx HTTP 状态码即表示确认投递。跟随重定向后，最终响应为非 2xx 时会触发重试。

bodyany

可选响应体。Token360 不读取响应体内容。

请求

JSON

1{
2  "id": "video_b5c3cb639d804319b1015025",
3  "request_id": "your-order-id-001",
4  "status": "completed",
5  "payload": {
6    "id": "video_b5c3cb639d804319b1015025",
7    "object": "video",
8    "status": "completed",
9    "model": "seedance-2.0-fast",
10    "prompt": "A paper crane unfolds into a real bird and flies away.",
11    "created_at": 1778197436,
12    "updated_at": 1778197510,
13    "duration": 5,
14    "resolution": "480p",
15    "ratio": "16:9",
16    "parameters": {
17      "duration": 5,
18      "resolution": "480p",
19      "aspect_ratio": "16:9",
20      "video_mode": "text_to_video"
21    },
22    "url": "https://media.token360.ai/v-b5c3cb639d804319b1015025/2026/05/...mp4?Expires=...&Signature=...",
23    "video_url": "https://media.token360.ai/v-b5c3cb639d804319b1015025/2026/05/...mp4?Expires=...&Signature=...",
24    "content": {
25      "video_url": "https://media.token360.ai/v-b5c3cb639d804319b1015025/2026/05/...mp4?Expires=...&Signature=...",
26      "last_frame_url": null,
27      "file_url": null
28    },
29    "usage": {
30      "completion_tokens": 50638,
31      "total_tokens": 50638
32    }
33  }
34}

响应

返回任意最终 2xx 响应即视为确认投递。请在 30 秒内快速返回，避免触发重试。

JSON

1{
2  "status_code": 204,
3  "body": null
4}

Batch 批量任务 Webhook

当 batch 作业进入终态（completed、failed、cancelled、expired）时，平台可按与视频相同的策略向你的 URL 发送 POST。

启用方式

单次：在 POST /v1/batches 中传入 callback_url，或
账户默认：在控制台 批量任务 → Webhook 设置 中配置。

若两者同时存在，以 batch 上的 callback_url 为准。

载荷

请求体为 batch 对象（与 GET /v1/batches/{batch_id} 字段一致），并额外包含：


`event`	如 `batch.completed`、`batch.failed` 等

配置签名密钥后，请求头包含 Token360-Timestamp 与 Token360-Signature（sha256= + HMAC-SHA256({timestamp}.{body})）。

重试

与视频一致：最多 3 次尝试，单次超时 30 秒，间隔 1s / 3s / 5s。任意 2xx 即停止重试。

详见批量任务。

此页面对您有帮助吗？