A dificuldade de integrar a Claude API não está em "saber enviar uma requisição HTTP", mas em alguns detalhes que costumam pegar: em qual cabeçalho vai a chave, se anthropic-version é obrigatório, por que max_tokens não pode ser omitido e por que content é um array em vez de uma string. Acertando esses pontos, a chamada mínima funciona em dez minutos.
Este artigo segue a ordem "conta e chave, cabeçalhos, curl, Python, streaming e parâmetros, diagnóstico de erros, segurança da chave" e, ao final, explica como usar um gateway compatível como entrada alternativa. IDs de modelo, contexto e cobrança seguem a documentação oficial da Anthropic e a página de preços do site.
Nota: Anthropic e Claude são marcas de seus titulares; OpenAI é marca de seu titular. Este artigo é apenas uma explicação técnica de integração. Modelos, preços e cotas podem mudar; confirme a documentação oficial antes de integrar.
1. Antes de começar: conta, workspace e chave
A Claude API usa o Anthropic Console para gerenciar conta, workspace, API Keys e faturamento. Antes de começar, confirme três pontos:
| Item | O que confirmar | Observação |
|---|---|---|
| Conta | E-mail verificável e acesso ao Console | Para equipes, prefira um e-mail corporativo |
| Workspace | A qual workspace a chave pertence | O workspace determina membros, chaves e consumo |
| Faturamento | Forma de pagamento, dados de cobrança e limite disponível | Vale o que o Console exibir |
Se a equipe ainda não decidiu quem administra o faturamento, não crie uma chave de produção às pressas. Depois que a chave é distribuída, consumo e permissões ficam vinculados ao workspace correspondente, e separar custos mais tarde sai mais caro.
2. Como criar uma API Key em seis passos
- Abra o Anthropic Console (console.anthropic.com), registre-se ou entre na conta e conclua a verificação de e-mail.
- Crie ou selecione um workspace. A recomendação é separar produção, testes e experimentos pessoais, evitando usar uma única chave em todo lugar.
- Acesse a página API Keys, crie uma nova chave e dê um nome que explique o uso, por exemplo
prod-backend-2026-10. - Copie a chave e guarde imediatamente em um gerenciador de segredos ou variável de ambiente. Na maioria dos consoles, o valor completo aparece apenas na criação.
- Na página de faturamento do Console, confirme forma de pagamento, dados de cobrança e limites. Se há pré-pagamento, nota fiscal e teto de cota depende das opções reais do console.
- Configure a variável de ambiente local e envie uma requisição mínima para validar a chave.
export ANTHROPIC_API_KEY="sk-ant-sua-chave"
Não coloque a chave no código, em repositórios Git, em páginas de front-end ou em históricos de conversa. Mesmo na fase de testes, crie uma chave separada para poder revogá-la a qualquer momento.
3. Cabeçalhos e chamada curl mínima
O endpoint da Messages API é POST https://api.anthropic.com/v1/messages. Três cabeçalhos são essenciais:
| Cabeçalho | Valor | Função |
|---|---|---|
x-api-key |
Sua API Key | Autenticação da chave Anthropic |
anthropic-version |
2023-06-01 |
Define a versão da API; a ausência pode gerar erro |
content-type |
application/json |
Declara o corpo JSON |
Atenção: a API Key vai em x-api-key, não em Authorization: Bearer. Misturar os dois esquemas de autenticação é uma causa muito comum de erro 401.
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"system": "Você é um assistente técnico. Responda de forma concisa.",
"messages": [
{"role": "user", "content": "Explique em três frases o que é um gateway de API."}
]
}'
O ID de modelo do exemplo é apenas um dos disponíveis no momento; modelos realmente disponíveis, contexto e preços seguem a Models API oficial e a página de preços. O content da resposta é um array de blocos; o texto costuma estar em content[0].text, mas o mais seguro é percorrer o array e verificar type == "text".
4. Chamada da Messages API em Python
Instale o SDK oficial:
pip install anthropic
Chamada mínima:
import os
import anthropic
client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
resp = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system="Você é um assistente técnico. Responda de forma concisa.",
messages=[
{"role": "user", "content": "Explique em três frases o que é um gateway de API."}
],
)
for block in resp.content:
if block.type == "text":
print(block.text)
print(resp.stop_reason)
print(resp.usage.input_tokens, resp.usage.output_tokens)
Alguns pontos importantes:
systemé um parâmetro de nível superior; não o escreva como mensagem{"role": "system"}. Na Messages API, os papéis das mensagens são principalmenteusereassistant.max_tokensé obrigatório e define o tamanho máximo da resposta. Valor pequeno demais trunca a saída estop_reasonmostramax_tokens; valor grande demais exige considerar custo e timeout.resp.contenté um array de blocos e pode conter blocos de texto, de raciocínio ou de chamada de ferramenta. O código de negócio não deve assumir que só existe texto.- Registre
usageestop_reason: conciliação e diagnóstico dependem deles.
5. system, max_tokens e streaming
system é usado para papel, formato de saída e condições de contorno. Conteúdo estável fica no início; a entrada variável do usuário vai em messages, o que favorece o acerto de cache.
max_tokens não é "quanto maior, melhor". Ele limita apenas a saída de uma chamada e não altera o custo de entrada; relatórios longos e código extenso precisam de espaço, enquanto classificação e extração podem usar valores menores. Em produção, configure por tipo de endpoint, não um valor global.
Streaming é adequado para respostas longas e interfaces interativas. No SDK Python:
with client.messages.stream(
model="claude-opus-5-5",
max_tokens=4096,
system="Você é um assistente técnico.",
messages=[{"role": "user", "content": "Escreva uma descrição de produto com 200 palavras."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
Requisições em streaming também retornam usage e stop_reason; não os omita ao persistir os dados. Com HTTP nativo, adicione "stream": true ao corpo: a resposta é um fluxo de eventos SSE, interpretado por eventos como content_block_delta.
6. Nomes de modelo e escolha de versão
Os modelos Claude são divididos em séries como Opus, Sonnet e Haiku, com posicionamento, contexto e preços diferentes. Os IDs costumam aparecer em duas formas: alias estável e snapshot com data. Em produção, defina qual usar e não copie o nome exibido no console para o código.
Ordem de escolha sugerida:
- Use primeiro o conjunto de avaliação do seu negócio para filtrar a série que atende à qualidade.
- Depois compare latência, contexto e custo.
- Por fim, confirme se o modelo está disponível na região e no modo de acesso desejados.
Modelos entram e saem de linha, e IDs antigos podem entrar em estado legacy. Centralize os nomes em configuração ou tabela de mapeamento, para migrar mudando um único ponto. Modelos disponíveis seguem a Models API oficial, o console e a página de preços.
7. Como diagnosticar 401, 429 e 400
| Código | Causas comuns | Ordem de verificação |
|---|---|---|
| 401 | Chave ausente, cabeçalho errado, chave revogada, workspace incompatível | Verifique x-api-key, espaços e quebras de linha, status da chave e base URL |
| 429 | Limite de requisições ou de tokens, pico de concorrência, problema de cota | Leia retry-after, faça backoff exponencial com jitter, separe chaves, reduza concorrência |
| 400 | JSON inválido, max_tokens ausente, ID de modelo errado, parâmetro fora do limite |
Guarde o corpo do erro e o request id e revise o corpo item a item |
| 404 | Caminho ou nome de modelo inexistente | Confirme /v1/messages e o ID do modelo |
| 5xx | Falha temporária do upstream | Retente um número limitado de vezes; se persistir, use a entrada alternativa |
Ao diagnosticar, guarde primeiro o cabeçalho request-id da resposta. Em 401, não suspeite da cota antes de verificar o cabeçalho de autenticação e a própria chave; em 429, não é necessariamente "saldo acabou", pode ser limite de taxa; em 400, quase sempre é problema no corpo, e a mensagem costuma indicar o campo específico.
8. Segurança da chave e gateway compatível como alternativa
Segurança da chave exige ao menos quatro práticas: armazenar apenas em variável de ambiente ou gerenciador de segredos; separar chaves por projeto; configurar alertas de consumo; rotacionar periodicamente e revogar chaves de membros desligados. Front-end, aplicativos móveis e repositórios públicos não podem conter chaves de longa duração.
Equipes que enfrentam problemas de rede, pagamento ou nota fiscal podem usar um gateway com endpoint compatível com Anthropic em vez do endereço oficial. Com o SDK oficial, normalmente basta alterar base_url e a chave:
import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ["ZSQH_API_KEY"],
base_url="https://ai.zhongshangqihang.com",
)
resp = client.messages.create(
model="conforme a lista de modelos do site",
max_tokens=256,
messages=[{"role": "user", "content": "Responda apenas OK"}],
)
print(resp.content)
Se o gateway oferecer apenas interface compatível com OpenAI, será preciso mudar a estrutura da requisição ou adicionar uma camada de adaptação; trocar só a base URL não basta. Ao escolher um gateway, confirme três pontos: suporte ao protocolo nativo da Anthropic, como os nomes de modelo são mapeados e se as políticas de limite e logs são transparentes.
9. Perguntas frequentes
A Claude API é a mesma coisa que a assinatura do Claude na web?
Não. A versão web é uma assinatura de produto para usuários finais; a API é cobrada por consumo, e os dois têm sistemas de conta, cotas e administração diferentes. Chaves, faturamento e consumo da API são gerenciados no Anthropic Console.
Depois de criar a API Key, ainda consigo ver o valor completo?
Na maioria dos casos, o valor completo aparece só na criação. Depois disso, só é possível ver o prefixo ou o nome. Guarde-o imediatamente no gerenciador de segredos; se perder, revogue a chave antiga e crie outra.
Por que max_tokens é obrigatório?
A Messages API exige declarar explicitamente o limite de saída de uma chamada, para controlar tamanho e recursos. Omitir retorna 400. Defina um valor razoável por tarefa, sem preencher o máximo por padrão.
O 429 é cota esgotada ou concorrência alta?
Os dois são possíveis. Veja primeiro o corpo da resposta e o retry-after: ocorrências concentradas em curto intervalo geralmente indicam limite de taxa ou concorrência; ocorrências persistentes com cota de faturamento anormal pedem verificação do plano e do consumo. As ações incluem retry com backoff, redução de concorrência e separação de chaves.
Equipes precisam obrigatoriamente usar um gateway?
Não. Equipes com conexão direta estável, pagamento viável e avaliação de conformidade concluída podem usar o acesso oficial, que é mais simples. Avalie um gateway quando precisar de cobrança em moeda local, nota fiscal, entrada unificada para vários modelos ou otimização de rede, e confirme as políticas de dados e de falhas.
Próximo passo
Crie uma conta no ZSQH AI Gateway, execute a requisição mínima de /v1/messages com uma chave de teste e só depois integre ao negócio. Modelos, contexto e cobrança seguem a página de preços.
Leituras relacionadas:
