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

Para solicitações /v1/messages compatíveis com Anthropic, você também pode usar:

x-api-key: sk-your-api-key

Solicitaçõ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-token

Use 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

  1. Faça login no TokenLab Console
  2. Abra API Keys
  3. Crie uma nova chave
  4. Dê a ela um nome descritivo
  5. 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çãoDescrição
Limite de gastosNo 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 permitidosA 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 entregaAuto, Verified ou Official para solicitações desta chave. Vazio usa o padrão do Workspace. Veja Faturamento e preços.
ExpiraçãoApós este período, a chave retorna 401 expired_api_key.
StatusUma 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 StatusTipoCódigoDescrição
401invalid_api_keyinvalid_api_keyA chave de API está ausente, inválida, inativa ou revogada
401expired_api_keyexpired_api_keyA chave expirou
402insufficient_balanceinsufficient_balanceSaldo da conta insuficiente
402quota_exceededquota_exceededLimite de uso da chave de API atingido
403permission_errormodel_not_allowedA chave não tem permissão para usar o modelo solicitado
403permission_erroruser_suspended, account_restrictedA conta não pode usar a API
429rate_limit_exceededrate_limit_exceededMuitas 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"
  }
}

Nesta página