Referência da APIUsando a API

Visão geral da API

Copy page



Entenda os endpoints disponíveis da Claude API, cabeçalhos de autenticação, SDKs de cliente, paginação, limites de taxa e opções de acesso a plataformas de nuvem.

A Claude API é uma API RESTful em https://api.anthropic.com que fornece acesso programático aos modelos Claude e aos Claude Managed Agents.

Pré-requisitos

Para usar a Claude API, você precisa de:

• Uma conta do Claude Console
• Uma chave de API do Console, ou uma regra de Workload Identity Federation configurada

Para instruções de configuração passo a passo, consulte Comece a usar o Claude.

APIs disponíveis

A Claude API inclui as seguintes APIs:

• Messages APIPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar.: Envie mensagens ao Claude para interações conversacionais (POST /v1/messages)
• Message Batches APIPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar.: Processe grandes volumes de requisições de Messages de forma assíncrona com uma redução de custo de 50 por cento (POST /v1/messages/batches)
• Token Counting APIPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar.: Conte os tokens de uma mensagem antes de enviá-la para gerenciar custos e limites de taxa (POST /v1/messages/count_tokens)
• Models APIPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar.: Liste os modelos Claude disponíveis e seus detalhes (GET /v1/models)
• Files APIPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar.: Faça upload e gerencie arquivos para uso em várias chamadas de API (POST /v1/files, GET /v1/files)
• Skills APIPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar.: Crie e gerencie habilidades de agente personalizadas (POST /v1/skills, GET /v1/skills)

As seguintes APIs estão em beta:

• Agents API: Defina configurações de agente reutilizáveis e versionadas para o Claude Managed Agents (POST /v1/agents, GET /v1/agents)
• Sessions API: Execute sessões de agente com estado em sandboxes gerenciados na nuvem (POST /v1/sessions, GET /v1/sessions/{id}/events/stream)
• Environments API: Configure templates de sandbox para sessões de agente (POST /v1/environments, GET /v1/environments)

Para a referência completa da API com todos os endpoints, parâmetros e esquemas de resposta, explore as páginas de referência da API listadas na navegação. Para acessar recursos beta, consulte Cabeçalhos beta.

Autenticação

Para detalhes sobre cada método de autenticação e quando usá-lo, consulte Autenticação. As requisições à Claude API incluem estes cabeçalhos:

Se você estiver usando os SDKs de cliente, o SDK envia os cabeçalhos de autenticação, versão e content-type automaticamente; você passa anthropic-workspace-id por conta própria quando sua chave precisa dele. Para detalhes sobre versionamento da API, consulte Versões da API.

Ao acessar o Claude através de uma plataforma de nuvem, a autenticação é integrada ao sistema IAM do provedor de nuvem. Consulte a documentação específica da plataforma para tipos de credenciais suportados, cabeçalhos obrigatórios e opções de autenticação.

Obtendo chaves de API

A API é disponibilizada por meio do Console web. No Console, você pode usar o Playground (platform.claude.com/playground) para experimentar a API no navegador e depois gerar chaves de API na página Chaves de API (platform.claude.com/settings/keys). Para saber como, consulte Obtenha sua chave de API do Claude. Você escolhe o tipo de cada chave (consulte Tipos de chave) e sua expiração ao criá-la. Use workspaces no Console para separar ambientes e controlar gastos por caso de uso.

SDKs de cliente

A Anthropic fornece SDKs oficiais que simplificam a integração com a API ao lidar com autenticação, formatação de requisições, tratamento de erros e muito mais.

Benefícios:

• Gerenciamento automático de cabeçalhos (autenticação, anthropic-version, content-type)
• Tratamento de requisições e respostas com segurança de tipos
• Lógica de nova tentativa e tratamento de erros integrados
• Suporte a streaming
• Timeouts de requisição e gerenciamento de conexão

Para uma lista de SDKs de cliente, consulte SDKs, CLI e bibliotecas.

