/venice-api-keys

name: venice-api-keys
description: Manage Venice API keys. Covers GET/POST/PATCH/DELETE /api_keys, GET /api_keys/{id}, GET /api_keys/rate_limits, GET /api_keys/rate_limits/log, the two-step /api_keys/generate_web3_key wallet flow, INFERENCE vs ADMIN key types, per-key consumption limits (USD / DIEM) with EPOCH / MONTH / LIFETIME reset windows, and per-key modelPrivacy (ALL / PRIVATE_TEXT / PRIVATE_ONLY).

Venice API Keys

Admin endpoints for managing Bearer API keys. Management routes need an **ADMIN** key. For wallet-only auth, use [`venice-auth`](../venice-auth/SKILL.md) / [`venice-x402`](../venice-x402/SKILL.md) instead.

| Endpoint | Key type | Purpose | |---|---|---| | `GET /api_keys` | ADMIN | List your active keys (masked). | | `POST /api_keys` | ADMIN | Create a key. Response contains the **only copy of the secret**. | | `PATCH /api_keys` | ADMIN | Update `description`, `expiresAt`, `consumptionLimit`, `limitPeriod`, `modelPrivacy`. | | `DELETE /api_keys?id=...` | ADMIN | Revoke a key. | | `GET /api_keys/{id}` | ADMIN | Full details for one key (usage, limits, expiration). | | `GET /api_keys/rate_limits` | any | Balances + per-model rate limits for the calling key. | | `GET /api_keys/rate_limits/log` | ADMIN | Last 50 rate-limit breaches on the account. | | `GET /api_keys/generate_web3_key` | none | Get a short-lived token to sign with a wallet. | | `POST /api_keys/generate_web3_key` | none | Prove a wallet holds staked VVV and mint an API key. |

Limits: key creation (`POST /api_keys`) is capped at **20 requests/minute per user** and **500 active keys per user** (expired keys don't count).

A request with no `Authorization` header gets a `402` x402 auth challenge rather than `401`; a bad key gets `401`.

Key types

| Type | Can call | |---|---| | `INFERENCE` | Inference and utility routes — `/chat/completions`, `/responses`, `/decisions`, `/systemone`, `/image/*`, `/images/generations`, `/audio/*`, `/video/*`, `/embeddings`, `/augment/*`, `/crypto/rpc/*`, `/characters*`, `/models*` — plus `GET /api_keys/rate_limits`. Admin-only routes return `401` `"Admin API key required"`. | | `ADMIN` | Everything above, plus `GET/POST/PATCH/DELETE /api_keys`, `GET /api_keys/{id}`, `GET /api_keys/rate_limits/log`, and all billing routes (`/billing/balance`, `/billing/usage-history`, `/billing/usage-analytics`). |

Secrets are prefixed `VENICE_INFERENCE_KEY_` or `VENICE_ADMIN_KEY_`. A leaf app should almost always use **`INFERENCE`** keys — per-app, per-user, with consumption caps.

`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" }
    }
  ]
}

• Only non-expired keys are listed, newest first. The full secret is **never** returned — only `last6Chars`.
• `usage.trailingSevenDays` and `currentPeriodUsage` values are **strings** with 4 decimals. The `usd` figures include bundled-credit spend but not earned-credit spend, even though the USD limit counts both.
• `currentPeriodUsage` is spend inside the current `limitPeriod` window and is present **only** when the key has a USD or DIEM limit set.
• `consumptionLimits.vcu` is deprecated and always shown; ignore it.

`POST /api_keys` — create

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"
  }
}

**Save `apiKey` immediately** — Venice won't show the secret again. If you lose it, delete and re-create. The body is strict: unknown fields are a `400`.

Required

• `apiKeyType` — `INFERENCE` or `ADMIN`.
• `description` — string, max **64** characters.

Optional

• `expiresAt` — `""`, a date `YYYY-MM-DD`, or a UTC datetime `YYYY-MM-DDTHH:mm:ss[.sss]Z`. Omit (or `""`) for non-expiring.
• `consumptionLimit.usd` / `.diem` — number `0`–`9999999999`, or `null` for no cap. The **USD** limit caps `USD`, `BUNDLED_CREDITS` and `EARNED_CREDITS` spend combined; the **DIEM** limit caps DIEM spend.
• `consumptionLimit.vcu` — **deprecated** (legacy DIEM). Use `diem`.
• `limitPeriod` — window the limits are measured over. Default `EPOCH`.
• `modelPrivacy` — which models the key may call. Default `ALL`.

`limitPeriod`

| Value | Window | |---|---| | `EPOCH` | Resets every UTC day (default, legacy behaviour). | | `MONTH` | Resets at 00:00 UTC on the 1st of each calendar month. | | `LIFETIME` | Never resets — a permanent cap on the key. |

When a key hits its limit while the account still has funds, inference returns `402` with only an `error` string: `"API key USD spend limit exceeded. Your account may still have USD balance, but this API key has reached its configured USD spending limit."` (or the same with DIEM). There is no `code` fie