APIs de IA: protocolo, API Key e primeira solicitação

Acesso por API, assinatura web e conta compartilhada

São produtos diferentes:

Para o desenvolvimento normal, use uma conta e uma chave sob seu controle. Não crie uma integração baseada em um login comprado ou compartilhado.

1. Escolha o protocolo exigido pelo cliente

Leia a documentação do cliente ou SDK antes de escolher um modelo. Use OpenAI-compatible quando a ferramenta esperar um OpenAI SDK, Chat Completions, Responses API ou um campo como OPENAI_BASE_URL. Use Anthropic-compatible quando ela criar solicitações Messages e esperar ANTHROPIC_BASE_URL ou x-api-key.

O nome do modelo não determina o protocolo. O cliente precisa criar o mesmo contrato de requisição aceito pelo endpoint.

Na BetterToken, as Base URLs são:

OpenAI-compatible Base URL:  https://www.bettertoken.ai/v1
Anthropic-compatible Base URL: https://bettertoken.ai/

O valor OpenAI-compatible já inclui /v1. O valor Anthropic-compatible não inclui; uma solicitação Messages via HTTP direto usa o caminho completo do recurso /v1/messages.

2. Diferencie Base URL do caminho da requisição

Normalmente, um SDK ou uma ferramenta pede a Base URL e acrescenta o caminho do recurso. Uma chamada HTTP direta precisa do caminho completo.

OpenAI-compatible raw path:  https://www.bettertoken.ai/v1/chat/completions
Anthropic Messages raw path: https://www.bettertoken.ai/v1/messages

Não cole o caminho completo de uma requisição em um campo que espera apenas a Base URL. Caso contrário, o cliente pode acrescentar o recurso duas vezes e retornar 404.

3. Mantenha a API Key fora do código

Use variáveis de ambiente locais no primeiro teste e depois mova as credenciais de produção para o gerenciador de segredos fornecido pela sua plataforma.

export BETTERTOKEN_API_KEY="your_api_key_here"
export BETTERTOKEN_MODEL_ID="your_current_model_id"

Nunca coloque uma chave real no código-fonte, em .env.example, prompt, issue, captura de tela ou mensagem de suporte. Copie o Model ID atual e exato da documentação ou do catálogo de modelos do provedor, em vez de tentar deduzi-lo de um nome de marketing.

4. Envie uma solicitação OpenAI-compatible mínima

Comece com uma solicitação curta somente de texto antes de habilitar streaming ou ferramentas:

curl https://www.bettertoken.ai/v1/chat/completions \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$BETTERTOKEN_MODEL_ID"'",
    "messages": [{"role": "user", "content": "Reply with API_OK"}],
    "max_tokens": 16
  }'

Evite curl -v em logs compartilhados, pois a saída verbose pode expor headers sensíveis.

5. Envie uma solicitação Anthropic-compatible mínima

A solicitação Messages usa outro cabeçalho de autenticação e outro formato de corpo:

curl https://www.bettertoken.ai/v1/messages \
  -H "x-api-key: $BETTERTOKEN_API_KEY" \
  -H "anthropic-version: CURRENT_SUPPORTED_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$BETTERTOKEN_MODEL_ID"'",
    "max_tokens": 16,
    "messages": [{"role": "user", "content": "Reply with API_OK"}]
  }'

CURRENT_SUPPORTED_VERSION é um placeholder. Antes do teste, confirme o cabeçalho compatível no momento na referência da API. Se a tarefa for especificamente um acesso Claude-compatible, consulte os limites e a configuração da Claude API antes de voltar à solicitação mínima.

6. Verifique a resposta e o registro de uso

O primeiro teste só termina quando estes sinais estão de acordo:

• o HTTP status indica sucesso;
• a resposta contém o Model ID esperado ou seu valor de exibição documentado;
• o contrato selecionado retorna os campos esperados de content e usage;
• o BetterToken Workspace mostra um registro no mesmo horário, com modelo, status, tokens de input/output/cache aplicáveis e o valor cobrado.

O Workspace é um registro de uso e cobrança. Não presuma que ele armazena o prompt completo ou o corpo da resposta. Consulte o catálogo de modelos atual para disponibilidade e preços, em vez de copiar uma lista dinâmica para as notas da integração.

7. Resolva problemas por camada da resposta

• 401 ou 403: confira a chave, o key group, espaços acidentais, a Base URL e o cabeçalho de autenticação exigido pelo protocolo escolhido.
• 404: compare a Base URL com o path completo. Procure /v1, /chat/completions ou /messages duplicados.
• model not found: copie o Model ID atual e exato e confirme que ele está disponível para o key group e o protocolo escolhidos.
• 429: leia o corpo da resposta, respeite qualquer intervalo de repetição e verifique a concorrência ou os limites de taxa atuais antes de enviar mais uma solicitação.
• Timeout ou TLS error: diferencie condições locais de proxy, firewall, DNS e certificados de uma resposta da API. Não desative permanentemente a verificação TLS.
• Sem registro no Workspace: confirme se uma variável de ambiente antiga não direcionou a solicitação para outro provedor.

Depois de alterar a configuração, envie novamente uma única solicitação curta e associe-a ao registro no Workspace. Quando ela funcionar, adicione streaming, ferramentas, contextos maiores ou um loop de agente, uma camada por vez, para manter pequena a superfície de diagnóstico de cada nova falha.

Próximo passo: API compatível com OpenAI

Para um caminho prático de configuração com sua própria chave e uma rota compatível com OpenAI, consulte a página da API OpenAI. Ela descreve uma API compatível da BetterToken, não uma chave oficial da OpenAI.