Cabeçalhos beta

Os "beta headers" (cabeçalhos beta) permitem que você acesse recursos experimentais e novas capacidades de modelos antes que eles se tornem parte da API padrão.

Como usar cabeçalhos beta

Para acessar recursos beta, inclua o cabeçalho anthropic-beta em suas requisições à API:

POST /v1/messages
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
anthropic-beta: BETA_FEATURE_NAME
content-type: application/json

A documentação de cada recurso indica o nome exato do beta a ser enviado. A visão geral da API lista as APIs atualmente em beta.

Os exemplos a seguir mostram a mesma requisição com cURL, a CLI ant e o SDK, usando o beta de edição de contexto como exemplo. O SDK recebe nomes beta por meio de betas e envia o cabeçalho anthropic-beta para você:

client = Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    betas=["context-management-2025-06-27"],
)

print(response.content)

Múltiplos recursos beta

Para usar múltiplos recursos beta em uma única requisição, inclua todos os nomes dos recursos no cabeçalho separados por vírgulas:

anthropic-beta: feature1,feature2,feature3

Você também pode enviar o cabeçalho anthropic-beta mais de uma vez na mesma requisição. A Claude API lê todos os cabeçalhos anthropic-beta, então o seguinte é equivalente ao exemplo anterior:

anthropic-beta: feature1
anthropic-beta: feature2
anthropic-beta: feature3

Com o SDK, liste cada recurso (por exemplo, betas=["feature1", "feature2"]). Com a CLI, passe uma única flag --beta com os nomes dos recursos separados por vírgulas (por exemplo, --beta feature1,feature2). Você também pode repetir a flag (por exemplo, --beta feature1 --beta feature2).

Recursos beta em outras plataformas

Os nomes beta são os mesmos em todas as plataformas que os aceitam, mas nem todas as plataformas aceitam todos os betas. Claude Platform on AWS, Microsoft Foundry e Google Cloud recebem nomes beta no cabeçalho anthropic-beta, assim como a Claude API. Para enviar vários betas, coloque seus nomes em um único cabeçalho, separados por vírgulas: o Google Cloud lê apenas um cabeçalho anthropic-beta e ignora os demais, então os betas nos outros cabeçalhos não têm efeito.

No Amazon Bedrock, onde os nomes beta são colocados depende da API que você chama:

• Claude no Amazon Bedrock (endpoints bedrock-mantle) os recebe no cabeçalho anthropic-beta.
• A API InvokeModel os lê do corpo da requisição, não de um cabeçalho. Liste-os no array anthropic_beta do corpo, um nome por elemento, por exemplo "anthropic_beta": ["feature1", "feature2"].

Cabeçalhos específicos de endpoint

Algumas APIs beta têm escopo restrito a endpoints específicos e exigem um cabeçalho beta específico do recurso em cada requisição:

O namespace client.beta do SDK adiciona esses cabeçalhos automaticamente. Adicione-os você mesmo apenas ao fazer requisições HTTP diretas. Consulte a visão geral do Managed Agents, Usando a memória do agente e a referência de túneis MCP para mais detalhes.

Cabeçalhos específicos de endpoint que se aplicam ao mesmo endpoint nem sempre podem ser combinados. Nos endpoints de memory store, agent-memory-2026-07-22 substitui managed-agents-2026-04-01: enviar ambos na mesma requisição retorna um erro 400. O SDK envia o cabeçalho correto para cada endpoint automaticamente.

Convenções de nomenclatura de versões

Os nomes de recursos beta normalmente seguem o padrão feature-name-YYYY-MM-DD, onde a data indica quando o beta foi lançado. Sempre use o nome exato do recurso beta conforme documentado.

Tratamento de erros

Se você usar um nome de beta inválido, ou um beta ao qual sua organização não tem acesso, você receberá uma resposta de erro 400:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Unexpected value(s) `invalid-beta-name` for the `anthropic-beta` header. Please consult our documentation at platform.claude.com/docs or try again without the header."
  },
  "request_id": "req_011CcnGfC9fELffo2EALu4Wd"
}

Obtendo ajuda

Para atualizações sobre recursos beta, consulte as notas de versão. Para ajuda com problemas em produção, entre em contato com o suporte.

Próximos passos