Webhook 回调 - VidoCraft API 文档

创建任务时传入 callback_url，任务进入终态（completed、failed、canceled）后 API 会向该地址 POST 任务内容。请求体与 GET /api/v1/tasks/:id 的响应完全一致——一个处理函数可以同时服务两者。

投递为尽力而为：最多尝试 2 次、单次超时 8 秒。请把回调当作唤醒信号：收到后（以及一直没收到时的兜底）都应调用 GET /api/v1/tasks/:id 确认最终状态。回调不带签名——以重新拉取为准。

URL 必须是公网可达的 HTTPS 地址——localhost 与私网地址会被拒绝。沙盒（测试密钥）任务也会在创建约 35 秒后触发同样的回调，可以零成本开发你的回调处理逻辑。

创建任务时带上 callback_url，然后处理这个 POST——请求体与 GET /api/v1/tasks/:id 的响应完全一致：

// e.g. a Next.js / TanStack Start route handler
export async function POST(request) {
  const task = await request.json();

  if (task.status === 'completed') {
    const urls = task.data.results;   // download / store promptly
  }
  if (task.status === 'failed') {
    console.error(task.failed_reason); // credits were refunded
  }

  // Recommended: confirm via GET /api/v1/tasks/:id before acting.
  return new Response(null, { status: 200 });
}

尽快返回任意 2xx；耗时处理请异步进行。