本番環境への組み込み

実際のユーザーや実際のお金がこの組み込みに頼るようになる前に、このページをチェックリストとして使ってください。各セクションでは、何をするか、なぜ重要か、詳しい説明がどこにあるかを示しています。まだ最初の呼び出しを試していない場合は、アカウントの準備とクイックスタートから始めてください。

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

• キーで実際に呼び出せるモデルを選ぶ。 API キーを付けて GET /api/v1/models を呼び出し、enabled と available がどちらも true のモデルだけを使います。同じ応答から、モデルの inputSchema（受け付けるフィールドの一覧）と examples を読みます。Web サイトのモデルページでわかるのはモデルに何ができるかであって、あなたのキーがいまそのモデルを呼び出せることの証明にはなりません。モデルを参照してください。
• 正しい入り口を使う。 画像・動画などのメディアのタスクには、/api/v1 配下のタスク API を使います（createTask を呼び、そのあと recordInfo かコールバックで結果を受け取ります）。テキストモデルは、/v1 配下で OpenAI 互換・Anthropic 互換のクライアントから、または /v1beta 配下で Gemini 互換のクライアントからも呼び出せます。テキストとストリーミングを参照してください。
• 認証には API キーだけを使う。 コンソールのログイン Cookie は API の認証情報ではないので、決してコードにコピーしないでください。

キーと残高を守る

• キーはサーバーに置く。 バックエンドの環境変数（SPICY_API_KEY）に入れ、ブラウザーのコード、モバイルアプリ、公開リポジトリには絶対に入れないでください。認証を参照してください。
• 環境とサービスごとに 1 本のキーを使う。 各キーには、使うものにちなんだ名前（たとえば「production-worker」）を付けます。そうすれば、ほかを止めずに 1 本だけ失効させられます。
• 本番用のキーに上限を設定する： 最悪の日を想定した日次上限、月間予算、利用を許可するモデル、そしてサーバーから呼び出す場合は IP 許可リストです。認証のキーごとの制限についての説明を参照してください。キーを編集するときは、上限の欄を空欄にすると上限なしになることを忘れないでください。
• 有効期限を確認する。 有効期限を設定したキーは、その日の終わり（UTC）に使えなくなり、失効したキーと同じ 401 が返るようになります。日付をカレンダーに入れておくか、長く動かし続けるバックエンドでは有効期限を設定しないでください。
• バッチの途中で残高を切らさない。 残高不足で拒否されたタスクには 40201 が返り、キューに入ることもありません。通知で残高不足アラートをオンにし、自動チャージも検討してください。
• チームの上限も適用される。 キーがチームに属している場合、キー自身の上限に達していなくても、チームの日次・月次の上限によってタスクが 40202 で止まることがあります。また、すべてのタスクはチームのオーナーの残高から支払われます。課金の利用上限についての説明を参照してください。
• Webhook 署名キーのローテーションを計画する。 コンソールでキーをローテーションすると、新旧のキーを併用できる期間はありません。古いキーによる署名はその場で止まり、まだ再試行中の配信も新しいキーで署名されます。ローテーションは落ち着いた時間帯に行い、新しいキーをすぐに受信側へ反映し、受け取り損ねたものは recordInfo で回収してください。Webhook の署名キーについての説明を参照してください。

サーバーで入力を準備する

• 現在のスキーマで検証する。 inputSchema にあるフィールドの型、許可される値、条件付きの必須項目に従ってください。スキーマはモデルごとに異なるので、モデルを切り替えたら検証し直します。
• メディアは対応している方法で送る。 公開されていてアクセスできる https:// の URL か、対応している Base64 の入力を使います。ローカルのファイルは、アップロード URL を発行し、そのバイト列を PUT で送り、files/{fileId}/commit を呼び出してから、返ってきた spicy:// URI をモデルの入力フィールドに渡します。メディアを参照してください。
• アップロードしたファイルは有効期間内に使う。 spicy:// URI は、確定（commit）したときの応答にある expiresAt（既定では 1 日後）まで使えます。使う予定のないアップロード URL をまとめて発行しないでください。使われないままの URL も、制限の対象として数えられます。レート制限を参照してください。

課金を受け入れる前に見積もる

