Gestionar claves de API

Una clave Admin puede gestionar todas tus demás claves de API mediante la API. Da a cada aplicación, entorno o cliente su propia clave Inference, limita cuánto puede gastar cada una, supervisa el uso por clave y cambia o revoca claves sin abrir el panel.

Crear

Emite una clave con un tope de gasto

Supervisar

Consulta cuánto gasta cada clave

Cambiar

Aumenta un tope o amplía una expiración

Revocar

Desactiva una clave de inmediato

Cómo funciona

Clave AdminTu clave de controlCrea, cambia y revoca clavesLee el uso y la facturaciónSe queda en tu servidor

Inferencecust:acme$50 / mesSolo modelos privados

Inferencecust:globex$5 / mesSolo desde 11.22.33.0/24

Inferencestaging$10 / díaExpira el 30 de jun

Las claves Admin pueden llamar a todos los endpoints, incluidos los que gestionan claves y leen la facturación. Las claves Inference pueden llamar a modelos, pero no pueden gestionar claves ni leer la facturación, así que son las claves que repartes.

	Admin	Inference
Llamar a modelos y otros endpoints de inferencia	✓	✓
Consultar su propio saldo y límites de tasa (`GET /api_keys/rate_limits`)	✓	✓
Crear, actualizar y revocar claves (`/api_keys`)	✓
Leer el uso y la facturación (`/billing/*`)	✓

Crea tu primera clave Admin en el panel: sigue Generar una clave de API y elige Admin como tipo de clave. Guárdala en un almacén de secretos del lado del servidor, nunca en código del cliente.

Los ejemplos de esta página leen la clave Admin de VENICE_ADMIN_KEY:

export VENICE_ADMIN_KEY="your-admin-key"

import os
import requests

BASE = "https://api.venice.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['VENICE_ADMIN_KEY']}"}

const BASE = "https://api.venice.ai/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.VENICE_ADMIN_KEY}`,
  "Content-Type": "application/json",
};

Crear una clave

Esto crea una clave Inference para un cliente, con un tope de $50 al mes y que expira el 30 de junio de 2027:

curl https://api.venice.ai/api/v1/api_keys \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKeyType": "INFERENCE",
    "description": "cust:acme",
    "consumptionLimit": { "usd": 50 },
    "limitPeriod": "MONTH",
    "expiresAt": "2027-06-30"
  }'

resp = requests.post(f"{BASE}/api_keys", headers=HEADERS, json={
    "apiKeyType": "INFERENCE",
    "description": "cust:acme",
    "consumptionLimit": {"usd": 50},
    "limitPeriod": "MONTH",
    "expiresAt": "2027-06-30",
})
resp.raise_for_status()
key = resp.json()["data"]
key_id, secret = key["id"], key["apiKey"]

const res = await fetch(`${BASE}/api_keys`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    apiKeyType: "INFERENCE",
    description: "cust:acme",
    consumptionLimit: { usd: 50 },
    limitPeriod: "MONTH",
    expiresAt: "2027-06-30",
  }),
});
const { data: key } = await res.json();
const { id: keyId, apiKey: secret } = key;

Response

{
  "success": true,
  "data": {
    "id": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
    "apiKey": "VENICE_INFERENCE_KEY_...",
    "apiKeyType": "INFERENCE",
    "description": "cust:acme",
    "consumptionLimit": { "usd": 50, "vcu": null, "diem": null },
    "limitPeriod": "MONTH",
    "modelPrivacy": "ALL",
    "expiresAt": "2027-06-30T00:00:00.000Z",
    "ipAllowlist": []
  }
}

data.apiKey es el secreto de la clave, y esta respuesta es la única vez que lo verás. Guárdalo de inmediato. Si lo pierdes, revoca la clave y crea una nueva. Conserva también data.id: todas las demás llamadas de esta página lo usan.

Configuración de la clave

Establece estos campos al crear una clave o cámbialos más tarde con PATCH /api_keys. El cuerpo de la solicitud es estricto, así que un campo desconocido devuelve 400.

