本番環境への組み込み

料金確認、タスクの復旧、結果の保存までを実装する手順。

モデルとプロトコルを選ぶ

認証付きの最新カタログから inputSchema と例を取得し、enabled と available が両方 true のモデルを選びます。公開モデルページは、アカウントで現在実行できる証明ではありません。タスクは /api/v1、互換クライアントは /v1 を使います。Console の Cookie を API 認証に流用しないでください。

API キーはバックエンドの環境変数で管理し、ブラウザーやアプリの配布物に含めません。型、列挙値、条件付き必須項目を最新 Schema に合わせます。公開 HTTPS のメディア URL は、モデルが対応する入力欄に直接指定できます。ローカルファイルはアップロードチケットの取得、PUT、commit の順で送り、返された spicy:// URI を対応する入力欄に渡します。モデル変更時は再検証してください。

料金を確認してから送信する

model、input、callBackUrl を含むリクエスト全体を jobs/quote に送ります。estimatedCost、maxCharge、currency、expiresAt を表示して確認を得ます。見積もりは 5 分間有効で、残高を確保しません。確定時に同じリクエストへ quoteId と expectedCost を追加します。入力変更や 40901 では再見積もりし、増額を自動承認しません。金額は十進数文字列のまま保存します。

操作記録を保存する

送信前に業務操作 ID、安全な入力フィンガープリント、Idempotency-Key を保存し、受理後に taskId と request_id を記録します。同じアカウント・API キー・操作では 24 時間以内は元のキーを再利用します。タイムアウトは未受理の証拠ではありません。終端の失敗から再試行すると、現在の条件で別タスクが作成されます。

コールバックと結果を処理する

受信した生のバイト列で署名と時刻を検証し、重複を除いて永続化してから速やかに応答します。重い処理は自社のキューに移し、遅延・重複通知を状態に応じて扱います。補助ポーリングは recordInfo に対して上限付きの指数バックオフを使います。202 は受理、succeeded は生成成功、settled=true は精算完了です。

同時実行と保存期間を管理する

アカウントごとの実行中件数と通信時間を制限します。429 は Retry-After に従い、一斉の毎秒ポーリングを避けます。カタログは短時間のプライベートキャッシュに留めます。署名付き URL は 20 分、生成メディアは 14 日、入力ファイルは 1 日で期限を迎えるため、必要な結果は保存してください。切断ではタスクは取り消されません。

公開前に確認する

最初はカタログ、残高、見積もりを確認し、費用確認後に最小の生成を試します。正常終了、不正な入力、残高不足、同じキーでの復旧、重複通知、期限切れ URL、予算制限を検証します。ログには request_id、taskId、時刻、状態、金額を記録し、キーやプロンプト全文は残しません。