如何对视频生成使用 webhook 和轮询？

将轮询作为视频生成的基线方案，因为每个异步任务都会返回一个可供查询的任务 ID。仅当所选视频端点支持回调 URL 时再添加 webhook，并始终将轮询作为处理回调丢失或提供商特定回调投递问题的事实来源。

创建视频任务

以下请求会创建一个最小化的视频任务，并存储返回的 ID。仅当所选模型页面文档说明了这些字段时，再添加时长、分辨率或回调字段。

curl https://api.cometapi.com/v1/videos \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -F "model=doubao-seedance-2-0" \
  -F "prompt=A cinematic shot of a paper airplane crossing a desk"

响应中包含任务 ID 和状态：

{
  "id": "task_example",
  "task_id": "task_example",
  "object": "video",
  "model": "doubao-seedance-2-0",
  "status": "queued",
  "progress": 0,
  "created_at": 1779872000
}

轮询状态

以下请求用于检查视频任务状态：

curl https://api.cometapi.com/v1/videos/task_example \
  -H "Authorization: Bearer $COMETAPI_KEY"

响应会随着任务推进而变化。完成后的响应在模型适配器提供结果 URL 时可以包含 video_url；否则，请使用模型特定的结果字段，或在该模型支持代理下载时使用 /v1/videos/{id}/content 内容路由。

{
  "id": "task_example",
  "object": "video",
  "model": "doubao-seedance-2-0",
  "status": "completed",
  "progress": 100,
  "completed_at": 1779872300,
  "video_url": "<generated-video-url>"
}

接收 webhook

CometAPI 并未为每个视频模型定义一个通用的统一回调 payload。应将回调视为提供商特定的透传事件，存储原始请求体，并通过轮询核对最终状态。以下 Express 处理器接收视频回调并存储事件：

import express from "express";

const app = express();
app.use(express.json({ limit: "2mb" }));

app.post("/cometapi/video-webhook", async (request, response) => {
  const event = request.body;

  console.log("Task ID:", event.task_id || event.id);
  console.log("Status:", event.status);

  response.status(200).json({ received: true });
});

app.listen(3000);

回调 payload 通常包含任务标识和状态字段，但具体嵌套结构取决于所选模型或提供商：

{
  "task_id": "task_example",
  "status": "completed",
  "progress": 100,
  "result": {
    "video_url": "https://example.com/result.mp4"
  }
}

常见错误

错误	解决方法
回调丢失	按任务 ID 轮询，直到你的应用已存储终态。
重复回调	以任务 ID 为依据，让回调处理具备幂等性。
回调被拒绝	尽快返回 `2xx` 响应，然后在后台处理任务。
提供商特定 payload 不匹配	存储原始回调 payload，并在你的应用中将其标准化。
缺少 `video_url`	将 `video_url` 视为可选字段，并在可用时结合轮询与模型特定结果字段或 `/v1/videos/{id}/content` 使用。

Documentation Index

​创建视频任务

​轮询状态

​接收 webhook

​常见错误

​相关链接

创建视频任务

轮询状态

接收 webhook

常见错误

相关链接