Gerenciando chaves de API

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.

Criar

Emita uma chave com limite de gasto

Acompanhar

Veja quanto cada chave gasta

Alterar

Aumente um limite ou estenda uma expiração

Revogar

Desative uma chave imediatamente

Como funciona

Chave AdminSua chave de controleCria, altera e revoga chavesLê uso e cobrançaFica no seu servidor

Inferencecust:acme$50 / mêsApenas modelos privados

Inferencecust:globex$5 / mêsApenas de 11.22.33.0/24

Inferencestaging$10 / diaExpira 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/*`)	✓

Crie sua primeira chave Admin no painel: siga Gerando uma chave de API 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:

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",
};

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:

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

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.

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

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

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

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

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.

cURL

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:

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

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

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

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:

Crie a substituta

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

Implante-a

Mude seu app para usar o novo segredo.

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

Criar chave de API

Todos os campos aceitos na criação.

Atualizar chave de API

Altere limites, expiração, privacidade e IPs.

Listar chaves de API

Todas as chaves ativas com seu uso.

Excluir chave de API

Revogue uma chave.

Análise de uso

Gasto por chave, modelo e dia.

Histórico de uso

Cada cobrança, com sua chave de API.

Documentação

Primeiros passos

Texto e chat

Imagem

Vídeo

Áudio

Pesquisa e RAG

Agentes e integrações

Ferramentas de código

Ferramentas para agentes

SDKs e frameworks

Criar

Acompanhar

Alterar

Revogar

Como funciona

Criar uma chave

Configurações da chave

Acompanhar o uso

Uma chave

Gasto por chave ao longo do tempo

Cada cobrança, por chave

Se uma chave pode gastar agora

Alterar limites e configurações

Revogar ou rotacionar uma chave

Erros que seus chamadores podem ver

Boas práticas

Referência da API

Criar chave de API

Atualizar chave de API

Listar chaves de API

Excluir chave de API

Análise de uso

Histórico de uso

Criar

Acompanhar

Alterar

Revogar

​Como funciona

​Criar uma chave

​Configurações da chave

​Acompanhar o uso

​Uma chave

​Gasto por chave ao longo do tempo

​Cada cobrança, por chave

​Se uma chave pode gastar agora

​Alterar limites e configurações

​Revogar ou rotacionar uma chave

​Erros que seus chamadores podem ver

​Boas práticas

​Referência da API

Criar chave de API

Atualizar chave de API

Listar chaves de API

Excluir chave de API

Análise de uso

Histórico de uso

Como funciona

Criar uma chave

Configurações da chave

Acompanhar o uso

Uma chave

Gasto por chave ao longo do tempo

Cada cobrança, por chave

Se uma chave pode gastar agora

Alterar limites e configurações

Revogar ou rotacionar uma chave

Erros que seus chamadores podem ver

Boas práticas

Referência da API