Source: https://aiprimetech.io/pt/learn/anthropic-python-sdk/ [Início](/pt/) / [Aprenda](/pt/learn/) / SDK Python da Anthropic: instalar, definir base_url, usar streaming e tratar erros # SDK de Python da Anthropic: instale, defina base_url, use streaming e trate erros O anthropic é o pacote do cliente Python oficial da Anthropic para a API do Claude. Ele cuida da autenticação, das novas tentativas, do streaming e dos erros tipados, e funciona sem alterações com qualquer endpoint compatível com a Anthropic: defina base_url (ou ANTHROPIC_BASE_URL) e o restante do seu código permanece igual. ## Instalação terminalCopiar ``` pip install anthropic ``` As versões 1.x são executadas em httpx2 e exigem Python 3.10 ou mais recente. Se você passar seu próprio cliente HTTP, use DefaultHttpxClient do SDK para manter os tempos limite e os limites de conexão padrão. ## Crie um cliente app.pyCopiar ``` import anthropic client = anthropic.Anthropic( api_key="your_key", # default: ANTHROPIC_API_KEY base_url="https://aiprimetech.io", # default: ANTHROPIC_BASE_URL, else https://api.anthropic.com ) ``` base_url é a raiz do host. O SDK acrescenta /v1/messages automaticamente, portanto https://aiprimetech.io/v1 produziria /v1/v1/messages e um campo 404 page not found. Com ambas as variáveis definidas no ambiente, anthropic.Anthropic() não precisa de nenhum argumento: terminalCopiar ``` export ANTHROPIC_API_KEY=your_key export ANTHROPIC_BASE_URL=https://aiprimetech.io ``` ## Envie uma mensagem app.pyCopiar ``` message = client.messages.create( model="claude-sonnet-5", max_tokens=1024, messages=[{"role": "user", "content": "Summarise TCP slow start in two sentences."}], ) for block in message.content: if block.type == "text": print(block.text) print(message.usage.input_tokens, message.usage.output_tokens) print(message._request_id) # log this with any failure report ``` content é uma lista de blocos (texto, raciocínio, uso de ferramentas), portanto verifique block.type em vez de ler content[0].text sem verificar. ## Receba respostas por streaming stream.pyCopiar ``` with client.messages.stream( model="claude-sonnet-5", max_tokens=16000, messages=[{"role": "user", "content": "Write a short story about a lighthouse."}], ) as stream: for text in stream.text_stream: print(text, end="", flush=True) final = stream.get_final_message() ``` Use streaming sempre que houver uma entrada longa, uma saída longa ou um valor alto de max_tokens: uma única requisição sem streaming precisa terminar dentro do tempo limite; com streaming, isso não é necessário. messages.create(..., stream=True) fornece o iterador de eventos bruto caso você não precise do auxiliar. ## Cliente assíncrono async_app.pyCopiar ``` import asyncio, anthropic client = anthropic.AsyncAnthropic(base_url="https://aiprimetech.io") limit = asyncio.Semaphore(3) # stay within your key's concurrency async def ask(question: str) -> str: async with limit: msg = await client.messages.create( model="claude-haiku-4-5", max_tokens=512, messages=[{"role": "user", "content": question}], ) return next(b.text for b in msg.content if b.type == "text") async def main(): answers = await asyncio.gather(*(ask(q) for q in ["What is DNS?", "What is BGP?"])) print(answers) asyncio.run(main()) ``` O semáforo é importante. Disparar centenas de requisições de uma vez com asyncio.gather é a causa mais comum dos erros de Concurrency limit exceeded que observamos em clientes Python. ## Tempos limite e novas tentativas Valores padrão: tempo limite de 10 minutos por requisição e 2 novas tentativas automáticas com espera exponencial. O SDK repete requisições em caso de erros de conexão, 408, 409, 429 e respostas 5xx. Como as requisições que excedem o tempo limite também são repetidas, o tempo total decorrido no pior caso é o tempo limite multiplicado pelo número de tentativas. app.pyCopiar ``` client = anthropic.Anthropic(base_url="https://aiprimetech.io", timeout=60.0, max_retries=4) # override for one call only client.with_options(timeout=300.0).messages.create( model="claude-opus-5-5", max_tokens=4000, messages=[{"role": "user", "content": "Review this design doc..."}], ) ``` ## Tratamento de erros | Status | Exceção | Tentar novamente? | 400 | anthropic.BadRequestError | Não: corrija a requisição | 401 | anthropic.AuthenticationError | Não: chave incorreta ou ausente | 403 | anthropic.PermissionDeniedError | Não | 404 | anthropic.NotFoundError | Não: ID do modelo ou URL | 429 | anthropic.RateLimitError | Sim, após uma pausa | 5xx, incluindo 529 por sobrecarga | anthropic.InternalServerError | Sim | Falha de rede | anthropic.APIConnectionError | Sim | Tempo limite excedido | anthropic.APITimeoutError | Sim, ou use streaming errors.pyCopiar ``` try: message = client.messages.create(model="claude-sonnet-5", max_tokens=1024, messages=[{"role": "user", "content": "Hi"}]) except anthropic.NotFoundError as e: print("Bad model ID or URL:", e.message) except anthropic.RateLimitError as e: print("Rate limited, retry after", e.response.headers.get("retry-after")) except anthropic.APIStatusError as e: print(e.status_code, e.type, e.message) except anthropic.APIConnectionError: print("Network problem") ``` Capture primeiro as classes específicas e APIStatusError por último; um único except genérico oculta a diferença entre erros que justificam uma nova tentativa e erros que exigem uma alteração no código. e.type fornece a string do tipo de erro da API, como rate_limit_error ou overloaded_error. ## IDs dos modelos | ID do modelo | Use para | claude-sonnet-5 | Padrão para programação e trabalho com agentes: rápido, eficiente e de preço intermediário. | claude-opus-5-5 | Raciocínio mais complexo, grandes refatorações e execuções longas de agentes. | claude-fable-5-1 | O mais capaz e mais caro; reserve-o para as tarefas mais difíceis. | claude-haiku-4-5 | Barato e rápido: títulos, resumos, classificação e pequenas etapas. client.models.list() retorna os modelos disponibilizados por um endpoint, para que você possa verificar um ID antes de usá-lo. Use os IDs exatamente como estão escritos: sem sufixos de data. ## Solução de problemas em um gateway | O que você vê | Causa | Correção | NotFoundError por 404 page not found | /v1 em base_url | Use a raiz do host | AuthenticationError | Chave não definida no processo ou colada com espaços em branco | Exiba len(os.environ["ANTHROPIC_API_KEY"]) | RateLimitError: Concurrency limit exceeded for user | Requisições demais em andamento | Um asyncio.Semaphore como acima | APITimeoutError em tarefas longas | Requisição sem streaming excedendo o tempo limite | Use streaming ou aumente timeout | InternalServerError: No available accounts | Capacidade temporária do serviço de origem | Deixe o SDK tentar novamente; aumente max_retries | Insufficient account balance | Saldo esgotado | [Adicionar créditos](/pt/topup/) Mais sobre erros do lado do modelo: o [guia de erros da API do Claude](/pt/learn/claude-api-errors-troubleshooting/). ## Perguntas frequentes Como instalo o SDK Python da Anthropic? pip install anthropic. A versão 1.x exige Python 3.10 ou mais recente. Como defino uma URL base personalizada no SDK Python da Anthropic? Passe base_url para anthropic.Anthropic() ou defina ANTHROPIC_BASE_URL. Use a raiz do host; o SDK acrescenta /v1/messages. Quais são o tempo limite e as novas tentativas padrão? 10 minutos por requisição e 2 novas tentativas com espera exponencial, abrangendo erros de conexão, 408, 409, 429 e 5xx. Como uso streaming com o SDK Python? Use with client.messages.stream(...) as stream: e itere sobre stream.text_stream; stream.get_final_message() retorna a mensagem completa. Comece a usar o Claude em minutos Obtenha uma chave de API — sem precisar de conta na Anthropic nem de lista de espera.[Obtenha sua chave de API](/register) AI Prime Tech é um gateway de API independente. Não tem afiliação com a Anthropic, não é endossado por ela e não é seu revendedor. Claude e os nomes dos modelos relacionados são marcas comerciais de seus respectivos proprietários. ## Mais guias da API do Claude [Como obter uma chave de API do Claude](/pt/learn/how-to-get-a-claude-api-key/)[Preços da API Claude explicados](/pt/learn/claude-api-pricing-explained/)[A maneira mais barata de usar a API do Claude](/pt/learn/cheapest-way-to-use-claude-api/)[Cursor ilimitado com a API do Claude](/learn/use-claude-api-with-cursor/)[Acesso ilimitado ao Claude Code](/pt/learn/use-claude-api-with-claude-code/)[Gateway da API do Claude vs. acesso direto à Anthropic](/pt/learn/claude-api-vs-anthropic-direct/)[Como usar Claude por meio de uma API compatível com OpenAI](/pt/learn/openai-compatible-claude-api/)[Modelos Claude explicados: uma comparação entre Claude Opus, Sonnet, Haiku e Fable — todos os modelos da API Claude, nomes e preços dos modelos Anthropic (2026)](/pt/learn/claude-api-models-compared/)[Pagamento da API do Claude com criptomoedas](/pt/learn/claude-api-with-crypto-payment/)[Acesso à API do Claude sem lista de espera](/pt/learn/claude-api-without-waitlist/)[Como reduzir o uso de tokens do Claude](/pt/learn/how-to-reduce-claude-token-usage/)[Cline ilimitado com a API do Claude](/pt/learn/use-claude-api-with-cline/)[Roo Code ilimitado com a API do Claude](/pt/learn/use-claude-api-with-roo-code/)[Claude ilimitado nas IDEs da JetBrains](/pt/learn/use-claude-api-with-jetbrains/)[Aider ilimitado com a API do Claude](/pt/learn/use-claude-api-with-aider/)[Claude ilimitado no VS Code](/pt/learn/use-claude-api-with-vscode/)[Configuração do OpenCode para Claude: configuração do opencode.json, modelos e erros comuns](/pt/learn/use-claude-api-with-opencode/)[Como executar um agente Hermes ilimitado no Claude](/pt/learn/run-hermes-agent-with-claude-api/)[Executando OpenClaw ilimitado com Claude](/pt/learn/run-openclaw-with-claude-api/)[O que significa uma API compatível com a Anthropic](/pt/learn/anthropic-compatible-api/)[Chave de API do Claude Code — ANTHROPIC_API_KEY: como obtê-la, configurá-la e quando usar claude setup-token em seu lugar](/pt/learn/claude-code-api-key-setup/)[Custos da API do Claude Code — Preços e como reduzi-los](/pt/learn/claude-code-api-costs/)[Erros da API Claude explicados: erro de servidor 500, sobrecarga 529, limite de requisições 429, requisição inválida 400 — e a correção para cada um](/pt/learn/claude-api-errors-troubleshooting/)[Como comprar créditos da API do Claude — e por que um crédito do Claude é melhor do que qualquer oferta de "comprar conta do Claude"](/pt/learn/buy-claude-api-credits/)[API Claude gratuita: existe uma chave de API Claude gratuita e o que realmente é gratuito em 2026?](/pt/learn/claude-api-free-trial/)[API do Claude vs assinatura Claude Pro/Max — Qual escolher](/pt/learn/claude-api-vs-subscription/)[Como executar a CLI do Codex no Claude](/pt/learn/use-claude-api-with-codex/)[Conectando Claude ao n8n](/pt/learn/use-claude-api-with-n8n/)[Roteando LiteLLM para Claude](/pt/learn/use-claude-api-with-litellm/)[Usando Claude no Kilo Code](/pt/learn/use-claude-api-with-kilo-code/)[Integre Claude ao GitHub Copilot](/pt/learn/use-claude-api-with-github-copilot/)[Conecte o Zed ao Claude por meio do gateway](/pt/learn/use-claude-api-with-zed/)[Conecte o Cherry Studio ao Claude](/pt/learn/use-claude-api-with-cherry-studio/)[ChatAnthropic no LangChain: importação, base_url, streaming, ferramentas e erros](/pt/learn/use-claude-api-with-langchain/)[Claude com o Vercel AI SDK: baseURL de createAnthropic, streaming e correções](/pt/learn/use-claude-api-with-vercel-ai-sdk/)[Execute o Factory Droid com o Claude](/pt/learn/use-claude-api-with-factory-droid/)[A API do Claude Code, explicada](/pt/learn/claude-code-api/)[Como integrar a API do Claude à sua aplicação](/pt/learn/claude-api-integration/)[Como obter uso ilimitado do Claude — e por que não existe "Claude Code crackeado"](/pt/learn/get-unlimited-claude-usage/)