Claude API versus plataformas de nuvem

O Claude está disponível através da Claude API primária e através de plataformas de nuvem. Escolha com base em sua infraestrutura, disponibilidade de recursos, requisitos de conformidade e preferências de preço.

Claude API

• Acesso direto aos modelos e recursos mais recentes
• Cobrança e suporte da Anthropic
• Melhor para: Novas integrações, acesso completo a recursos, relacionamento direto com a Anthropic

APIs de plataformas de nuvem

Acesse o Claude através de AWS, Google Cloud ou Microsoft Azure:

• Integrado com a cobrança e o IAM do provedor de nuvem
• A disponibilidade de recursos varia por plataforma: As plataformas operadas pela Anthropic incluem Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) e Microsoft Foundry; as plataformas operadas por parceiros incluem Claude Models on Google Cloud (Google managed) e Amazon Bedrock. Consulte a página de cada plataforma para disponibilidade de recursos e prazos.
• Melhor para: Compromissos de nuvem existentes, requisitos específicos de conformidade, cobrança de nuvem consolidada

Formato de requisição e resposta

Limites de tamanho de requisição

A Claude API primária impõe estes limites de tamanho de requisição:

Se você exceder esses limites, receberá um erro 413 request_too_large.

Cabeçalhos de resposta

A Claude API inclui os seguintes cabeçalhos em suas respostas:

Para os cabeçalhos de limite de taxa, consulte Cabeçalhos de resposta em Limites de taxa. Para exemplos que leem um cabeçalho de resposta pelo nome com cada SDK, consulte Identificar o workspace por trás de uma resposta da API.

Paginação

Os endpoints de listagem retornam resultados em páginas. A maioria dos endpoints de listagem mais recentes usa o esquema de cursor page e next_page descrito nesta seção. Alguns usam um esquema diferente; consulte a nota no final desta seção. Use o parâmetro de consulta limit para controlar o tamanho da página e o parâmetro de consulta page para buscar uma página adjacente. Cada resposta inclui um array data junto com campos de cursor para navegar entre páginas.

Para voltar uma página, passe prev_page como o parâmetro page. prev_page é null quando você está na primeira página. Nem todos os endpoints de listagem suportam prev_page. Apenas GET /v1/sessions retorna prev_page; em endpoints de listagem que não suportam paginação para trás, o campo está ausente da resposta em vez de ser null. Para um passo a passo de requisição, consulte Listando sessões.

O SDK fornece um iterador com paginação automática que segue next_page para você. Por exemplo, for session in client.beta.sessions.list() percorre todas as sessões. A paginação automática do SDK funciona apenas para frente; para voltar uma página, leia prev_page da resposta e passe-o você mesmo de volta como o parâmetro page. Consulte SDKs, CLI e bibliotecas para mais detalhes.

Limites de taxa e disponibilidade

Limites de taxa

A API impõe limites de taxa e limites de gasto para prevenir uso indevido e gerenciar capacidade. Os limites são organizados em níveis de uso; sua organização é colocada em um nível automaticamente e pode passar para um nível mais alto ao longo do tempo. Cada nível tem:

• Limites de gastos: Custo mensal máximo para uso da API
• Limites de taxa: Número máximo de requisições por minuto (RPM) e tokens por minuto (TPM)

Você pode visualizar seus limites de taxa em Limites de taxa no Claude Console. Seus limites de gastos estão em Limites de gastos no Claude Console (platform.claude.com/settings/spend-limits). Para limites de taxa mais altos ou um teto de gastos mensal maior, use Solicitar aumento de nível na página Limites de taxa.

Para informações detalhadas sobre limites, níveis e o algoritmo de token bucket usado para limitação de taxa, consulte Limites de taxa.

Disponibilidade

A Claude API está disponível em muitos países e regiões em todo o mundo. Verifique a página de regiões suportadas para confirmar a disponibilidade em sua localização.

Próximos passos