> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gestionar claves de API

> Crea, limita, supervisa, actualiza y revoca claves de API de Venice desde código con una clave Admin.

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.

> [card] [Crear](#create-a-key)
>
> Emite una clave con un tope de gasto

> [card] [Supervisar](#track-usage)
>
> Consulta cuánto gasta cada clave

> [card] [Cambiar](#change-limits-and-settings)
>
> Aumenta un tope o amplía una expiración

> [card] [Revocar](#revoke-or-rotate-a-key)
>
> Desactiva una clave de inmediato

## Cómo funciona

Clave Admin
Tu clave de control
Crea, cambia y revoca claves
Lee el uso y la facturación
Se queda en tu servidor

Inference
cust:acme

\$50 / mes
Solo modelos privados

Inference
cust:globex

\$5 / mes
Solo desde 11.22.33.0/24

Inference
staging

\$10 / día
Expira 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/*`) | ✓ | |

> [!NOTE]
>
> Crea tu primera clave Admin en el panel: sigue [Generar una clave de API](https://docs.venice.ai/es/guides/getting-started/generating-api-key.md) 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`:

```bash cURL theme={"system"}
export VENICE_ADMIN_KEY="your-admin-key"
```

```python Python theme={"system"}
import os
import requests

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

```javascript Node.js theme={"system"}
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:

```bash cURL theme={"system"}
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"
  }'
```

```python Python theme={"system"}
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"]
```

```javascript Node.js theme={"system"}
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;
```

```json Response theme={"system"}
{
  "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": []
  }
}
```

> [!WARNING]
>
> `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.

> [!TIP]
>
> ¿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](https://docs.venice.ai/es/guides/integrations/generating-api-key-agent.md).

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

```bash cURL theme={"system"}
curl https://api.venice.ai/api/v1/api_keys/e28e82dc-9df2-4b47-b726-d0a222ef2ab5 \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"
```

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

```javascript Node.js theme={"system"}
const res = await fetch(`${BASE}/api_keys/${keyId}`, { headers });
const { data: key } = await res.json();
```

```json Response (trimmed) theme={"system"}
{
  "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.

```bash cURL theme={"system"}
curl "https://api.venice.ai/api/v1/billing/usage-analytics?lookback=30d" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"
```

```json Response (trimmed) theme={"system"}
{
  "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.

```bash cURL theme={"system"}
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"
```

```python Python theme={"system"}
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.

```bash cURL theme={"system"}
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:

```bash cURL theme={"system"}
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 }
  }'
```

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

```javascript Node.js theme={"system"}
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

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

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

```javascript Node.js theme={"system"}
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:

**1. Crear la sustituta**

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

**2. Desplegarla**

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

**3. 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](https://docs.venice.ai/es/api-reference/error-codes.md) 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

> [card] [Crear clave de API](https://docs.venice.ai/es/api-reference/endpoint/api_keys/create.md)
>
> Todos los campos aceptados al crear.

> [card] [Actualizar clave de API](https://docs.venice.ai/es/api-reference/endpoint/api_keys/update.md)
>
> Cambia límites, expiración, privacidad e IP.

> [card] [Listar claves de API](https://docs.venice.ai/es/api-reference/endpoint/api_keys/list.md)
>
> Todas las claves activas con su uso.

> [card] [Eliminar clave de API](https://docs.venice.ai/es/api-reference/endpoint/api_keys/delete.md)
>
> Revoca una clave.

> [card] [Analíticas de uso](https://docs.venice.ai/es/api-reference/endpoint/billing/usage-analytics.md)
>
> Gasto por clave, modelo y día.

> [card] [Historial de uso](https://docs.venice.ai/es/api-reference/endpoint/billing/usage-history.md)
>
> Cada cargo, con su clave de API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.