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 informa o nome beta exato 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. Os SDKs recebem os nomes beta no parâmetro betas e enviam o cabeçalho anthropic-beta por você:

client = Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    betas=["files-api-2025-04-14"],
)

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

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). Evite repetir a flag: atualmente apenas o valor da primeira flag tem efeito.



Cabeçalhos específicos por endpoint

Algumas APIs beta são restritas 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 de Managed Agents e a referência de túneis MCP para mais detalhes.



Convenções de nomenclatura de versões

Os nomes dos 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 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 lançamento. Para ajuda com problemas em produção, entre em contato com o suporte.



Próximos passos