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 os SDKs, usando o beta de edição de contexto como exemplo. Os SDKs recebem os nomes dos betas no parâmetro betas e enviam 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

Ao usar um SDK, liste cada recurso no parâmetro betas (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).

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:

Os namespaces beta dos SDKs adicionam esses cabeçalhos automaticamente. Adicione-os você mesmo apenas ao fazer requisições HTTP diretas. Consulte a visão geral do Managed Agents, Usando memória de 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. Os SDKs cliente enviam 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