Primeiros passos
Autenticação
Autentique solicitações da API TokenLab com uma chave de API
Chaves de API
Chamadas de modelo e recursos privados exigem uma chave de API. Endpoints de descoberta pública, como GET /v1/models e GET /v1/models/{model}, funcionam sem uma. Uma resposta de descoberta bem-sucedida não verifica se sua chave funciona; siga o Quickstart para enviar uma solicitação de modelo. Use a chave completa salva; o prefixo na lista de chaves não pode autenticar.
Para endpoints compatíveis com OpenAI, envie como:
Authorization: Bearer sk-your-api-keyPara solicitações /v1/messages compatíveis com Anthropic, você também pode usar:
x-api-key: sk-your-api-keySolicitações /v1beta/* compatíveis com Gemini também aceitam x-goog-api-key: sk-your-api-key. Prefira um cabeçalho em vez do parâmetro de consulta ?key=, pois URLs frequentemente acabam em logs.
Tokens de Gerenciamento
Endpoints da API de gerenciamento usam um tipo de token separado:
Authorization: Bearer mt-your-management-tokenUse tokens de gerenciamento apenas com endpoints /v1/management/*. Abra API → Tokens para o workspace selecionado para criar ou substituir um token. Salve o token completo quando ele for exibido; ele é mostrado apenas uma vez após a criação ou substituição.
Tokens de gerenciamento não podem ser usados para inferência de modelo, e chaves de API padrão sk-... não podem ser usadas para a API de Gerenciamento.
Obter uma chave de API
- Faça login no TokenLab Console
- Abra API Keys
- Crie uma nova chave
- Dê a ela um nome descritivo
- Copie-a imediatamente, pois ela é mostrada apenas uma vez
- Nunca exponha chaves de API em código do lado do cliente
- Nunca envie chaves de API para controle de versão
- Use variáveis de ambiente ou um gerenciador de segredos
- Rotacione as chaves periodicamente
- Exclua chaves não utilizadas
Usar uma chave de API
Veja o Início Rápido para variáveis de ambiente e uma primeira solicitação completa. Use o SDK correspondente ao seu formato de API escolhido; mantenha as chaves no servidor.
Configurações de chave
Você pode definir estas opções em cada chave de API no Console e através da API de Gerenciamento:
| Configuração | Descrição |
|---|---|
| Limite de gastos | No limit permite que a chave use o saldo do Workspace. Fixed limit faz com que a chave retorne 402 quota_exceeded após atingir o valor. |
| Modelos permitidos | A chave pode chamar apenas estes modelos. Outros modelos retornam 403 model_not_allowed. Vazio significa sem restrição no nível da chave. |
| Opção de entrega | Auto, Verified ou Official para solicitações desta chave. Vazio usa o padrão do Workspace. Veja Faturamento e preços. |
| Expiração | Após este período, a chave retorna 401 expired_api_key. |
| Status | Uma chave inactive (pausada) retorna 401 invalid_api_key. Uma chave revoked não pode ser ativada novamente. |
Prefixo da chave
Todas as chaves de API do TokenLab começam com sk-.
Respostas de erro
| Código de Status | Tipo | Código | Descrição |
|---|---|---|---|
| 401 | invalid_api_key | invalid_api_key | A chave de API está ausente, inválida, inativa ou revogada |
| 401 | expired_api_key | expired_api_key | A chave expirou |
| 402 | insufficient_balance | insufficient_balance | Saldo da conta insuficiente |
| 402 | quota_exceeded | quota_exceeded | Limite de uso da chave de API atingido |
| 403 | permission_error | model_not_allowed | A chave não tem permissão para usar o modelo solicitado |
| 403 | permission_error | user_suspended, account_restricted | A conta não pode usar a API |
| 429 | rate_limit_exceeded | rate_limit_exceeded | Muitas tentativas de autenticação com falha de um endereço IP. Aguarde o Retry-After e corrija a chave; não crie loops em 401 |
Exemplo:
{
"error": {
"message": "Invalid API key",
"type": "invalid_api_key",
"code": "invalid_api_key"
}
}