• お金を使う前に価格を見せる。 model、input、callBackUrl をすべて含めて POST /api/v1/jobs/quote に送ります。支払う人に、estimatedCost、maxCharge、通貨（USD）、expiresAt を見せてください。見積もりは無料で、タスクは作られず、資金も仮押さえされません。
• 確認を得た内容をそのまま送信する。 見積もりの有効期間は 5 分です。確認を得たら、同じリクエストに quoteId と expectedCost を加えて createTask に送ります。
• 40901 に対応する。 これは、見積もりのあとで、見積もりの期限切れ、入力の変更、価格の変更のいずれかが起きたことを意味します。新しく見積もりを取り、新しい金額を見せてください。高くなった金額を黙って受け入れてはいけません。見積もりを参照してください。
• 金額を正確に扱う。 金額は "0.008" のような十進数の文字列です。浮動小数点ではなく、十進数の演算で保存・加算してください。課金の残高の確認についての説明を参照してください。

業務上の操作を記録する

ネットワーク呼び出しが途中で失敗したときに復旧できるかどうかは、自分の側の記録にかかっています。

• 送信前に保存する： 自社の注文 ID や操作 ID、リクエストの短い説明（秘密情報やプロンプト全文を含まず、あとで見分けられる程度のもの）、そして送信する Idempotency-Key。
• 受理後に保存する： 応答にある taskId と request_id。
• 同じ送信には同じキーを使い回す。 同じアカウント、同じ API キー、同じリクエストについて、24 時間以内に元の Idempotency-Key をもう一度送れば、2 回目の課金ではなく元のタスクが返ってきます。冪等性を参照してください。
• タイムアウトは「失敗」ではなく「不明」として扱う。 新しいタスクを作るかどうかを決める前に、元のキーを使って元の送信を回復してください。トラブルシューティングと復旧を参照してください。
• 再試行にかかる費用を知っておく。 すでに失敗したタスクを再試行すると、現在の条件と価格で新しいタスクが作られます。

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

• すべてのコールバックを検証する。 解析する前に、受け取ったリクエストの元のバイト列に対して署名とタイムスタンプを確認し、そのあとで重複を除いてイベントを保存します。Webhook を参照してください。
• すぐに応答する。 ただちに 2xx で応答し、時間のかかる処理は自分のキューで行ってください。
• 重複や遅延を前提にする。 何をするかは、コールバックが届いた順番ではなく、タスクの state で判断します。
• 予備としてポーリングを残しておく。 コールバックが遅れている場合は、毎秒ではなく、間隔を徐々に延ばしながら recordInfo を読みます。
• 正しい合図を読む。 createTask の HTTP 202 はタスクが受理されたこと、state: "succeeded" は生成が終わったこと、settled: true は課金額が確定したことを意味します。

同時実行数を抑え、結果を保存する

• 実行中のタスク数をアカウントごとに制限し、自分のリクエストにも締め切りを設けてください。受理されたタスクは、精算されるまで資金を仮押さえし続けます。
• 429 では Retry-After に従い、多数のクライアントが足並みをそろえて毎秒ポーリングするのは避けてください。レート制限を参照してください。
• カタログのデータは、短時間だけ、外部と共有しない形でキャッシュし、見積もりを恒久的な価格表として扱わないでください。
• 残しておく必要のある結果は保管する。 ダウンロードリンクの有効期間は 20 分、生成されたメディアの保存期間は最長で約 14 日、アップロードしたファイルは 1 日です。これらの期間は短くでき、POST /api/v1/jobs/purge を使えば、タスクの内容をもっと早く削除することもできます。なお、保存期間の設定を短くすると、すでに実行したタスクの結果も削除されることがあります。データ保存と破棄を参照してください。
• 接続を切れば処理が止まると考えない。 受理されたタスクは実行を続け、キャンセルできません。

公開前に検証する

まず無料の呼び出しから始めます。カタログ（GET /api/v1/models）、残高（GET /api/v1/chat/credit）、見積もりです。次に、自分で用意した費用確認の流れを通して、小さな実際の生成を 1 回実行します。これはほかのタスクと同じように課金されます。組み込みが次のそれぞれに正しく対応できるか確認してください。

request_id、taskId、時刻、state、金額をログに記録してください。API キーとプロンプト全文は、一般的なログに残さないでください。

関連する手順

見積もりとプロトコル互換 · モデルカタログとスキーマ · メディア · Webhook · エラー · トラブルシューティングと復旧 · 課金 · データ保存と破棄