Webhooks 与媒体作业生命周期

异步媒体任务操作指南：webhook 注册、状态、轮询、错误代码、费用和幂等性限制，严格依据代码中的当前实现。

1. POST /api/media/generate：成功时202并{ ok: true, jobId, status: "processing" }。API 没有单独的 queued / running 状态：在任务完成前，客户端会看到 processing。
2. 上游可能会经历内部阶段（waiting、generating），这些阶段不会反映在公共 API 中；轮询期间，作业会保持为 processing。
3. 终端状态：success（包含 resultUrls，成功后计费）或 fail（不收费）。
4. 完成记录只会写入一次：通过上游回调，或在 GET /api/media/jobs/{id} 中进行延迟轮询时写入。

# 2. poll the job until it is ready
curl https://getvibeapi.com/api/media/jobs/JOB_ID \
  -H "Authorization: Bearer $GETVIBE_API_KEY"
# → {"status":"success","resultUrls":["https://..."],"priceRub":...}

每个账户一个 URL：mediaWebhookUrl。在 控制面板 → Webhooks 中配置，或通过 API 使用账户会话（登录后的 cookie）进行配置。该端点不接受 sk-pv-…，只能接受经过身份验证的会话。

# Example (a dashboard session is required, not an API key)
curl -X PATCH https://getvibeapi.com/api/webhooks \
  -H "Content-Type: application/json" \
  -b "session=YOUR_SESSION" \
  -d '{"mediaWebhookUrl":"https://example.com/webhooks/media"}'

# Clear the URL
curl -X PATCH https://getvibeapi.com/api/webhooks \
  -H "Content-Type: application/json" \
  -b "session=YOUR_SESSION" \
  -d '{"mediaWebhookUrl":null}'

当作业达到终止状态时，GetVibe 会创建一个逻辑事件，并通过 POST 将其传送到已注册的 mediaWebhookUrl。传送次数有限：服务总共最多尝试 5 次。同一有效负载可能会到达多次。

// POST to your mediaWebhookUrl when a job finishes
{
  "jobId": "...",
  "status": "success",            // or "fail"
  "model": "veo-3.1",
  "kind": "video",                // image | video | audio | music | 3d
  "resultUrls": ["https://getvibeapi.com/api/media/file/..."],
  "failMsg": null,
  "createdAt": "2026-06-17T10:00:00.000Z"
}

• 成功时只收费一次。 在 finalizeJob 中，转换 processing → success|fail 是原子的：重复回调或轮询不会产生第二次收费。
• fail — 免费。 状态为 fail 时不会扣费。
• 入站报价。 如果创建时保存了报价，则成功时会严格按该报价收费（绝不会超过上游实际计量的费用）。
• 通过 header 创建幂等性。 向 /api/media/generate 重复发送不带该 header 的 POST 请求，会在成功时创建新的任务并产生新的费用。请发送 Idempotency-Key（最多 255 个 ASCII 字符）：在 24 小时内使用相同 key 和请求体重试时，会返回相同的 jobId，不会创建新任务；相同 key 搭配不同请求体会返回 422，而在第一个请求仍在处理时会返回 409。付费生成的 jobId 也会显示在 GET /v1/generations 中（job_id 字段）。
• Webhook 最多尝试五次。 每次终止状态转换都会创建一个逻辑事件，但投递尝试可能重复。五次失败后，事件状态会变为 FAILED。客户端处理程序必须对 jobId + status 这一对值进行去重。