Webhook

什么是 Webhook

Token360 可在异步任务进入终态时向你的 HTTPS 地址 POST，免去持续轮询。


视频	`POST /v1/videos` 的 `callback_url`	`completed` / `failed`
批量任务	`POST /v1/batches` 的 `callback_url`，或控制台批量任务 → Webhook 账户默认	`completed` / `failed` / `cancelled` / `expired`
异步 Chat	不支持。请轮询 `GET /v1/async/chat/completions/{job_id}`。多行且需要回调请用批量任务。	—

适合后台处理结果（更新订单、落盘输出、通知用户）。

如何启用 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.5",
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 去重。

视频回调请求

认证

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

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

Request Body

idstringrequired

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

statusenum<string>required

视频任务终态。

payloadobjectrequired

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

request_idstring

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

errorobject | null

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

error.codestring

供应商或平台错误代码。

error.messagestring

可读错误信息。

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.5",
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）时触发。execution=platform 与 execution=provider 投递方式相同。

启用方式

单次：POST /v1/batches 传入 callback_url（须 HTTPS；内网/回环地址会被拒绝）。
账户默认：控制台 批量任务 → Webhook（URL + 可选签名密钥）。

两者同时存在时，以该次 callback_url 为准。都未设置则不会回调，请轮询 GET /v1/batches/{batch_id}。

Shell

1curl -X POST https://api.token360.ai/v1/batches \
2  -H "Authorization: Bearer sk-your-api-key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "input_file_id": "file_abc123",
6    "endpoint": "/v1/chat/completions",
7    "completion_window": "24h",
8    "execution": "platform",
9    "callback_url": "https://your-app.example.com/webhooks/batch"
10  }'

载荷

请求体为 batch 对象（与 GET /v1/batches/{batch_id} 一致），并带 event：


`event`	`batch.completed`、`batch.failed`、`batch.cancelled`、`batch.expired`
`id`	Batch ID（`batch_…`）
`status`	终态
`execution` / `execution_preference` / `fallback_from_provider`	实际执行路径
`request_counts`	`total` / `completed` / `failed`
`output_file_id` / `error_file_id`	有文件时出现
`usage_billing`	结算后的合计（若已 recorded）

账户 Webhook 配置了签名密钥时，请求头含 Token360-Timestamp 与 Token360-Signature（sha256= + HMAC-SHA256({timestamp}.{raw_json_body})）。校验后再处理。请在 10 秒内回 2xx。

重试

最多 3 次，单次超时 10 秒，退避 1s 再 3s。任意 2xx 停止重试。

详见批量任务与创建 batch。

此页面对您有帮助吗？