基本概念
冪等なリクエスト
生成の送信には 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"
}
}自動的に新しいキーへ置き換えず、入力の変更が意図した新しい生成なのか、クライアントの不具合なのかを確認します。
受付結果が分からない場合の再試行
- 送信前にキーを作成します。
- アプリケーションの処理記録にキーと入力を保存します。
- 通信切断やタイムアウトでは、同じ入力とキーで再送します。
- 返されたジョブ ID を保存し、
status_urlで現在の状態を確認します。
queue_full、provider_capacity_exceeded、provider_rate_limited、再試行可能な provider_submission_failed でも同じキーを使います。残高不足やキーの利用上限など確定した拒否は、原因を解消してから新しいキーで送ります。エラーと再試行も確認してください。