Webhook コールバック

概要

タスク形式のエンドポイントは既定で GET /api/generate/status/{task_id} の ポーリング によって結果を取得します。上流モデルが Webhook コールバック をサポートしている場合、サブミット時に input.metadata.callback_url で公開アクセス可能な HTTPS URL を透過渡し、終端状態到達時に上流が直接 POST してくれるため、ポーリングを不要にできます。

対応する上流

その他の上流（OpenAI Sora / Google Veo / Gemini Nano-Banana / OpenAI GPT Image など）は現状ポーリングのみ対応です。タスク状態取得 をご利用ください。

サブミット時にコールバックを有効化

callback_url は常に input.metadata 配下に置きます。input 直下では 許可されません：

POST /api/generate/submit
Authorization: Bearer sk-xxxxxx
Content-Type: application/json

{
  "model": "kling-v1",
  "input": {
    "prompt": "A cat playing piano in the garden",
    "metadata": {
      "callback_url": "https://your.domain/hooks/kling"
    }
  }
}

サブミットのレスポンスは callback なしの場合と同じです：

{
  "code": 200,
  "data": {
    "task_id": "task_01HF8Z3KQX2A6Y4N3R8M5W7V9P",
    "status": "not_started",
    "created_time": "2026-06-14T10:30:00"
  }
}

受信側の実装ポイント

• HTTPS エンドポイント — 多くの上流は平文 HTTP を拒否します。
• 即時 200 を返す — まず ACK を返し、業務処理は非同期化。上流のタイムアウトリトライを避けるため。
• 冪等性 — task_id をユニークキーに重複排除。リトライにより同一コールバックが複数回到達する可能性があります。
• 署名検証 — 上流が署名（Kling の JWT / タイムスタンプなど）を付ける場合、検証を通してから payload を信頼してください。
• ポーリングのフォールバック — クリティカルなタスクではコールバック欠落に備えてステータス取得を残しておくことを推奨。

ステータス取得との関係

受信する payload は 上流オリジナル の内容です。形式を統一したい場合は、コールバック受信時に タスク状態取得 を呼び出し、プラットフォーム正規化済みの files[] / status / progress を取得してください。