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

# Gerenciando chaves de API

> Crie, limite, acompanhe, atualize e revogue chaves de API Venice por código com uma chave Admin.

Uma chave Admin pode gerenciar todas as suas outras chaves de API pela API. Dê a cada app, ambiente ou cliente sua própria chave de Inference, limite quanto cada uma pode gastar, acompanhe o uso por chave e altere ou revogue chaves sem abrir o painel.

> [card] [Criar](#create-a-key)
>
> Emita uma chave com limite de gasto

> [card] [Acompanhar](#track-usage)
>
> Veja quanto cada chave gasta

> [card] [Alterar](#change-limits-and-settings)
>
> Aumente um limite ou estenda uma expiração

> [card] [Revogar](#revoke-or-rotate-a-key)
>
> Desative uma chave imediatamente

## Como funciona

Chave Admin
Sua chave de controle
Cria, altera e revoga chaves
Lê uso e cobrança
Fica no seu servidor

Inference
cust:acme

\$50 / mês
Apenas modelos privados

Inference
cust:globex

\$5 / mês
Apenas de 11.22.33.0/24

Inference
staging

\$10 / dia
Expira em 30 de jun.

Chaves Admin podem chamar todos os endpoints, incluindo os que gerenciam chaves e leem dados de cobrança. Chaves de Inference podem chamar modelos, mas não podem gerenciar chaves nem ler dados de cobrança, por isso são as chaves que você distribui.

| | Admin | Inference |
| - | :-: | :-: |
| Chamar modelos e outros endpoints de inferência | ✓ | ✓ |
| Consultar o próprio saldo e limites de taxa (`GET /api_keys/rate_limits`) | ✓ | ✓ |
| Criar, atualizar e revogar chaves (`/api_keys`) | ✓ | |
| Ler uso e cobrança (`/billing/*`) | ✓ | |

> [!NOTE]
>
> Crie sua primeira chave Admin no painel: siga [Gerando uma chave de API](https://docs.venice.ai/pt-BR/guides/getting-started/generating-api-key.md) e escolha **Admin** como tipo de chave. Mantenha-a em um armazenamento de segredos do lado do servidor, nunca em código do lado do cliente.

Os exemplos desta página leem a chave 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",
};
```

## Criar uma chave

Este exemplo cria uma chave de Inference para um cliente, com limite de \$50 por mês e expiração em 30 de junho 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` é o segredo da chave, e esta resposta é a única vez em que você o verá. Armazene-o imediatamente. Se ele for perdido, revogue a chave e crie uma nova. Guarde também o `data.id`: todas as outras chamadas desta página o utilizam.

### Configurações da chave

Defina estas configurações ao criar uma chave ou altere-as depois com `PATCH /api_keys`. O corpo da requisição é estrito, então um campo desconhecido retorna `400`.

| Campo | Valores | O que faz |
| - | - | - |
| `apiKeyType` | `INFERENCE` ou `ADMIN` | Obrigatório na criação. Não pode ser alterado depois. |
| `description` | Até 64 caracteres | Obrigatório na criação. As análises de uso identificam a chave por ele, então coloque aqui seu próprio identificador, como `cust:acme`. |
| `consumptionLimit` | `{ "usd": 50 }` | Limite de gasto para cada `limitPeriod`, em `usd`, `diem` ou ambos. Omita uma moeda, ou defina-a como `null`, para não ter limite. O limite em USD contabiliza USD, créditos incluídos e créditos ganhos em conjunto. |
| `limitPeriod` | `EPOCH`, `MONTH`, `LIFETIME` | Quando o limite é reiniciado. `EPOCH`, o padrão, reinicia diariamente às 00:00 UTC, `MONTH` no dia 1º de cada mês (UTC) e `LIFETIME` nunca. |
| `expiresAt` | `"2027-06-30"` | Uma data ou um horário UTC como `"2027-06-30T23:59:59Z"`. Uma data sozinha significa 00:00 UTC desse dia. Omita para uma chave que nunca expira. |
| `modelPrivacy` | `ALL`, `PRIVATE_TEXT`, `PRIVATE_ONLY` | `ALL`, o padrão, permite qualquer modelo. `PRIVATE_TEXT` exige modelos de texto e embedding Private, TEE ou E2EE. `PRIVATE_ONLY` exige isso para todos os modelos. |
| `ipAllowlist` | `["11.22.33.0/24"]` | Até 100 endereços IPv4 ou IPv6 públicos ou intervalos CIDR. Uma lista vazia permite qualquer IP. |

Você pode criar até 20 chaves por minuto e manter até 500 chaves ativas. Entre em contato com o suporte se precisar de mais.

> [!TIP]
>
> Está construindo um agente? Uma carteira com VVV em staking na Base pode emitir sua própria chave sem uma conta Venice. Consulte [Criação de chave de API por agente autônomo](https://docs.venice.ai/pt-BR/guides/integrations/generating-api-key-agent.md).

## Acompanhar o uso

| Para descobrir | Chame | Leia |
| - | - | - |
| Quanto uma chave gastou neste período | `GET /api_keys/{id}` | `currentPeriodUsage` |
| Quanto cada chave gastou nos últimos 7 dias | `GET /api_keys` | `usage.trailingSevenDays` |
| Gasto por chave, por dia | `GET /billing/usage-analytics` | `byKey`, `byKeyDaily` |
| Cada cobrança, com a chave à qual foi faturada | `GET /billing/usage-history` | `apiKeyId` |
| Se uma chave pode gastar agora | `GET /api_keys/rate_limits`, chamado com essa chave | `accessPermitted`, `balances` |
| Quais chaves estão atingindo limites de taxa | `GET /api_keys/rate_limits/log` | `apiKeyId`, `modelId` |

### Uma chave

```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 chave usou $12,50 dos seus $50 do mês. `currentPeriodUsage` só aparece em chaves com limite em USD ou DIEM, e os valores de uso são strings com quatro casas decimais. As respostas retornam `consumptionLimits` (plural), enquanto as requisições enviam `consumptionLimit` (singular).

### Gasto por chave ao longo do tempo

`GET /billing/usage-analytics` retorna os totais por chave em `byKey` e uma linha por dia em `byKeyDaily`, prontos para gráficos. Passe `lookback` (`7d` por padrão, até `90d`) ou um par `startDate` e `endDate` que abranja até 90 dias. Os resultados ficam em cache por 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 cobrança, por chave

`GET /billing/usage-history` lista cada cobrança, e cada entrada traz o `apiKeyId` ao qual foi faturada. Use-o para conciliar gastos ou cobrar seus próprios clientes. As entradas são retornadas da mais antiga para a mais recente. Envie `nextCursor` de volta como `cursor`, sozinho, até que ele seja `null`. Envie `Accept: text/csv` para receber CSV.

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

As cobranças têm `amount` negativo, então o loop o subtrai para obter um total positivo por chave e moeda. Entradas sem `apiKeyId` vêm do app web da Venice ou são lançamentos da conta, como compras de créditos.

### Se uma chave pode gastar agora

`GET /api_keys/rate_limits` funciona com qualquer chave e informa sobre a chave que o chama. `accessPermitted` indica se a chave pode gastar agora, e `balances` mostra quanto ela ainda tem para 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`, com uma chave Admin, retorna as suas últimas 50 ocorrências de limite de taxa, cada uma com seu `apiKeyId` e `modelId`.

## Alterar limites e configurações

Envie o `id` da chave e apenas os campos que você quer alterar. Todo o resto permanece como está. Este exemplo aumenta o limite para \$100 por mês:

```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 } }),
});
```

Em vez disso, envie qualquer um destes campos para fazer outras alterações:

| Para | Envie |
| - | - |
| Remover o limite | `"consumptionLimit": { "usd": null }` |
| Reiniciar o limite mensalmente em vez de diariamente | `"limitPeriod": "MONTH"` |
| Tornar o limite um orçamento único | `"limitPeriod": "LIFETIME"` |
| Estender a expiração | `"expiresAt": "2027-12-31"` |
| Remover a expiração | `"expiresAt": null` |
| Aceitar requisições apenas dos seus servidores | `"ipAllowlist": ["11.22.33.0/24"]` |
| Voltar a aceitar requisições de qualquer IP | `"ipAllowlist": []` |
| Permitir apenas modelos privados | `"modelPrivacy": "PRIVATE_ONLY"` |
| Renomear a chave | `"description": "cust:acme-prod"` |

Um novo `limitPeriod` entra em vigor imediatamente, então mudar para `LIFETIME` contabiliza todo o gasto anterior da chave no limite. `apiKeyType` não pode ser alterado; crie uma nova chave em vez disso.

## Revogar ou rotacionar uma chave

```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 });
```

A resposta é `{ "success": true }`. A revogação é imediata: a próxima requisição da chave recebe `401 Authentication failed`, e a chave deixa de aparecer em `GET /api_keys`. As cobranças anteriores dela permanecem no histórico de uso.

Para rotacionar uma chave sem tempo de inatividade:

**1. Crie a substituta**

Crie uma nova chave com as mesmas configurações e armazene o segredo dela.

**2. Implante-a**

Mude seu app para usar o novo segredo.

**3. Revogue a chave antiga**

Quando o `lastUsedAt` da chave antiga em `GET /api_keys` parar de mudar, exclua-a.

## Erros que seus chamadores podem ver

| Status | Mensagem | O que fazer |
| - | - | - |
| `402` | `API key USD spend limit exceeded...`, ou o mesmo para DIEM | Aumente ou remova o limite, ou aguarde o próximo período. A própria conta ainda pode ter fundos. |
| `403` | O modelo não é permitido pela configuração de privacidade da chave | Use um modelo Private, TEE ou E2EE, ou altere `modelPrivacy`. |
| `403` | `This API key is restricted to configured IP addresses...` | Adicione o IP do chamador ao `ipAllowlist`. |
| `401` | `Authentication failed` | A chave foi revogada, expirou ou foi digitada incorretamente. |
| `401` | `Admin API key required` | Uma chave de Inference chamou um endpoint de gerenciamento de chaves ou de cobrança. |
| `429` | `Too many API key creation requests...` | A criação de chaves é limitada a 20 por minuto. Aguarde e tente novamente. |
| `400` | `Maximum number of active API keys (500) reached...` | Revogue as chaves que você não usa mais ou entre em contato com o suporte. |

Consulte [Códigos de erro](https://docs.venice.ai/pt-BR/api-reference/error-codes.md) para a lista completa.

## Boas práticas

* Mantenha as chaves Admin no seu servidor e distribua apenas chaves de Inference.
* Dê a cada app, ambiente e cliente sua própria chave, para que cada uma possa ser acompanhada e revogada individualmente.
* Coloque seu próprio identificador em `description`. As análises de uso identificam as chaves por ele.
* Defina limite e expiração para toda chave que você entregar a outra pessoa, e restrinja chaves de servidor para servidor aos seus IPs com `ipAllowlist`.

## Referência da API

> [card] [Criar chave de API](https://docs.venice.ai/pt-BR/api-reference/endpoint/api_keys/create.md)
>
> Todos os campos aceitos na criação.

> [card] [Atualizar chave de API](https://docs.venice.ai/pt-BR/api-reference/endpoint/api_keys/update.md)
>
> Altere limites, expiração, privacidade e IPs.

> [card] [Listar chaves de API](https://docs.venice.ai/pt-BR/api-reference/endpoint/api_keys/list.md)
>
> Todas as chaves ativas com seu uso.

> [card] [Excluir chave de API](https://docs.venice.ai/pt-BR/api-reference/endpoint/api_keys/delete.md)
>
> Revogue uma chave.

> [card] [Análise de uso](https://docs.venice.ai/pt-BR/api-reference/endpoint/billing/usage-analytics.md)
>
> Gasto por chave, modelo e dia.

> [card] [Histórico de uso](https://docs.venice.ai/pt-BR/api-reference/endpoint/billing/usage-history.md)
>
> Cada cobrança, com sua chave de API.


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