Webhooks とメディアジョブのライフサイクル

非同期メディアジョブの操作ガイド: webhook の登録、ステータス、ポーリング、エラーコード、課金、冪等性の制限 — すべてコード内の現在の実装に厳密に準拠しています。

1. POST /api/media/generate — 成功時は 202 と { ok: true, jobId, status: "processing" }。queued / running という個別のステータスは API にはありません。ジョブが完了するまで、クライアントには 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":...}

アカウントごとに 1 つの 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 は 1 つの論理イベントを作成し、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"
}

• 成功時に1回だけ課金されます。 finalizeJob では、遷移 processing → success|fail はアトミックです。コールバックやポーリングを繰り返しても、2回目の課金は発生しません。
• fail — 無料。 fail ステータスでは引き落としは行われません。
• 受付時の見積もり。 作成時に見積もりが保存されていた場合、成功時にはまさにその額が課金されます（実際の上流での計測額を超えることはありません）。
• 冪等性の作成 — ヘッダーによる指定。 ヘッダーなしで /api/media/generate に POST を繰り返すと、新しいジョブが作成され、成功時に新たな課金が発生します。Idempotency-Key を送信してください（最大255 ASCII文字）。同じキーと同じボディで24時間以内に再試行すると、新しいジョブを作成せずに同じ jobId が返されます。同じキーでボディが異なる場合は 422、最初のリクエストがまだ処理中の場合は 409 です。有料生成の jobId は GET /v1/generations でも表示されます（job_id フィールド）。
• Webhook は最大 5 回の試行に制限されます。 論理イベントは終端遷移ごとに 1 つ作成されますが、配信の試行は繰り返されることがあります。5 回失敗すると、イベントのステータスは FAILED になります。クライアントのハンドラーは jobId + status のペアを重複排除する必要があります。