認証
キーの形式、キーごとの制限、参照できるタスク、キー漏えい時に直ちに行う対処。
作成、読み取り、課金を行うすべての API 呼び出しで、Authorization に API キーを送ります。評価用の公開モデルカタログだけは例外で、キーが不要です。
Authorization: Bearer sk-spicy-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxネイティブ API（/api/v1/*）は Bearer キーだけを受け付け、Cookie やクエリのパラメーターは使えません。
テキスト・動画の互換エンドポイント（/v1、/v1beta）は同じキーを使い、Anthropic SDK の x-api-key と Google GenAI SDK の x-goog-api-key も受け付けます。公式 SDK はベース URL の変更だけで使えます。テキストとストリーミング参照。この 2 ヘッダーは /api/v1 では効かず、URL のクエリ内のキーは、どのエンドポイントでも使えません。
API キーとコンソールは別です
API キーを受け付けるのは /api/v1、/v1、/v1beta です。ウェブコンソールは独自のブラウザーセッションを使います。ログインを API キーには使えず、漏れた API キーでコンソールへログインすることもできません。違う種類の認証情報は常に 401 で、権限エラーではありません。
キーの形式
固定の sk-spicy- に、小文字の 16 進数 48 文字が続きます。
| 部分 | 目的 |
|---|---|
sk-spicy- | ログ、リポジトリ、GitHub の秘密情報検出で見分けられる固定の接頭辞 |
| 次の 8 文字 | 記録を速く探すための検索部分。検証はキー全体で行う |
| 残りの 40 文字 | 秘密情報の残り。全体に pepper を加えた SHA-256 ハッシュだけを保存するため、当社も元のキーを読み戻せない |
接頭辞は意図したものです。他人が残高を使った後で気付くより、検出され通知される方がよいためです。
キーは 1 回だけ表示します
閉じる前にコピーするか、ファイルとして保存 を押します。失ったら新しいキーを作ります。復元はできません。復元できるなら平文保存という意味になるため、この設計にしています。
キーを作る
- コンソール → API キー で キーを作成 を押します。
production backend、staging workerなど、使用するサービスの名前を付けます。失効するとき見分ける必要があります。- 必要なら 詳細設定 で支出上限、許可モデル、IP の許可リスト、有効期限を設定します。すべて後で変更できます。
- コピーか ファイルとして保存 を使い、保存できたことを確認します。閉じると再表示できません。
作成にはチームの owner、admin、developer の役割が必要です。左上で選んだチームに属し、使用量と上限もそのチームへ計上します。各チームは有効なキーを最大 50 個持てます。有料処理には認証済みメールと残高も必要です。アカウント設定を参照してください。
キーの保管場所
- 手元のテスト： ターミナルで
export SPICY_API_KEY="…"を使います。ウィンドウを閉じるまで有効です。またはコードが読む.envに置き、最初のコミット前に.envを.gitignoreへ入れます。 - サーバーやホスティング： 秘密情報または環境変数の設定へ置き、コードで環境の
SPICY_API_KEYを読みます。 - ソース、チャット、スクリーンショット、問い合わせ、AI 補助のプロンプトへは決して貼りません。
クライアントへ配布しない
ブラウザーやアプリに入れた情報は取り出せます
バンドル、難読化、複数ファイルへの文字列分割は保護になりません。開発ツールや逆コンパイラーで取得でき、漏れたキーは残高か上限を使い切るまで動きます。
フロントエンドで生成するなら、自分のバックエンドを経由します。ブラウザーが自分へ、自分が当社へ呼び出します。その層でユーザー別の上限も適用できます。
モバイルアプリ、デスクトップクライアント、公開 notebook、CI ログ、サポートへ貼る curl -v の出力にも同じことが当てはまります。
自分のブラウザーで、自分だけが使うツールは別です。 API はブラウザーからの呼び出しに対応するため、SillyTavern 拡張や、自分のキーを貼るロールプレイアプリは直接呼べます。上の規則は、他人が読み込むものへキーを入れる場合です。各ツールに日次上限付きの別キーを与え、支出を確認し、個別に失効できるようにします。
キーごとの制限
作成時または後でコンソールから設定します。サーバー側で適用します。
| 制限 | 効果 | 到達時の業務コード |
|---|---|---|
| 日次支出上限 | 新規キーは設定しなければ上限なし。自分で金額を設定し、設定ミスや漏えいの支出を制限。UTC の日ごとに更新 | 40202 |
| 月次予算 | UTC の現在の暦月で使える額 | 40202 |
| 累計支出上限 | キーの生涯の支出額。パートナーへ渡すキーに便利 | 40202 |
| 有効期限 | UTC の指定日の終了時に無効 | 401 |
| IP の許可リスト | 一覧のアドレス・CIDR だけ許可。サーバー連携に推奨 | 40302 |
| モデルの許可リスト | テストを安価なモデルだけにするなど。無制限なら後で追加したモデルも呼べる | 40301 |
キーのカードで現在の上限を表示し、いつでも変更できます。
上限には支出済み額と、実行中タスクの予約額も含むため、進行中に上限へ届くことがあります。msg はどの上限かを示します。40202 の msg がプラットフォームの枠を示すなら、キーの問題ではありません。別キーを作っても直らないため、後で再試行します。
IP の一覧は最後のプロキシではなく、エッジが見る実際の公開アドレスに照合します。送信元アドレスはサーバー要求が出る公開 IP です。多くのホストはネットワーク設定に載せ、手元なら curl https://ifconfig.me で分かります。
タスクは作成したキーに属する
API から見えるのは、作成した API キーだけです。同じチームでも他のキーでは次のようになります。
| 別のキーで行う操作 | 結果 |
|---|---|
読み取り（recordInfo）、再試行、破棄、ダウンロードリンク取得 | 存在しないタスクと同じ 404 |
履歴（GET /api/v1/jobs）、使用量（GET /api/v1/usage） | そのキー自身のタスクと支出だけ |
同じ Idempotency-Key で作成を再送 | 元の ID を含まない 409 |
キー変更後の 409 は、タスク未作成を意味しません
あるキーでタイムアウトし、別キーで再送した場合、409 の背後で、すでに実行・課金されるタスクがある可能性があります。「作られていない」と見なし、新しい冪等性キーで再送しないでください。二重生成への支払いになります。最初の API キーで再送するか、コンソールで探します。
2 つはキーと独立しています。タスクの Webhook は作成キーの失効後も届きます。また、どのキーで作ってもチームの全タスクを コンソール → ログ で確認でき、詳細に 使用したキー を表示します。
キーの交換
- production、staging、local など環境ごとに 1 キーを使い、他に影響せず失効できます。
- 計画的な交換： 新しいキーを作り、新しいタスクだけで使います。古いキーの全タスクが終端へ達し（遅くとも各
deadlineAt）、結果を回収してから古いものを失効します。古いキーがまだ信頼できる場合だけの手順です。 - 失効は即時で、元に戻せません。 キャッシュの待機も再有効化もなく、新規作成が必要です。
漏えい後
直ちに失効する
コンソール → API キー で操作を開き、失効 を選びます。即時に適用します。
自分の進行中タスクを待たないでください。そのキーで API から読むことはできなくなりますが、受理済みタスクは継続し課金されます。Webhook または コンソール → ログ から回収します。漏えい時は待つべきではありません。
代わりを作る
新しいキーを作り、サーバー設定を更新します。準備中も漏れたキーを有効に残さないでください。
使用状況を確認する
漏えい期間の コンソール → ログ で、知らないモデル、異常な件数、説明できない支出を探します。詳細の 使用したキー と、CSV をエクスポート の各タスクのキー ID で確認できます。キーのページにも最終使用時刻があります。
新しいキーの制限を強める
適切な IP の許可リストと日次上限を設定し、コード、ログ、配布設定から元の露出を除きます。
予想外の支出があれば、タスク ID または request_id を添え コンソール → サポート へ連絡します。
認証失敗の応答
{
"code": 401,
"msg": "Credentials are invalid or expired",
"request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}HTTP 状態も 401 です。すべての認証失敗が code: 401 を返し、msg で種類を示します。
msg の始まり | 状況 | 対処 |
|---|---|---|
Missing credentials | キーが届いていない | Authorization: Bearer … と、送信プロセスの SPICY_API_KEY を確認。別のターミナルの変数は引き継がれない |
API key format is not recognized | 送信値が SpicyAPI のキーではない | sk-spicy- で始まるか、Bearer の不足、文字の不足・追加、引用符、改行を確認 |
Credentials are invalid or expired | 正しい形式だが存在しない、失効済み、期限切れ | 存在を探られないよう意図的に区別しない。コンソール → API キー で状態確認か新規作成 |
文章ではなく code で分岐します。言い回しは変わり、エラー言語に従います。詳しくはエラーを参照してください。
メール未認証やアカウント停止など、アカウント自身が呼べない場合は 403 です。キーを変えても直りません。