Generating an API Key

Create a Venice API key, store it securely, verify it, and troubleshoot 402 spend limit errors when an account balance is available but the key is capped.

Venice API requests are authenticated with Bearer API keys. This guide shows how to create a key from the Venice dashboard, store it safely, and verify that it works.

If you are building an autonomous agent that needs to mint its own key with a wallet, use the Autonomous Agent API Key Creation guide instead.

Before you start

• Sign in to your Venice account.
• Make sure the account has a spendable balance before calling paid endpoints. You can create a key before funding the account, but model requests will not succeed until the account can consume DIEM, bundled credits, or USD.

1. Open API settings

   Visit https://venice.ai/settings/api. You can also open this page from the Venice app by selecting API in your settings.

   The API settings dashboard shows your balances, API tier, usage, and existing API keys.

2. Start a new key

   Select Generate New API Key, then configure the key:

   • Description: Use a short name that identifies the app, environment, or integration that will use this key.
   • API Key Type: Use Inference Only for normal model requests. Use Admin only when the key must manage API keys programmatically.
   • Expires at: Optionally set an expiration date. If you leave this blank, the key does not expire automatically.
   • Epoch Consumption Limits: Optionally cap how much DIEM or USD this key can spend during a 24-hour epoch. If you leave this blank, the key can use the account’s available balance subject to your account limits.
3. Generate and copy the key

   Click Generate. Venice will show the full API key one time.

   Copy the key immediately and store it in a secure location. After you close the dialog, Venice only shows identifying metadata such as the key description and last characters. If you lose the secret value, delete the key and create a new one.

   Paste the key exactly as it was issued. Use the dialog’s copy button rather than selecting the text by hand, so you do not clip the first or last character or pick up a trailing newline. When a tool asks for the key in a form field, enter the key on its own: no Bearer prefix, no surrounding quotes, and no leading or trailing spaces. Because the dashboard shows only the last few characters once the dialog closes, never try to rebuild a lost key by retyping that masked value.

   Add the key to your local environment or secret manager:

   export VENICE_API_KEY="your-api-key-here"
   
4. Verify the key

   Make a low-risk request to confirm that authentication is working. Get API Key Rate Limits and Balances costs nothing and accepts either key type. Use it rather than GET /models, which returns the model catalog with or without a key and therefore succeeds even when your key is wrong:

   curl --request GET \
     --url https://api.venice.ai/api/v1/api_keys/rate_limits \
     --header "Authorization: Bearer $VENICE_API_KEY"
   

   A successful response returns your API tier, balances, and rate limits, and data.accessPermitted reports whether the key may consume the inference endpoints.

   A 401 with AUTHENTICATION_FAILED means the key itself was rejected. Print the stored value and compare it against the last characters shown in the dashboard: the usual causes are a partial copy, a Bearer prefix or quotes captured into the value itself, or a stray space or newline on either end. Also confirm the header reads Bearer <api-key> with exactly one space between the two.

Disabling USD spending during API key creation in the Venice app sets your USD spend limit to zero for the given API key. API calls may fail with an insufficient balance error when your available DIEM or bundled credits cannot cover the request, even if your account has a USD balance.

Troubleshooting spend limit errors

Per-key spend limits are separate from your account balance. A key can be blocked from spending even when your account still has funded USD credits, DIEM, or bundled credits. If a request returns a 402 with one of these codes, the cause is the key’s own limit rather than your account balance:

• API_KEY_USD_SPEND_LIMIT_EXCEEDED — the key’s USD spend limit is set to zero (USD spending was disabled at creation) or the current epoch has reached its USD cap.
• API_KEY_DIEM_SPEND_LIMIT_EXCEEDED — the key has reached its DIEM cap for the current 24-hour epoch.

To confirm the current state of a key, call Get API Key Rate Limits and Balances and inspect data.accessPermitted, data.balances, and the per-key consumption limits.

To resolve the error, either raise or remove the key’s Epoch Consumption Limits at venice.ai/settings/api, or call Update API Key with new consumptionLimits. Account-wide balances (USD, DIEM, and bundled credits) are independent payment sources and are consumed automatically as available; you do not need to choose one at request time.

See Error Codes for the full list of billing-related responses.

Best practices

• Create separate keys for development, staging, and production.
• Prefer Inference Only keys for applications that only call model endpoints.
• Keep Admin keys rare, tightly scoped, and stored only in trusted server-side environments.
• Never commit API keys to source control or expose them in client-side code.
• Set expiration dates and consumption limits for keys used in temporary, shared, or higher-risk environments.
• Delete unused keys and rotate any key that may have been exposed.

Programmatic key management

Admin keys can manage API keys through the API reference endpoints:

Create API Key

Create a new dashboard-style API key from an existing admin key.

List API Keys

View active keys and their metadata.

Update API Key

Update a key description, expiration date, or consumption limits.

Delete API Key

Revoke a key that is no longer needed.