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

Antes de conectar uma API de IA, identifique o contrato esperado pelo cliente: OpenAI-compatible ou Anthropic-compatible. Depois, use a Base URL documentada pelo provider, mantenha a API Key fora do código-fonte, envie uma solicitação curta e verifique tanto a resposta quanto o registro de uso. O fato de uma tela de configuração salvar sem erros não prova que a solicitação chegou ao endpoint pretendido.

Se você precisa de um API gateway em vez de uma assinatura web específica de um fornecedor, comece pela visão geral da API de IA da BetterToken. A BetterToken oferece interfaces OpenAI-compatible e Anthropic-compatible separadas. Você continua usando sua própria conta e API Key da BetterToken; essa chave não é uma chave do OpenAI Console nem do Anthropic Console.

Acesso por API, assinatura web e conta compartilhada

São produtos diferentes:

Forma de acesso	O que você recebe	O que isso não implica
Acesso por API	Solicitações HTTP autenticadas com sua própria chave	Acesso à assinatura de chat para consumidores de um fornecedor
Assinatura web	Uma interface específica e os limites incluídos no produto	Saldo de API transferível ou API Key de terceiros
Conta compartilhada	A sessão de login de outra pessoa	Uma integration segura ou adequada para production

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.

Em um provedor OpenAI-compatible, a Base URL e o caminho de Chat Completions podem ter esta forma:

Base URL: https://api.example.com/v1
Caminho completo: https://api.example.com/v1/chat/completions

Em um provedor Anthropic-compatible, a forma pode ser Base URL https://api.example.com e caminho completo de Messages https://api.example.com/v1/messages. São formas, não valores de configuração: copie os valores reais apenas da documentação do provedor escolhido.

Precisa conferir o protocolo e os campos da primeira requisição? Abrir a referência de configuração da API

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://api.example.com/v1/chat/completions
Anthropic Messages raw path: https://api.example.com/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 API_KEY="your_api_key_here"
export MODEL_ID="your_current_model_id"
export OPENAI_BASE_URL="https://api.example.com/v1"
export ANTHROPIC_BASE_URL="https://api.example.com"

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 "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$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 "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: CURRENT_SUPPORTED_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$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.

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 registro de uso ou cobrança do provedor mostra a solicitação com o status e o valor esperados.

A disponibilidade de modelos, os Model IDs e os preços mudam. Consulte o catálogo e a página de preços atuais do provedor escolhido antes de calcular um orçamento.

7. Resolva problemas por camada da resposta

• 401: confira a chave, espaços acidentais e o método de autenticação. Bearer e x-api-key não são intercambiáveis.
• 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.
• 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.

A ordem prática é identificar o contrato do cliente, guardar a chave como secret, configurar a Base URL correta, enviar uma solicitação curta e conferir resposta e registro de uso. Só então adicione streaming, ferramentas, contexto longo ou fluxo de agentes.

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.

As formas https://api.example.com, https://api.example.com/v1, https://api.example.com/v1/messages e https://api.example.com/v1/chat/completions são exemplos; use os valores documentados pelo provedor escolhido.