Campo	Valores	Qué hace
`apiKeyType`	`INFERENCE` o `ADMIN`	Obligatorio al crear. No se puede cambiar después.
`description`	Hasta 64 caracteres	Obligatorio al crear. Las analíticas de uso etiquetan la clave con él, así que pon aquí tu propio identificador, como `cust:acme`.
`consumptionLimit`	`{ "usd": 50 }`	Tope de gasto para cada `limitPeriod`, en `usd`, `diem` o ambos. Omite una moneda, o establécela en `null`, para no tener tope. El tope en USD cuenta conjuntamente USD, créditos incluidos y créditos obtenidos.
`limitPeriod`	`EPOCH`, `MONTH`, `LIFETIME`	Cuándo se restablece el tope. `EPOCH`, el valor predeterminado, se restablece a diario a las 00:00 UTC; `MONTH`, el día 1 de cada mes (UTC); y `LIFETIME`, nunca.
`expiresAt`	`"2027-06-30"`	Una fecha, o una hora UTC como `"2027-06-30T23:59:59Z"`. Una fecha sola significa las 00:00 UTC de ese día. Omítelo para una clave que nunca expire.
`modelPrivacy`	`ALL`, `PRIVATE_TEXT`, `PRIVATE_ONLY`	`ALL`, el valor predeterminado, permite cualquier modelo. `PRIVATE_TEXT` exige modelos de texto y embeddings Private, TEE o E2EE. `PRIVATE_ONLY` lo exige para todos los modelos.
`ipAllowlist`	`["11.22.33.0/24"]`	Hasta 100 direcciones IPv4 o IPv6 públicas o rangos CIDR. Una lista vacía permite cualquier IP.

Puedes crear hasta 20 claves por minuto y mantener hasta 500 claves activas. Contacta con soporte si necesitas más.

¿Estás construyendo un agente? Una wallet con VVV en staking en Base puede generar su propia clave sin una cuenta de Venice. Consulta Creación de claves de API para agentes autónomos.

Supervisar el uso

Para saber	Llama a	Lee
Cuánto ha gastado una clave en este periodo	`GET /api_keys/{id}`	`currentPeriodUsage`
Cuánto gastó cada clave en los últimos 7 días	`GET /api_keys`	`usage.trailingSevenDays`
Gasto por clave, por día	`GET /billing/usage-analytics`	`byKey`, `byKeyDaily`
Cada cargo, con la clave a la que se facturó	`GET /billing/usage-history`	`apiKeyId`
Si una clave puede gastar ahora mismo	`GET /api_keys/rate_limits`, llamado con esa clave	`accessPermitted`, `balances`
Qué claves están alcanzando los límites de tasa	`GET /api_keys/rate_limits/log`	`apiKeyId`, `modelId`

Una clave

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

key = requests.get(f"{BASE}/api_keys/{key_id}", headers=HEADERS).json()["data"]

const res = await fetch(`${BASE}/api_keys/${keyId}`, { headers });
const { data: key } = await res.json();

Response (trimmed)

{
  "data": {
    "id": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
    "description": "cust:acme",
    "consumptionLimits": { "usd": 50, "diem": null, "vcu": null },
    "limitPeriod": "MONTH",
    "currentPeriodUsage": { "usd": "12.5000", "diem": "0.0000" },
    "usage": { "trailingSevenDays": { "usd": "4.2000", "diem": "0.0000", "vcu": "0.0000" } },
    "lastUsedAt": "2026-11-03T14:05:00.000Z"
  }
}

Esta clave ha usado $12.50 de sus $50 del mes. currentPeriodUsage solo aparece en claves con un tope en USD o DIEM, y los importes de uso son cadenas con cuatro decimales. Las respuestas devuelven consumptionLimits (plural), mientras que las solicitudes envían consumptionLimit (singular).

Gasto por clave a lo largo del tiempo

GET /billing/usage-analytics devuelve los totales por clave en byKey y una fila por día en byKeyDaily, listos para graficar. Pasa lookback (7d por defecto, hasta 90d) o un par startDate y endDate que abarque hasta 90 días. Los resultados se almacenan en caché durante 10 minutos.

cURL

