変更履歴
公共 API の互換性維持のための旧パス, 旧エンドポイントの代替関係と移行差異
2026-11-12
今回の更新で公開 API ドキュメントを再編成しました: ページはアカウント, API キー, 使用量, タスク, 請求, 料金のグループに分かれ, キーのライフサイクル (作成, 更新, 失効, ローテーション), キー残高, モデル料金のドキュメントを追加しました.
旧「アカウント」グループの 5 ページは削除し, 旧ドキュメント URL は対応する新ページへリダイレクトされます. 変更はドキュメント構成のみで, 稼働中の API 動作は変わりません.
互換性のため残された旧パス
次の 10 個の旧 GET パスは現在も利用でき, 動作は右側の新パスと同一です. 互換性維持のために残しているもので, 今後のリリースで削除されるため早めに移行してください. 新規連携は新パスを直接使用してください. なお /api/v1/account と /api/v1/account/balance はそれ自体が新パスなので対象外です.
| 旧パス | 新パス |
|---|---|
/api/v1/account/api-keys | /api/v1/api-keys |
/api/v1/account/api-keys/{api_key_id} | /api/v1/api-keys/{api_key_id} |
/api/v1/account/usage/records | /api/v1/usage/records |
/api/v1/account/usage/summary | /api/v1/usage/summary |
/api/v1/account/tasks | /api/v1/tasks |
/api/v1/account/tasks/{task_id} | /api/v1/tasks/{task_id} |
/api/v1/account/billing/topups | /api/v1/billing/topups |
/api/v1/account/billing/topups/{trade_no} | /api/v1/billing/topups/{trade_no} |
/api/v1/account/billing/payment-method | /api/v1/billing/payment-method |
/api/v1/account/billing/auto-topup | /api/v1/billing/auto-topup |
キーの作成, 更新, 失効, ローテーション, キー残高, Webhook, 料金, Stripe 請求書には, /account プレフィックス付きの旧パスは存在せず, 平坦な新パスのみです.
旧アカウント API からの移行
下表は新旧エンドポイントの機能対応表であり, そのまま置き換えられる互換パスではありません. 認証情報, パラメータ, レスポンス形式が異なるため, 呼び出しコードの修正が必要です. 旧残高・作成 API はモデルキーで認証していましたが, 新 API はシステムアクセストークンを使用します.
旧使用量 API で必須だった X-User-Id ヘッダーは新 API では不要です.
| 旧 API | 新 API | 移行条件 |
|---|---|---|
GET /v1/balance, /balance | GET /api/v1/api-keys/{api_key_id}/balance | 対象キー自身で認証せず, システムアクセストークンとキー ID で取得します. 無制限の残額は -1 ではなく null です. |
GET /api/usage/tokens/requests | GET /api/v1/usage/records | 下表に従ってパラメータとフィールドを変更します. キャッシュ読み書きの token 数は usage 内で返されます. |
GET /api/usage/tokens/summary | GET /api/v1/usage/summary?group_by=api_key | group_by=api_key を明示します. record_count はログ行数で, 完全な呼び出し数や純支出ではありません. |
GET /v1/user/balance, /user/balance | GET /api/v1/account/balance | 自分の残高または子アカウント予算を取得します. 十進文字列で USD と credits を分けます. |
GET /v1/pricing | GET /api/v1/pricing?api_key_id={api_key_id} | api_key_id でキー視点を指定できます. after/next_after は cursor/next_cursor に変更され, code/message/data 形式を使います. 同一プロトコルではありません. |
POST /v1/tokens | POST /api/v1/api-keys | 新しいフィールドと型に従ってください. group, cross_group_retry, Webhook 設定に対応せず, 旧機能の完全な代替ではありません. |
旧 allow_ips の改行区切り文字列は ["192.0.2.10","2001:db8::1"] のような文字列配列に変わります. 作成と更新の両方で利用でき, [] で制限を解除し, null や無効なアドレスは 400 になります. 単一の IP アドレスのみ対応し, CIDR レンジは利用できません.
使用量フィールドとページ分割の移行
時刻パラメータは Unix 秒の start_timestamp/end_timestamp からタイムゾーン付き from/to に変わり, ページング中も同じ範囲を保持します. token_id は api_key_id 文字列, page_size は limit に変わり, 旧カーソルは使えません.
キャッシュ項目では, 旧 cache_tokens は usage.cache_read_tokens, cache_creation_tokens は usage.cache_write_tokens に対応します.
新 API では 5 分と 1 時間の書き込み内訳も返しますが, これらは cache_write_tokens に含まれるため二重に加算しないでください. 欠損または無効な値は null, 明示的に記録されたゼロは 0 を返します.
パラメータエラーの HTTP ステータスは 422 から 400 に変わり, エラーレスポンスは数値 code を使います. 旧 quota は内部単位でしたが, 新 recorded_credits は credits 換算済みのため, フィールド名の変更だけでなく金額の意味も調整してください.
| 旧フィールド | 新フィールド | 説明 |
|---|---|---|
log_id | id | 名称変更のみ. |
token_id | api_key_id | 数値 ID を文字列で渡す. |
token_name | key_name | 名称変更のみ. |
model_name | model | 名称変更のみ. |
start_timestamp/end_timestamp | from/to | Unix 秒 → タイムゾーン付き RFC 3339; ページ間で同じ範囲を維持する. |
page_size | limit | 1 ページの件数. |
cost_usd | recorded_cost_usd | ログ行の計上コスト USD, 十進文字列. |
quota | recorded_credits | 内部クォータ単位 → 換算済み credits. 旧値はそのまま使えない. |
prompt_tokens | usage.input_tokens | usage オブジェクト内に移動. |
completion_tokens | usage.output_tokens | usage オブジェクト内に移動. |
reported_total_tokens | usage.reported_total_tokens | 上流が報告した合計トークン; usage 内に移動. |
cache_tokens | usage.cache_read_tokens | キャッシュ読み取り量; usage 内に移動. |
cache_creation_tokens | usage.cache_write_tokens | キャッシュ書き込み合計. 5 分・1 時間の内訳を含むため二重加算しないこと. |
request_count | record_count | ログ件数. 完全なリクエスト数ではない. |
data[] | data.items[] | レコード配列は data.items へ. |
meta.has_more | data.has_more | ページ情報は data 内に移動. |
meta.next_cursor | data.next_cursor | ページカーソル. 旧カーソルは新 API では無効. |
キー作成フィールドの変更
| 旧フィールド | 新フィールド | 説明 |
|---|---|---|
expired_time | expires_at | Unix 秒 (-1 は無期限) からタイムゾーン付き RFC 3339 へ; null または省略で無期限. |
remain_quota/remain_credits | remaining_credits | 十進文字列 (精度保持). |
daily_credits/monthly_credits | daily_limit_credits/monthly_limit_credits | null または "0" で無制限. |
unlimited_quota | unlimited | 真偽値, null 不可; true のとき remaining_credits は省略または null のみ. |
model_limits_enabled | — | 廃止; model_limits 配列が空でなければ制限が有効. |
model_limits | model_limits | カンマ区切り文字列 → 文字列配列; 連結後最大 1024 UTF-8 バイト. |
allow_ips | allow_ips | 改行区切り文字列 → 文字列配列; 単一 IP のみ, CIDR 不可; [] で解除, null/無効は 400. |
動作の変更: 作成成功の HTTP ステータスは 200 から 201 に変わり, 完全なシークレットは sk- プレフィックス付きで data.key に返されます.
引き続き区別する機能
アカウントのタスク API が返すのはタスクの状態と課金メタデータのみで, 生成結果は従来どおり結果取得 API を使います. billing と usage の意味は実際の費用とタスク使用量を参照してください.
料金カタログは現在の料率を示すもので, 過去の請求の再計算には使えません. 公開 API のキー管理でもクォータ変更や失効キーの復元はできません.
Webhook は専用の設定エンドポイントで管理します. 通常モデルキーごとに 1 件の設定を持ち, キーの作成・更新とは別の操作です. 詳しくはWebhook 設定の取得を参照してください.