venice-api-keys

Venice API Keys

Bearer API キーを管理するための管理エンドポイントです。管理ルートには ADMIN キーが必要です。ウォレットのみで認証する場合は、代わりに venice-auth／venice-x402 を使用してください。

エンドポイント	キーの種類	目的
GET /api_keys	ADMIN	有効なキーの一覧を取得します（マスク済み）。
POST /api_keys	ADMIN	キーを作成します。レスポンスにはシークレットの唯一のコピーが含まれます。
PATCH /api_keys	ADMIN	description、expiresAt、consumptionLimit、limitPeriod、modelPrivacy を更新します。
DELETE /api_keys?id=...	ADMIN	キーを失効させます。
GET /api_keys/{id}	ADMIN	1 つのキーの詳細（使用状況、制限、有効期限）を取得します。
GET /api_keys/rate_limits	すべて	呼び出し元のキーの残高とモデルごとのレート制限を取得します。
GET /api_keys/rate_limits/log	ADMIN	アカウントで発生した直近 50 件のレート制限超過を取得します。
GET /api_keys/generate_web3_key	なし	ウォレットで署名するための短期間有効なトークンを取得します。
POST /api_keys/generate_web3_key	なし	ウォレットがステーク済み VVV を保有していることを証明し、API キーを発行します。

制限：キーの作成（POST /api_keys）は、ユーザーあたり1 分間に 20 リクエスト、有効なキー 500 個までです（期限切れのキーは数えません）。

Authorization ヘッダーなしのリクエストには 401 ではなく 402 x402 認証チャレンジが返されます。不正なキーには 401 が返されます。

キーの種類