curl "https://api.venice.ai/api/v1/billing/usage-analytics?lookback=30d" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"

Response (trimmed)

{
  "byKey": [
    {
      "apiKeyId": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
      "description": "cust:acme",
      "totalUsd": 12.5,
      "totalDiem": 0,
      "totalUnits": 1830000
    }
  ]
}

Cada cargo, por clave

GET /billing/usage-history enumera cada cargo, y cada entrada incluye el apiKeyId al que se facturó. Úsalo para conciliar el gasto o facturar a tus propios clientes. Las entradas se devuelven de la más antigua a la más reciente. Reenvía nextCursor como cursor, por sí solo, hasta que sea null. Envía Accept: text/csv para obtener CSV en su lugar.

curl -G https://api.venice.ai/api/v1/billing/usage-history \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  --data-urlencode "startTimestamp=2026-10-01T00:00:00Z" \
  --data-urlencode "endTimestamp=2026-11-01T00:00:00Z"

from collections import defaultdict

spend = defaultdict(float)
params = {"startTimestamp": "2026-10-01T00:00:00Z", "endTimestamp": "2026-11-01T00:00:00Z"}
while True:
    page = requests.get(f"{BASE}/billing/usage-history", headers=HEADERS, params=params).json()
    for entry in page["data"]:
        if entry["apiKeyId"]:
            spend[(entry["apiKeyId"], entry["currency"])] -= entry["amount"]
    if page["nextCursor"] is None:
        break
    params = {"cursor": page["nextCursor"]}

Los cargos tienen un amount negativo, así que el bucle lo resta para obtener un total positivo por clave y moneda. Las entradas sin apiKeyId proceden de la aplicación web de Venice o son entradas de la cuenta, como compras de créditos.

Si una clave puede gastar ahora mismo

GET /api_keys/rate_limits funciona con cualquier clave e informa sobre la clave que lo llama. accessPermitted indica si la clave puede gastar ahora mismo, y balances muestra lo que le queda por gastar.

cURL

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

GET /api_keys/rate_limits/log, con una clave Admin, devuelve tus últimas 50 veces que se alcanzó un límite de tasa, cada una con su apiKeyId y modelId.

Cambiar límites y configuración

Envía el id de la clave y solo los campos que quieras cambiar. Todo lo demás se mantiene igual. Esto aumenta el tope a $100 al mes:

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",
    "consumptionLimit": { "usd": 100 }
  }'

requests.patch(f"{BASE}/api_keys", headers=HEADERS, json={
    "id": key_id,
    "consumptionLimit": {"usd": 100},
}).raise_for_status()

await fetch(`${BASE}/api_keys`, {
  method: "PATCH",
  headers,
  body: JSON.stringify({ id: keyId, consumptionLimit: { usd: 100 } }),
});

Envía cualquiera de estos campos para hacer otros cambios:

Para	Envía
Eliminar el tope	`"consumptionLimit": { "usd": null }`
Restablecer el tope mensualmente en lugar de a diario	`"limitPeriod": "MONTH"`
Convertir el tope en un presupuesto único	`"limitPeriod": "LIFETIME"`
Ampliar la expiración	`"expiresAt": "2027-12-31"`
Eliminar la expiración	`"expiresAt": null`
Aceptar solo solicitudes de tus servidores	`"ipAllowlist": ["11.22.33.0/24"]`
Volver a aceptar solicitudes desde cualquier IP	`"ipAllowlist": []`
Permitir solo modelos privados	`"modelPrivacy": "PRIVATE_ONLY"`
Renombrar la clave	`"description": "cust:acme-prod"`

Un nuevo limitPeriod se aplica de inmediato, así que cambiar a LIFETIME cuenta todo el gasto anterior de la clave contra el tope. apiKeyType no se puede cambiar; crea una clave nueva en su lugar.

Revocar o rotar una clave

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

requests.delete(f"{BASE}/api_keys", headers=HEADERS, params={"id": key_id}).raise_for_status()

await fetch(`${BASE}/api_keys?id=${keyId}`, { method: "DELETE", headers });

