基本概念

冪等なリクエスト

生成の送信には Idempotency-Key を付けます。通信切断やタイムアウトで受付結果が分からないときも、一つの生成には同じキーを使います。

export IDEMPOTENCY_KEY="$(uuidgen)"
curl --request POST https://api.orchestor.io/v1/creative/image-router/generate \
  --header "Authorization: Bearer $ORCHESTOR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{"model":"gpt-image-2","prompt":"朝の光が差し込む湖","mode":"async"}'

応答を受け取れなかった場合は、同じ入力とキーで再送します。同じジョブが返り、idempotency_hit で再送だったかを確認できます。

キーのルール

  • 1〜255 文字の印字可能な ASCII 文字を使います。UUID を使用できます。
  • 生成の前にキーを作り、入力と一緒に保存します。
  • 同じ生成の再試行ではキーと入力を変えません。
  • 意図的に別の生成を依頼する場合は、入力が同じでも新しいキーを作ります。
  • 受付済みのジョブを待つときは、再送せず状態を取得します。

パラメーターの不一致

同じキーで異なる入力を送ると 409 になります。エラー本文の error.code と error.message を確認してください。

{
  "error": {
    "code": "idempotency_conflict",
    "message": "同じ冪等性キーで入力が変わっています。別の生成なら新しいキーを使用してください。",
    "request_id": "req_00000000000000000000000000000000",
    "category": "validation",
    "stage": "validation",
    "retryable": false,
    "retry_after_seconds": null,
    "public_reason": "idempotency_conflict",
    "next_action": "fix_input"
  }
}

自動的に新しいキーへ置き換えず、入力の変更が意図した新しい生成なのか、クライアントの不具合なのかを確認します。

受付結果が分からない場合の再試行

  1. 送信前にキーを作成します。
  2. アプリケーションの処理記録にキーと入力を保存します。
  3. 通信切断やタイムアウトでは、同じ入力とキーで再送します。
  4. 返されたジョブ ID を保存し、status_url で現在の状態を確認します。

queue_full、provider_capacity_exceeded、provider_rate_limited、再試行可能な provider_submission_failed でも同じキーを使います。残高不足やキーの利用上限など確定した拒否は、原因を解消してから新しいキーで送ります。エラーと再試行も確認してください。