種類	呼び出し可能なもの
INFERENCE	推論およびユーティリティルート — /chat/completions、/responses、/decisions、/systemone、/image/*、/images/generations、/audio/*、/video/*、/embeddings、/augment/*、/crypto/rpc/*、/characters*、/models* — と GET /api_keys/rate_limits。管理者専用ルートは 401 "Admin API key required" を返します。
ADMIN	上記すべてに加え、GET/POST/PATCH/DELETE /api_keys、GET /api_keys/{id}、GET /api_keys/rate_limits/log、すべての課金ルート（/billing/balance、/billing/usage-history、/billing/usage-analytics）を呼び出せます。

シークレットのプレフィックスは VENICE_INFERENCE_KEY_ または VENICE_ADMIN_KEY_ です。通常、個別のアプリでは**INFERENCE** キーを使用してください。アプリごと、ユーザーごとにキーを作成し、消費上限を設定できます。

GET /api_keys

curl https://api.venice.ai/api/v1/api_keys \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
      "apiKeyType": "INFERENCE",
      "description": "backend prod",
      "createdAt": "2025-10-01T12:00:00.000Z",
      "expiresAt": null,
      "lastUsedAt": "2026-04-20T10:05:00.000Z",
      "last6Chars": "2V2jNW",
      "consumptionLimits": { "usd": 50, "diem": 10, "vcu": null },
      "limitPeriod": "MONTH",
      "modelPrivacy": "ALL",
      "usage": { "trailingSevenDays": { "usd": "4.2000", "vcu": "0.0000", "diem": "0.0000" } },
      "currentPeriodUsage": { "usd": "12.5000", "diem": "0.0000" }
    }
  ]
}

• 期限切れでないキーのみが新しい順に一覧表示されます。シークレット全体が返されることはありません。返されるのは last6Chars のみです。
• usage.trailingSevenDays と currentPeriodUsage の値は、小数点以下 4 桁の文字列です。usd の数値にはバンドルクレジットの支出が含まれますが、獲得クレジットの支出は含まれません。ただし、USD 上限には両方が含まれます。
• currentPeriodUsage は現在の limitPeriod の期間内の支出で、キーに USD または DIEM の上限が設定されている場合のみ含まれます。
• consumptionLimits.vcu は非推奨ですが、常に表示されます。無視してください。

POST /api_keys — 作成

curl https://api.venice.ai/api/v1/api_keys \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKeyType": "INFERENCE",
    "description": "backend prod",
    "expiresAt": "2026-12-31T23:59:59Z",
    "consumptionLimit": { "usd": 50, "diem": 10 },
    "limitPeriod": "MONTH",
    "modelPrivacy": "PRIVATE_ONLY"
  }'

{
  "success": true,
  "data": {
    "id": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
    "apiKey": "VENICE_INFERENCE_KEY_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "apiKeyType": "INFERENCE",
    "description": "backend prod",
    "expiresAt": "2026-12-31T23:59:59.000Z",
    "consumptionLimit": { "usd": 50, "diem": 10, "vcu": null },
    "limitPeriod": "MONTH",
    "modelPrivacy": "PRIVATE_ONLY"
  }
}

apiKey はすぐに保存してください。Venice でシークレットが再表示されることはありません。紛失した場合は、削除して再作成してください。リクエスト本文は厳密に検証されます。不明なフィールドがあると 400 が返されます。

必須

• apiKeyType — INFERENCE または ADMIN。
• description — 文字列、最大 64 文字。

任意

• expiresAt — ""、日付 YYYY-MM-DD、または UTC 日時 YYYY-MM-DDTHH:mm:ss[.sss]Z。有効期限なしにする場合は省略するか、"" を指定します。
• consumptionLimit.usd／.diem — 0～9999999999 の数値、または上限なしを示す null。USD 上限は USD、BUNDLED_CREDITS、EARNED_CREDITS の支出合計に適用され、DIEM 上限は DIEM の支出に適用されます。
• consumptionLimit.vcu — 非推奨（従来の DIEM）。diem を使用してください。
• limitPeriod — 上限を計測する期間。デフォルトは EPOCH です。
• modelPrivacy — キーで呼び出せるモデル。デフォルトは ALL です。

limitPeriod

Value	Window
EPOCH	UTC の毎日リセットされます（デフォルト、従来の動作）。
MONTH	各月の 1 日の 00:00 UTC にリセットされます。
LIFETIME	リセットされません — キーに対する恒久的な上限です。

アカウントに残高がある状態でキーが上限に達すると、推論は 402 を返し、error 文字列のみが含まれます："API key USD spend limit exceeded. Your account may still have USD balance, but this API key has reached its configured USD spending limit."（または DIEM の場合は同じ文言）。code フィールドはありません。

modelPrivacy

すべての推論ルートで適用されます。許可されていないモデルの場合、403 が返されます（"This API key is set to '…', but is an Anonymous model. Choose a Private, TEE, or E2EE model, or change the model privacy setting of this API key."）。このキーで GET /models、/models/traits、/models/compatibility_mapping を呼び出すと、使用可能なモデルのみが表示されます。

Value	Effect
ALL	すべてのモデルを使用できます（デフォルト）。
PRIVATE_TEXT	テキスト、埋め込み、判定モデルは Private、TEE、または E2EE である必要があります。画像／音声／動画モデルは Anonymous でもかまいません。
PRIVATE_ONLY	すべてのモデルが Private、TEE、または E2EE である必要があります。Anonymous モデルは拒否されます。

制限付きのキーで GET /models を呼び出すと、そのキーで呼び出し可能なモデルのみが返されます — 許可されたモデルを選ぶ最も簡単な方法です（venice-models を参照）。

PATCH /api_keys — 更新

curl -X PATCH https://api.venice.ai/api/v1/api_keys \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5", "description": "renamed", "consumptionLimit": { "usd": 100 }, "limitPeriod": "LIFETIME" }'

• id は必須です。それ以外はすべて省略可能で、送信したフィールドのみが変更されます。apiKeyType は変更できません。
• 変更可能な項目：description（64 文字以下）、expiresAt、consumptionLimit（usd／diem／vcu。それぞれ null を指定すると上限を解除できます）、limitPeriod、modelPrivacy。
• 有効期限を解除するには、"expiresAt": "" または null を指定します。
• { success: true, data: { id, apiKeyType, description, createdAt, expiresAt, lastUsedAt, last6Chars, consumptionLimits, limitPeriod, modelPrivacy } } を返します。
• 不明または期限切れの id → 400 "API key not found or expired"。

DELETE /api_keys?id=<uuid> — 失効

curl -X DELETE "https://api.venice.ai/api/v1/api_keys?id=e28e82dc-9df2-4b47-b726-d0a222ef2ab5" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"

ID は JSON ボディ { "id": "..." } として送信することもできます。{"success": true} を返します。不明なキー → 400 "API key could not be found"。失効は即時に反映されます。

GET /api_keys/{id} — 詳細

リスト項目と同じフィールド（上限設定時の usage.trailingSevenDays、currentPeriodUsage、limitPeriod、modelPrivacy など）を含む { data: <key> } を返します。不明または期限切れの ID → 400 "API key not found"。

GET /api_keys/rate_limits

任意のキー種別で呼び出せます。呼び出し元のキーについて報告します。

curl https://api.venice.ai/api/v1/api_keys/rate_limits \
  -H "Authorization: Bearer $VENICE_API_KEY"

{
  "data": {
    "accessPermitted": true,
    "apiTier": { "id": "paid", "isCharged": true },
    "balances": { "USD": 50.23, "DIEM": 100.023, "BUNDLED_CREDITS": 25 },
    "keyExpiration": null,
    "nextEpochBegins": "2026-04-21T00:00:00.000Z",
    "rateLimits": [
      {
        "apiModelId": "zai-org-glm-5-1",
        "rateLimits": [
          { "type": "RPM", "amount": 100 },
          { "type": "TPM", "amount": 2000000 }
        ]
      }
    ]
  }
}

• accessPermitted は実際の利用可否チェックです（残高、キーごとの上限、アカウントの状態）。/billing/balance の canConsume よりこちらを優先してください。
• balances はこのキーが現在使用できる金額です。各アカウント残高は、キーに残っている上限額を超えないよう調整されます。BUNDLED_CREDITS は USD 建てで、プランに含まれない場合は 0 です。獲得クレジットは一覧に含まれません。不明な場合は、3 項目のいずれかが省略されることがあります。
• apiTier.id はアカウントの API ティア（例：paid）です。isCharged は常に true です。
• rateLimits[].rateLimits[].type は RPM（分あたりのリクエスト数）、RPD（日あたりのリクエスト数）、または TPM（分あたりのトークン数）です。上記の数値は例示です — 実際の値はレスポンスから読み取ってください。動画および音楽モデルは空の配列を返します（スループット制限の対象外です）。
• nextEpochBegins は、DIEM の割り当てと EPOCH 期間のキー上限がリセットされる時刻です。

GET /api_keys/rate_limits/log

ADMIN キーが必要です。アカウントで直近に発生したレート制限超過を、新しい順に最大 50 件返します。

{
  "object": "list",
  "data": [
    { "apiKeyId": "e28e82dc-...", "modelId": "zai-org-glm-5-1", "rateLimitType": "RPM",
      "rateLimitTier": "paid", "timestamp": "2026-04-20T12:34:56.000Z" }
  ]
}

rateLimitType は次のいずれかです。

値	意味
RPM / TPM / RPD	モデルごとのスループット上限です。
FAILED_REQUESTS	一般的なエラーバジェットです。30 秒以内に 429 以外のクライアントエラー応答（4xx）が 50 件を超えると適用されます。
UNSUPPORTED_FEATURE_REQUESTS	/chat/completions または /responses で、30 秒以内に「モデルがこの機能をサポートしていない」という拒否が 200 件を超えると適用されます。

modelId は通常モデル ID ですが、エンドポイントレベルの制限は endpoint:api/v1/...（例：endpoint:api/v1/crypto/rpc）として記録され、解決できないモデル名は model:unknown として記録されます。

Web3 API キー — 2 段階のウォレットフロー

Base 上で VVV をステーキング済みのウォレットが、Bearer API キーを発行できるようにします。Venice アカウントは不要です。初回使用時に作成され、ウォレットに紐付けられます。

1. GET /api_keys/generate_web3_key

curl https://api.venice.ai/api/v1/api_keys/generate_web3_key

{ "success": true, "data": { "token": "<JWT>" } } を返します。トークンの有効期間は 15 分です。

2. トークンに署名し、POST /api_keys/generate_web3_key を呼び出す

import { Wallet } from 'ethers'

const { data: { token } } = await fetch(`${base}/api_keys/generate_web3_key`).then(r => r.json())
const wallet = new Wallet(process.env.WALLET_KEY!)
const signature = await wallet.signMessage(token) // EIP-191 personal_sign of the exact JWT string

const res = await fetch(`${base}/api_keys/generate_web3_key`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    apiKeyType: 'INFERENCE',
    description: 'Web3 API Key',
    address: wallet.address,
    signature,
    token,
    consumptionLimit: { usd: 50 },
  }),
})

const { data } = await res.json()
console.log(data.apiKey) // save this once

• 本文：address、signature、token、apiKeyType は必須です。description のデフォルト値は "Web3 API Key" です。expiresAt、consumptionLimit、limitPeriod、modelPrivacy は POST /api_keys と同様に機能します。
• 署名は Base（チェーン 8453）で検証されます。検証に失敗すると、アドレス不正、トークンの期限切れまたは改変、署名の不一致、"Wallet … has no staked VVV on Base" のいずれかを示す具体的なメッセージとともに 400 が返されます。
• レスポンスの形式は POST /api_keys と同じです。返された apiKey は通常の Bearer キーとまったく同じように機能します。ステーキング済み VVV が必要なのはキーの発行時のみです。キーの使用時には、紐付けられたアカウントの DIEM、獲得クレジット、バンドルクレジット、または USD が消費されます。

レシピ

顧客ごとに、月額 USD 上限 $5 のプライベートモデル専用キーを発行する

await fetch(`${base}/api_keys`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${ADMIN_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    apiKeyType: 'INFERENCE',
    description: `cust:${customerId}`,
    consumptionLimit: { usd: 5 },
    limitPeriod: 'MONTH',
    modelPrivacy: 'PRIVATE_ONLY',
  }),
})

顧客の利用終了時に取り消します。

キーのヘルスチェック

const { data } = await fetch(`${base}/api_keys/rate_limits`, {
  headers: { Authorization: `Bearer ${key}` },
}).then(r => r.json())

if (!data.accessPermitted) alert('Key blocked — top up or raise its limit')

エラー

コード	意味
400	不正な本文（apiKeyType の欠落、description が 64 文字超、不正な形式の expiresAt、不明なフィールド）、有効なキー数が 500 に到達、不明または期限切れのキー ID、または Web3 検証の失敗です。
401	無効なキー、または管理者専用ルートで ADMIN 以外のキーを使用した場合（"Admin API key required"）です。
402	Authorization ヘッダーがありません（x402 認証チャレンジ）。推論時に、キーの上限に達すると "API key USD spend limit exceeded…" / "API key DIEM spend limit exceeded…" が返されます。
403	推論時に、キーの modelPrivacy でモデルが許可されていません。
429	1 分あたりのキー作成数が 20 件を超えた、または一般的な API エラーバジェットに達しました。
500	一時的なエラーです。再試行してください。

注意事項

• シークレットが返されるのは、作成レスポンスの一度だけです。紛失した場合は、削除して再作成してください。
• consumptionLimit は limitPeriod（デフォルトは UTC 日単位の EPOCH。MONTH または LIFETIME も選択できます）の期間内で適用されます。呼び出しごとの上限ではありません。
• USD 上限は、USD、バンドルクレジット、獲得クレジットの合計に適用されます。
• GET /api_keys/rate_limits は INFERENCE キーで使用できますが、GET /api_keys/rate_limits/log は使用できません（ADMIN 専用）。
• modelPrivacy は強制されます。PRIVATE_ONLY キーで Anonymous モデルにアクセスすると 403 が返され、そのキーからは /models にも表示されません。
• vcu はレガシーです。diem を使用してください。
• 作成時の expiresAt: "" は「有効期限なし」を意味します。更新時の "" または null は、既存の有効期限を削除します。
• レート制限ログは最大 50 件です。急増のデバッグ時は、頻繁に取得してください。
• Web3 フローのトークンは 15 分で期限切れになり、ウォレットには Base 上でステーキング済みの VVV が必要です。このフローでは、作成レスポンスの consumptionLimit の値を信用せず、GET /api_keys/{id} で制限を取得してください。diem は vcu から算出されるため、diem だけを送信した場合は null として返されます。また、usd が 0 の場合も null として返されます。保存された制限値は正しい値です。