はじめに
認証
APIキーを使用してTokenLab APIリクエストを認証する
APIキー
モデルの呼び出しおよびプライベートリソースにはAPIキーが必要です。GET /v1/models や GET /v1/models/{model} といったパブリックな探索用エンドポイントは、キーなしで動作します。探索用エンドポイントで成功レスポンスが返されても、キーが正しく機能していることの証明にはなりません。モデルリクエストを送信するには「クイックスタート」に従ってください。保存した完全なキーを使用してください。キーリストに表示されるプレフィックスでは認証できません。
OpenAI互換エンドポイントの場合は、以下のように送信します。
Authorization: Bearer sk-your-api-keyAnthropic互換の /v1/messages リクエストの場合は、以下も使用できます。
x-api-key: sk-your-api-keyGemini互換の /v1beta/* リクエストも x-goog-api-key: sk-your-api-key を受け付けます。URLはログに残ることが多いため、?key= クエリパラメータよりもヘッダーの使用を推奨します。
管理トークン
管理APIエンドポイントでは、別の種類のトークンを使用します。
Authorization: Bearer mt-your-management-token管理トークンは /v1/management/* エンドポイントでのみ使用してください。トークンの作成または再発行を行うには、選択したワークスペースの API → トークン を開いてください。トークンが表示されたら、必ずその場で保存してください。作成または再発行直後の1回のみ表示されます。
管理トークンをモデル推論に使用することはできません。また、標準の sk-... APIキーを管理APIに使用することもできません。
APIキーの取得
- TokenLabコンソール にサインインします
- API Keys を開きます
- 新しいキーを作成します
- 分かりやすい名前を付けます
- 1回しか表示されないため、すぐにコピーしてください
- クライアント側のコードでAPIキーを公開しないでください
- APIキーをバージョン管理システムにコミットしないでください
- 環境変数またはシークレットマネージャーを使用してください
- 定期的にキーをローテーションしてください
- 不要になったキーは削除してください
APIキーの使用
環境変数の設定や最初のリクエストの詳細は クイックスタート を参照してください。選択した APIフォーマット に対応するSDKを使用し、キーはサーバー側で管理してください。
キーの設定
各APIキーの設定はコンソール上、または 管理API を通じて行うことができます。
| 設定 | 説明 |
|---|---|
| 利用限度額 | 制限なしはワークスペースの残高を使用します。固定制限は、設定額に達すると 402 quota_exceeded を返します。 |
| 許可されたモデル | このキーで呼び出し可能なモデルを制限します。他のモデルは 403 model_not_allowed を返します。空の場合はキーレベルの制限はありません。 |
| 配信オプション | このキーからのリクエストに対する Auto、Verified、または Official の設定です。空の場合はワークスペースのデフォルトが使用されます。課金と価格 を参照してください。 |
| 有効期限 | この時間を過ぎると、キーは 401 expired_api_key を返します。 |
| ステータス | inactive(一時停止)状態のキーは 401 invalid_api_key を返します。revoked(失効)状態のキーは再度有効化できません。 |
キーのプレフィックス
すべてのTokenLab APIキーは sk- で始まります。
エラーレスポンス
| ステータスコード | タイプ | コード | 説明 |
|---|---|---|---|
| 401 | invalid_api_key | invalid_api_key | APIキーが存在しない、無効、非アクティブ、または失効しています |
| 401 | expired_api_key | expired_api_key | キーの有効期限が切れています |
| 402 | insufficient_balance | insufficient_balance | アカウント残高が不足しています |
| 402 | quota_exceeded | quota_exceeded | APIキーの利用制限に達しました |
| 403 | permission_error | model_not_allowed | このキーでは要求されたモデルを使用できません |
| 403 | permission_error | user_suspended, account_restricted | アカウントでAPIを使用できません |
| 429 | rate_limit_exceeded | rate_limit_exceeded | 同一IPアドレスからの認証失敗が多すぎます。Retry-After を待ってキーを修正してください。401 エラーでループさせないでください |
例:
{
"error": {
"message": "Invalid API key",
"type": "invalid_api_key",
"code": "invalid_api_key"
}
}