Encabezados beta

Los encabezados beta te permiten acceder a funciones experimentales y nuevas capacidades de los modelos antes de que formen parte de la API estándar.



Cómo usar los encabezados beta

Para acceder a las funciones beta, incluye el encabezado anthropic-beta en tus solicitudes a la API:

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

La documentación de cada función indica el nombre beta exacto que debes enviar. La descripción general de la API enumera las APIs que actualmente están en beta.

Los siguientes ejemplos muestran la misma solicitud con cURL, la CLI ant y los SDKs. Los SDKs reciben los nombres beta en el parámetro betas y envían el encabezado anthropic-beta por ti:

client = Anthropic()

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

print(response.content)



Múltiples funciones beta

Para usar múltiples funciones beta en una sola solicitud, incluye todos los nombres de las funciones en el encabezado separados por comas:

anthropic-beta: feature1,feature2,feature3

Cuando uses un SDK, enumera cada función en el parámetro betas (por ejemplo, betas=["feature1", "feature2"]). Con la CLI, pasa una sola bandera --beta con los nombres de las funciones separados por comas (por ejemplo, --beta feature1,feature2). Evita repetir la bandera: actualmente solo el valor de la primera bandera tiene efecto.



Encabezados específicos por endpoint

Algunas APIs beta están limitadas a endpoints específicos y requieren un encabezado beta específico de la función en cada solicitud:

Los espacios de nombres beta de los SDKs agregan estos encabezados automáticamente. Agrégalos tú mismo solo cuando hagas solicitudes HTTP sin procesar. Consulta la descripción general de Managed Agents, Uso de la memoria del agente y la referencia de túneles MCP para más detalles.

Los encabezados específicos por endpoint que se aplican al mismo endpoint no siempre son combinables. En los endpoints de almacenes de memoria, agent-memory-2026-07-22 reemplaza a managed-agents-2026-04-01: enviar ambos en la misma solicitud devuelve un error 400. Los SDKs de cliente envían el encabezado correcto para cada endpoint automáticamente.



Convenciones de nomenclatura de versiones

Los nombres de las funciones beta normalmente siguen el patrón feature-name-YYYY-MM-DD, donde la fecha indica cuándo se lanzó la beta. Usa siempre el nombre exacto de la función beta tal como está documentado.



Manejo de errores

Si usas un nombre beta inválido, o una beta a la que tu organización no tiene acceso, recibirás una respuesta de error 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"
}



Obtener ayuda

Para actualizaciones sobre las funciones beta, consulta las notas de la versión. Para obtener ayuda con problemas en producción, contacta a soporte.



Próximos pasos