venice-api-keys

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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`

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

```json
{
  "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

```bash
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"
  }'
```

```json
{
  "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` field.

From veniceai/skills, MIT.

More from veniceai/skills