API キーを更新 | ToAPIs Documentation

PATCH

/api/v1/api-keys/{api_key_id}

中国本土のユーザー向け: 中国本土のユーザーは https://api.toapis.cn を API エンドポイント (Base URL)としてご利用ください. 本ドキュメント内の例では https://api.toapis.com を https://api.toapis.cn に置き換えてください.

動作

指定キーの設定を更新し, 名前, 上限, 状態, 有効期限などを調整できます. リクエスト本文には少なくとも 1 フィールドが必要です. 名前, モデル許可リスト, 日/月上限, unlimited, 残クォータ, 状態, 有効期限を指定でき, 省略したフィールドは現値を保持します.

有効化と状態

設定変更だけではキーは再有効化されません.
同じリクエストで status=enabled を指定した場合, 更新後の有効期限, unlimited, クォータをまとめて検証します. 期限切れまたは有限クォータ枯渇のキーは有効化できず 409 を返します.
失効済みキーは 404 を返します.
status を省略すると保存済みの状態は変わりません. disabled/expired/exhausted のキーは他フィールドの更新で自動復帰せず, enabled のキーはクォータと有効期限から読み取り状態が派生するため, 更新後に enabled へ戻る場合があります.

検証と書き込み

金額フィールドの検証は作成と同じで, JSON 数値や正確に換算できない値は拒否します.
model_limits に [] を指定するとモデル制限を解除します. 日/月上限に null または "0" を指定すると上限を解除しますが, 利用済みカウンターはリセットされません.
remaining_credits を設定するとデータベースに保存された残クォータが上書きされ, 以降の課金・返金は新しい値から増減します. 発生済みでまだ書き込まれていないバッチ課金も後からそのまま適用されます.
更新は累計使用量やアカウント残高を変更しません.
いずれかのフィールドが検証に失敗した場合, リクエスト全体が書き込まれず部分的な更新は起きません. 更新はトランザクション内で最終設定をまとめて検証し, 明示的に指定されたフィールドのみ書き込みます.
キャッシュ無効化と処理中リクエストの適用境界は従来どおりです.

認証

Authorizationstringヘッダー必須

Bearer YOUR_SYSTEM_ACCESS_TOKEN を使用します. モデルキーは不可, X-User-Id は不要です. 共通ルールは利用方法を参照してください.

リクエストパラメータ

api_key_idstringパス必須

自分の通常モデルキーの十進 ID 文字列. sk- シークレットではありません.

空でない本文は Content-Type: application/json が必要で, 上限は 16384 バイトです. 最上位は JSON オブジェクトとし, 未知または重複するフィールドやクエリパラメータは拒否します. 本文の読み取り期限は 10 秒です.

statusstringボディ

enabled または disabled のみ. expired, exhausted, deleted は読み取り専用.

expires_atstring | nullボディ

未来の RFC 3339 日時, 小数秒は切り上げ. null または作成時の省略は無期限. 更新時の省略は元の値を保持.

namestringボディ

指定時は前後の空白を除き, 空でない名前を 50 UTF-8 バイト以内で指定します. 省略時は維持します.

model_limitsarrayボディ

モデル許可リスト全体を置き換えます. [] は制限解除, null は拒否です. 各項目の空白を除き, 空やカンマを拒否し, 初出順に重複を除きます. カンマ連結後は 1024 UTF-8 バイト以内です.

daily_limit_creditsstring | nullボディ

日次 credits 上限. null または文字列 "0" は無制限.

monthly_limit_creditsstring | nullボディ

月次 credits 上限. null または文字列 "0" は無制限.

unlimitedbooleanボディ

真偽値のみで null は拒否します. false に戻し remaining_credits を省略すると, 保存済みのクォータ残高を維持します (すでに枯渇している場合もあります). 自動で有効化しません.

remaining_creditsstring | nullボディ

残高を絶対値で設定します. 加算ではありません. 最終 unlimited=false では非負の十進数文字列のみ, true では省略または null のみ受け付けます. 省略すると保存済みの残高を維持し, null でも無制限キーに保存された残高は消去されません.

allow_ipsarrayボディ

このモデル API Key の接続元 IP だけを制限する文字列配列. 単一の IPv4/IPv6 アドレスを指定し, 空白除去, 正規化, 重複除去を行います. [] は制限解除, null や無効な値は 400 です. CIDR, ホスト名, ポート, IPv6 zone は未対応です. PATCH の省略は維持します.

リクエスト例

curl --request PATCH \
  --url 'https://api.toapis.com/api/v1/api-keys/43' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"status": "disabled"}'

import requests

response = requests.patch(
    "https://api.toapis.com/api/v1/api-keys/43",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    json={'status': 'disabled'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.toapis.com/api/v1/api-keys/43", {
  method: "PATCH",
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN", "Content-Type": "application/json" },
  body: JSON.stringify({"status": "disabled"}),
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

レスポンスフィールド

例は架空のデータです. メタデータはキー詳細, 共通のレスポンスとエラーは利用方法を参照してください.

レスポンス例

{
  "code": 0,
  "message": "",
  "data": {
    "id": "43",
    "name": "Example Key",
    "key_hint": "****xyz9",
    "status": "disabled",
    "created_at": "2026-11-01T08:00:00Z",
    "expires_at": "2027-01-01T00:00:00Z",
    "unlimited": false,
    "remaining_credits": "500",
    "daily_limit_credits": null,
    "monthly_limit_credits": null,
    "model_limits": [],
    "allow_ips": []
  }
}