タスク完了コールバック（Webhook）

​

クイックスタート

curl -X POST https://あなたの接続ドメイン/v1/images/generations \
  -H "Authorization: Bearer あなたのAPIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red apple on a table",
    "size": "1024x1024",
    "webhook": "https://your-server.com",
    "language": "ja"
  }'

​

エラーメッセージの言語を指定

• 大文字と小文字は区別されず、前後の空白は自動的に削除されます。たとえば、"JA" と " ja " はどちらも ja として扱われます。
• 表にある2文字コードを使用してください。zh-CN、en-US、pt-BR などの地域タグは認識されません。
• サポートされていない値でもタスク送信は失敗せず、コールバックには元のエラーメッセージが含まれます。
• 元のメッセージがすでに対象言語の場合、再翻訳せずそのまま返されます。
• 翻訳に失敗した場合も、コールバックを遅延または破棄せず、元のメッセージを返します。

​

URLのルール

​

受信する内容

{
  "id": "task_01KV7FXR8BEYS1BWHJCT3JMCJ5",
  "status": "completed",
  "progress": 100,
  "created": 1781589029,
  "completed": 1781589058,
  "actual_time": 29,
  "cost": 0.006,
  "credits_cost": 0.06,
  "result": {
    "images": [{ "url": ["https://.../result.png"], "expires_at": 1781675458 }]
  }
}

{
  "id": "task_xxx",
  "status": "failed",
  "progress": 100,
  "created": 1781589029,
  "completed": 1781589050,
  "error": {
    "message": "入力画像にアクセスできません。URLがインターネットからアクセス可能であることを確認してください",
    "type": "task_failed",
    "param": "",
    "code": "task_failed"
  }
}

​

リトライと重複排除（重要）

• リトライ: サーバー側が約10秒以内に 2xx を返さない、または 5xx を返した場合、自動的に最大 3回 リトライします。間隔は約 10秒、30秒、60秒 です。3回とも失敗すると諦めます（約2分以内に終了）。
• リトライしないケース: エンドポイントが 4xx を返した場合（URL / リクエストに問題があると見なす）、リトライせずに直ちに諦めます。
• 重複排除: 通常、1つのタスクは1回のみプッシュされます。ただし極端なケース（送信後・確認前に当方で再起動が発生した場合など）では、重複プッシュを受信する可能性があります。重複処理を避けるため、必ず id（task_id）で冪等に重複排除 してください。

​

コールバックURLの要件

​

よくある質問

​

最小の受信側サンプル

from http.server import BaseHTTPRequestHandler, HTTPServer
import json

class H(BaseHTTPRequestHandler):
    def do_POST(self):
        n = int(self.headers.get("Content-Length") or 0)
        body = self.rfile.read(n)
        data = json.loads(body)
        print("タスクコールバックを受信:", data["id"], data["status"])
        # TODO: id で重複排除し、署名を検証してから処理する
        self.send_response(200); self.end_headers()
        self.wfile.write(b'{"ok":true}')

HTTPServer(("0.0.0.0", 443), H).serve_forever()