La respuesta es { "success": true }. La revocación es inmediata: la siguiente solicitud de la clave recibe 401 Authentication failed, y la clave desaparece de GET /api_keys. Sus cargos anteriores permanecen en el historial de uso. Para rotar una clave sin tiempo de inactividad:

Crear la sustituta

Crea una nueva clave con la misma configuración y guarda su secreto.

Desplegarla

Cambia tu aplicación para que use el nuevo secreto.

Revocar la clave anterior

Cuando el lastUsedAt de la clave anterior en GET /api_keys deje de cambiar, elimínala.

Errores que pueden ver quienes llaman a la API

Estado	Mensaje	Qué hacer
`402`	`API key USD spend limit exceeded...`, o el mismo para DIEM	Aumenta o elimina el tope, o espera al siguiente periodo. Es posible que la cuenta en sí todavía tenga fondos.
`403`	La configuración de privacidad de la clave no permite el modelo	Usa un modelo Private, TEE o E2EE, o cambia `modelPrivacy`.
`403`	`This API key is restricted to configured IP addresses...`	Añade la IP de quien llama a `ipAllowlist`.
`401`	`Authentication failed`	La clave está revocada, ha expirado o está mal escrita.
`401`	`Admin API key required`	Una clave Inference llamó a un endpoint de gestión de claves o de facturación.
`429`	`Too many API key creation requests...`	La creación de claves está limitada a 20 por minuto. Espera y vuelve a intentarlo.
`400`	`Maximum number of active API keys (500) reached...`	Revoca las claves que ya no uses o contacta con soporte.

Consulta Códigos de error para ver la lista completa.

Buenas prácticas

Mantén las claves Admin en tu servidor y reparte solo claves Inference.
Da a cada aplicación, entorno y cliente su propia clave, para que cada una se pueda supervisar y revocar de forma independiente.
Pon tu propio identificador en description. Las analíticas de uso etiquetan las claves con él.
Establece un tope y una expiración para cada clave que entregues a otra persona, y restringe las claves de servidor a servidor a tus IP con ipAllowlist.

Referencia de la API

Crear clave de API

Todos los campos aceptados al crear.

Actualizar clave de API

Cambia límites, expiración, privacidad e IP.

Listar claves de API

Todas las claves activas con su uso.

Eliminar clave de API

Revoca una clave.

Analíticas de uso

Gasto por clave, modelo y día.

Historial de uso

Cada cargo, con su clave de API.

Documentación

Primeros pasos

Texto y chat

Imagen

Vídeo

Audio

Búsqueda y RAG

Agentes e integraciones

Herramientas de código

Herramientas para agentes

SDK y frameworks

Crear

Supervisar

Cambiar

Revocar

Cómo funciona

Crear una clave

Configuración de la clave

Supervisar el uso

Una clave

Gasto por clave a lo largo del tiempo

Cada cargo, por clave

Si una clave puede gastar ahora mismo

Cambiar límites y configuración

Revocar o rotar una clave

Errores que pueden ver quienes llaman a la API

Buenas prácticas

Referencia de la API

Crear clave de API

Actualizar clave de API

Listar claves de API

Eliminar clave de API

Analíticas de uso

Historial de uso

Crear

Supervisar

Cambiar

Revocar

​Cómo funciona

​Crear una clave

​Configuración de la clave

​Supervisar el uso

​Una clave

​Gasto por clave a lo largo del tiempo

​Cada cargo, por clave

​Si una clave puede gastar ahora mismo

​Cambiar límites y configuración

​Revocar o rotar una clave

​Errores que pueden ver quienes llaman a la API

​Buenas prácticas

​Referencia de la API

Crear clave de API

Actualizar clave de API

Listar claves de API

Eliminar clave de API

Analíticas de uso

Historial de uso

Cómo funciona

Crear una clave

Configuración de la clave

Supervisar el uso

Una clave

Gasto por clave a lo largo del tiempo

Cada cargo, por clave

Si una clave puede gastar ahora mismo

Cambiar límites y configuración

Revocar o rotar una clave

Errores que pueden ver quienes llaman a la API

Buenas prácticas

Referencia de la API