API Key を更新する

PATCH /api/open/v1/keys/:id

リクエストパラメーター

リクエストボディに含まれるフィールドのみが更新され、含まれないフィールドは変更されません。少なくとも 1 つの更新可能なフィールドが必要です。空のボディ、null、{} は 400 を返します。

パラメーター	位置	型	必須	説明
id	path	integer	はい	Key ID。正の整数
name	body	string	いいえ	名前。前後の空白を除いて空にできません。最大 50 文字（文字数。バイト数ではありません）
status	body	integer	いいえ	1 有効化、2 停止。それ以外の値は 400 を返します（3 / 4 は自動設定）。
expired_time	body	integer	いいえ	有効期限、unix 秒。0 / -1 は無期限
remain_amount	body	number	いいえ	利用可能額。サイトの表示通貨、小数点以下 2 桁。負の値および上限を超える値は不可
unlimited	body	boolean	いいえ	無制限にするかどうか
model_limits_enabled	body	boolean	いいえ	モデル許可リストを有効にするかどうか
model_limits	body	string	いいえ	許可するモデル。半角カンマ区切り
allow_ips	body	string	いいえ	許可する IP。改行区切り。空文字列は制限なし

status は 1（有効化）または 2（停止）のみ受け付けます。有効化には、今回の更新後に Key が利用可能であることが必要です。期限内（expired_time が -1 または未来）で、かつ無制限または remain_amount > 0 である必要があり、満たさない場合は 400 を返します。{"status": 1, "expired_time": 1767225600} のように同じリクエストでまとめて指定できます。停止は現在の状態を問わず可能で、明示した status は自動復帰より優先されます。

リクエスト例

利用可能額を使い切った Key に金額を追加する（Key は自動的に有効状態に戻ります）:

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"remain_amount": 20.00}'

有効期限を延長する:

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expired_time": 1767225600}'

Key を停止する（再度有効化するまで、この Key でのリクエストは拒否されます）:

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": 2}'

再度有効化する。有効化後に利用可能であることを保証するため、同じリクエストで有効期限も延長します:

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": 1, "expired_time": 1767225600}'

レスポンス例

更新後の Key オブジェクトを返します。key はマスクされた値です。

{
  "success": true,
  "message": "",
  "data": {
    "id": 12,
    "name": "bot",
    "key": "sk-abcd**********wxyz",
    "status": 1,
    "created_time": 1729000000,
    "accessed_time": 1729000000,
    "expired_time": -1,
    "remain_amount": 20.00,
    "unlimited": false,
    "used_amount": 10.00,
    "model_limits_enabled": false,
    "model_limits": "",
    "allow_ips": ""
  }
}

フィールドの説明は Key オブジェクト を参照してください。

エラー

HTTP	code	シナリオ
400	invalid_request	id が正の整数ではない、またはリクエストボディが有効な JSON ではない
400	invalid_request	ボディが空、null、または更新可能なフィールドがない
400	invalid_request	status が 1 または 2 ではない（3 / 4 は自動設定）
400	invalid_request	Key が期限切れまたは利用可能額を使い切ったまま status: 1 を指定した。expired_time の延長、remain_amount の補充、無制限化が必要（同じリクエストでまとめて指定可能）
400	invalid_request	名前が 50 文字を超える。もしくは remain_amount が負の値か上限を超える
400	invalid_request	expired_time が未来ではない（かつ 0 / -1 でもない）、または 9999-12-31 より後
400	invalid_request	無制限の Key に remain_amount のみを指定した、または無制限の Key を上限ありに変更する際に remain_amount を指定しなかった
404	not_found	Key が存在しないか、あなたのものではない

その他の共通エラーコードは プラットフォーム API のエラー を参照してください。

補足

• remain_amount のみを指定した場合: 上限ありの Key には直接反映されます。無制限の Key では 400 を返すため、"unlimited": false も同時に指定する必要があります。
• "unlimited": false のみで remain_amount を指定しない場合: 無制限の Key では 400 を返します（残高が 0 になるのを防ぐため）。もともと上限ありの Key は現在の残高を維持します。
• 期限切れ（3）または利用可能額を使い切った（4）Key は、今回の更新で利用可能になると（expired_time の延長、remain_amount の補充、無制限化）、自動的に有効（1）に戻ります。この自動復帰は status を指定しない場合にのみ適用されます。
• 2 は手動で停止した状態です。自動的に復帰することはなく、再度有効化するには status: 1 を送信します。Key が 1 以外の状態のとき、その Key でのモデル呼び出しは拒否されます。
• すべての検証が完了してから一括で書き込まれます。いずれかのフィールドの検証に失敗すると 400 を返し、どのフィールドも変更されません。
• プラットフォーム API による Key の更新は監査ログに記録されます。