DEV Community

Cover image for Cómo usar la API de Claude Fable 5.1 (Paso a paso con Apidog)
Roobia
Roobia

Posted on Originally published at apidog.com

Cómo usar la API de Claude Fable 5.1 (Paso a paso con Apidog)

Cómo usar Claude Fable 5.1 desde la API: esfuerzo, streaming, herramientas y caché

Claude Fable 5.1 se lanzó el 1 de septiembre de 2026. Su ID exacto en la API es claude-fable-5-1, sin sufijo de fecha. Mantiene el precio de Fable 5: $10 por millón de tokens de entrada y $50 por millón de tokens de salida. Las lecturas de caché cuestan $0.25 por millón de tokens.

Prueba Apidog hoy

Esta guía cubre el flujo completo:

  • Obtener una clave API.
  • Enviar una primera solicitud.
  • Controlar el esfuerzo y el costo.
  • Activar streaming.
  • Usar herramientas sin tool_choice forzado.
  • Gestionar rechazos y alternativas.
  • Mostrar actualizaciones de progreso.
  • Confirmar las lecturas de caché mediante usage.

Todas las solicitudes usan HTTP y JSON estándar, por lo que puedes construirlas y depurarlas en Apidog antes de integrarlas en tu aplicación.

Si migras un servicio existente basado en Fable 5 u Opus 5, consulta también la guía de migración completa. Para una introducción al modelo, empieza por qué es Claude Fable 5.1.

Claude Fable 5.1

Antes de tu primera llamada: tres errores que devuelven 400

1. El pensamiento no se puede desactivar

Fable 5.1 usa pensamiento adaptativo en todas las solicitudes. Omite el campo thinking o envía:

{"type": "adaptive"}
Enter fullscreen mode Exit fullscreen mode

Estas configuraciones devuelven 400:

{"type": "disabled"}
Enter fullscreen mode Exit fullscreen mode 
{"type": "enabled", "budget_tokens": 10000}
Enter fullscreen mode Exit fullscreen mode

Si vienes de Opus 5, donde disabled era válido con un esfuerzo high o inferior, elimina ese campo y controla el gasto con output_config.effort.

2. El uso forzado de herramientas ya no está disponible

Estas opciones devuelven un error:

{"type": "any"}
Enter fullscreen mode Exit fullscreen mode 
{"type": "tool", "name": "..."}
Enter fullscreen mode Exit fullscreen mode

El mensaje es:

tool_choice: type "tool" and "any" are not supported for this model
Enter fullscreen mode Exit fullscreen mode

Más adelante se muestra cómo garantizar una llamada sin forzar tool_choice.

3. La retención de datos debe ser de 30 días

Fable 5.1 es un Modelo Cubierto. Las organizaciones o espacios de trabajo con retención de datos cero reciben un 400 invalid_request_error, incluso si el cuerpo de la solicitud es válido.

Si la primera llamada falla sin una explicación clara, verifica primero la configuración de retención.

Consulta la documentación de Novedades en Claude Fable 5.1 para conocer estos cambios.

Paso 1: Obtener una clave API

Inicia sesión en la Consola de Claude, abre las claves API en la configuración de tu organización y crea una clave. Cópiala inmediatamente: no podrás volver a verla.

Guárdala como una variable de entorno:

export ANTHROPIC_API_KEY="sk-ant-..."
Enter fullscreen mode Exit fullscreen mode

En Apidog, crea una variable de entorno llamada ANTHROPIC_API_KEY y úsala en el encabezado como {{ANTHROPIC_API_KEY}}. Así evitarás que la clave se guarde dentro del cuerpo de una solicitud.

Paso 2: Enviar tu primera solicitud

Crea una solicitud POST a https://api.anthropic.com/v1/messages con estos encabezados:

  • x-api-key
  • anthropic-version: 2023-06-01
  • content-type: application/json 
curl https://api.anthropic.com/v1/messages \
  -H "x-[REDACTED CREDENTIAL] \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-fable-5-1",
    "max_tokens": 16000,
    "messages": [
      {"role": "user", "content": "Explain the difference between idempotent and safe HTTP methods, with one example each."}
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

La misma solicitud con el SDK oficial de Python:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Explain the difference between idempotent and safe HTTP methods, with one example each."}],
)

if response.stop_reason == "refusal":
    print("declined:", response.stop_details.category if response.stop_details else None)
else:
    for block in response.content:
        if block.type == "text":
            print(block.text)
Enter fullscreen mode Exit fullscreen mode

Desarrolla estos dos hábitos desde el principio:

  1. Comprueba stop_reason antes de leer content. Un rechazo del clasificador se devuelve como HTTP 200, pero con una matriz de contenido vacía.
  2. Da a max_tokens un margen suficiente. El límite incluye los tokens de pensamiento y los tokens de respuesta. Como el pensamiento siempre está activo, un valor ajustado para un modelo sin pensamiento puede truncar la respuesta en Fable 5.1.

La respuesta contiene un bloque thinking cuyo texto está vacío con la configuración predeterminada display: "omitted". Es normal. Cuando envíes el turno siguiente, conserva ese bloque sin modificaciones.

Paso 3: Controlar costo y profundidad con effort

output_config.effort es la principal palanca de Fable 5.1. Se encuentra dentro de output_config, no en el nivel superior, y acepta:

  • low
  • medium
  • high
  • xhigh
  • max

El valor predeterminado es high.

{
  "model": "claude-fable-5-1",
  "max_tokens": 16000,
  "output_config": {"effort": "medium"},
  "messages": [{"role": "user", "content": "Summarize this changelog in five bullets."}]
}
Enter fullscreen mode Exit fullscreen mode

La guía del parámetro de esfuerzo recomienda empezar en high, evaluar los demás niveles con tus propios casos de prueba y repetir las pruebas aunque ya las hayas ejecutado con Fable 5. Los nombres de nivel no representan necesariamente la misma cantidad de pensamiento entre modelos.

Anthropic indica que:

  • medium puede aproximarse a Fable 5 con menor costo.
  • low suele ser competitivo con Opus y Sonnet en costo por tarea.
  • Con low, Fable 5.1 usa las herramientas de búsqueda y recuperación con menor frecuencia y responde más desde la memoria.
  • Con xhigh y max, puede redactar un entregable extenso durante la fase de pensamiento y volver a escribirlo después. Configura max_tokens para cubrir ambas fases.

Consulta también la guía del parámetro de esfuerzo para Opus 5, cuya semántica de cinco niveles también se aplica aquí.

Cambiar el esfuerzo a mitad de una conversación

Esta función beta permite cambiar el esfuerzo sin invalidar el prefijo de caché. En lugar de modificar el nivel superior entre solicitudes, envía un mensaje system vacío con output_config. El nuevo esfuerzo se aplica desde el siguiente turno del usuario.

Requiere:

  • El encabezado beta mid-conversation-output-config-2026-07-01.
  • El espacio de nombres client.beta.messages. 
response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    output_config={"effort": "high"},
    betas=["mid-conversation-output-config-2026-07-01"],
    messages=[
        {"role": "user", "content": "Plan a migration from SQLite to PostgreSQL in three short steps."},
        {"role": "assistant", "content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."},
        {"role": "system", "content": [], "output_config": {"effort": "low"}},
        {"role": "user", "content": "Summarize the plan in one sentence."},
    ],
)
Enter fullscreen mode Exit fullscreen mode

Reducir el esfuerzo de esta forma es fiable. Para aumentarlo, los saltos grandes —por ejemplo, de low a xhigh— suelen funcionar mejor.

Paso 4: Transmitir respuestas largas

Con un esfuerzo alto, las tareas difíciles pueden tardar varios minutos. Usa streaming siempre que la respuesta pueda ser extensa. El SDK requiere streaming para valores de max_tokens cercanos al límite de 128.000, con el fin de evitar tiempos de espera HTTP.

with client.messages.stream(
    model="claude-fable-5-1",
    max_tokens=64000,
    messages=[{"role": "user", "content": "Write a test plan for a rate-limited public API."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final = stream.get_final_message()

print(final.stop_reason, final.usage.output_tokens)
Enter fullscreen mode Exit fullscreen mode

En Apidog, las respuestas de streaming se renderizan a medida que llegan. Esto permite medir rápidamente cuánto tarda un turno con esfuerzo high antes de producir el primer token de texto.

Paso 5: Añadir herramientas sin forzarlas

La definición de herramientas es la misma que en Fable 5. Lo que cambia es cómo se solicita una llamada.

En Fable 5 podías usar:

{"type": "tool", "...": "..."}
Enter fullscreen mode Exit fullscreen mode

En Fable 5.1, una llamada forzada puede omitir el pensamiento y hacer que el modelo escriba su razonamiento dentro de los argumentos. Por eso devuelve 400.

Usa este patrón:

  1. Mantén tool_choice en auto.
  2. Nombra explícitamente la herramienta en la instrucción.
  3. Establece strict: true.
  4. Usa additionalProperties: false en el esquema. 
record_summary_tool = {
    "name": "record_summary",
    "description": "Record the structured summary of the document.",
    "strict": True,
    "input_schema": {
        "type": "object",
        "properties": {"summary": {"type": "string"}},
        "required": ["summary"],
        "additionalProperties": False,
    },
}

response = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    tools=[record_summary_tool],
    tool_choice={"type": "auto"},
    messages=[{"role": "user", "content": "Summarize: The meeting moved to Thursday. Call the record_summary tool with your result."}],
)
Enter fullscreen mode Exit fullscreen mode

Si solo querías obtener JSON, usa salidas estructuradas mediante output_config.format en lugar de una herramienta.

Si tu aplicación necesita una llamada concreta en el turno actual de una conversación de varios turnos, añade un mensaje system después del último turno del usuario. El mensaje debe nombrar la herramienta y declarar que la llamada es obligatoria. Conserva ese mensaje en el historial.

tool_choice: {"type": "none"} sigue funcionando cuando un turno no debe llamar a herramientas.

Bucle del agente

El bucle no cambia:

  1. Comprueba si stop_reason == "tool_use".
  2. Ejecuta cada bloque tool_use.
  3. Devuelve todos los bloques tool_result en un mensaje de usuario.
  4. Adjunta el turno del asistente exactamente como fue devuelto, incluidos los bloques de pensamiento.

Este último paso es especialmente importante en Fable 5.1. Consulta la guía de pensamiento preservado.

En bucles largos, Fable 5.1 puede emitir una llamada por turno cuando las siguientes lecturas independientes solo están implícitas en la tarea. Anthropic recomienda añadir después de cada resultado de herramienta esta instrucción:

Primero, enumere en privado lo que necesita a continuación; luego solicite cada elemento que no dependa del resultado de otro en esta única respuesta.

Envíala como un mensaje system con alcance de turno (clear_at: "next_user_message"). Requiere el encabezado beta mid-conversation-system-clear-at-2026-08-21. Conserva todas las copias anteriores del mensaje.

Paso 6: Gestionar rechazos con alternativas

Fable 5.1 ejecuta clasificadores de seguridad. Una solicitud rechazada devuelve HTTP 200 con:

  • stop_reason: "refusal"
  • Un objeto stop_details.
  • Una categoría entre cyber, bio, frontier_llm, reasoning_extraction y general_harms.

Un rechazo que ocurre antes de cualquier salida no se factura.

Alternativa del lado del servidor

La opción más sencilla es fallbacks: "default" con el encabezado beta server-side-fallback-2026-07-01. Anthropic reintentará la solicitud usando el modelo recomendado para la categoría.

Para Fable 5.1, los objetivos permitidos son:

  • claude-opus-4-8
  • claude-opus-5 
response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    fallbacks="default",
    betas=["server-side-fallback-2026-07-01"],
    messages=[{"role": "user", "content": "Audit this authentication middleware for logic bugs."}],
)

fallback_ran = any(
    entry.type == "fallback_message" for entry in (response.usage.iterations or [])
)
if fallback_ran and response.stop_reason != "refusal":
    print("served by", response.model)
Enter fullscreen mode Exit fullscreen mode

El campo model de nivel superior identifica el modelo que sirvió la respuesta. Un bloque de contenido fallback marca la transferencia. Conserva ese bloque en la misma posición cuando vuelvas a mostrar el turno.

fallbacks:

  • No está disponible en la API de Batches.
  • No está disponible en Bedrock, Google Cloud ni Foundry.
  • En esos entornos debes registrar BetaRefusalFallbackMiddleware del SDK en el cliente.

Consulta la guía de manejo de rechazos para conocer la facturación, el enrutamiento persistente y el reintento manual con crédito de fallback.

Paso 7: Mostrar actualizaciones de progreso

Entre llamadas a herramientas, Fable 5.1 puede escribir notas breves sobre lo que encontró y lo que hará después. Cada nota llega como un bloque thinking independiente inmediatamente antes de la llamada.

Por defecto, estos bloques están vacíos. Usa display: "updates" con el encabezado beta thinking-display-updates-2026-08-18:

{
  "model": "claude-fable-5-1",
  "max_tokens": 16000,
  "thinking": {"type": "adaptive", "display": "updates"},
  "tools": [...],
  "messages": [{"role": "user", "content": "Review the PRs open against our billing service."}]
}
Enter fullscreen mode Exit fullscreen mode

Los bloques thinking con texto no vacío son líneas de estado que puedes mostrar en la interfaz. Fable 5.1 produce menos actualizaciones que Fable 5. Si tu UI depende de esta narración, elimina también cualquier instrucción del prompt que pida al modelo reservar los hallazgos para la respuesta final.

Paso 8: Confirmar la tarifa de caché de $0.25

La caché de prompts es donde se aplica el principal cambio de precio. Marca el prefijo estable con cache_control y revisa el objeto usage:

response = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    system=[{"type": "text", "text": LONG_STABLE_SYSTEM_PROMPT, "cache_control": {"type": "ephemeral"}}],
    messages=[{"role": "user", "content": "Which endpoints in the spec lack an error schema?"}],
)
u = response.usage
print(u.input_tokens, u.cache_creation_input_tokens, u.cache_read_input_tokens)
Enter fullscreen mode Exit fullscreen mode

En el primer envío, cache_creation_input_tokens no será cero. Con un TTL de cinco minutos, esos tokens se facturan a $12.50 por millón.

En una segunda solicitud dentro de esos cinco minutos:

u.cache_read_input_tokens
Enter fullscreen mode Exit fullscreen mode

debería ser mayor que cero. Esos tokens se facturan a $0.25 por millón en Fable 5.1.

Si permanece en cero en solicitudes aparentemente idénticas, el prefijo cambia entre llamadas. Revisa especialmente:

  • Marcas de tiempo en el prompt del sistema.
  • JSON sin ordenar.
  • Matrices de herramientas variables.

El prompt mínimo que se puede almacenar en caché es de 512 tokens.

Dos detalles específicos de Fable 5.1:

  • Un fallo de caché cuesta 40 veces más que un acierto, así que mantener la caché activa es más importante que en Fable 5.
  • El esfuerzo por mensaje y los mensajes system con alcance de turno permiten cambiar partes de la sesión sin reiniciar el prefijo.

Las mismas ediciones que reinician la caché —reconstruir system o editar turnos anteriores— también invalidan los bloques de pensamiento. En Fable 5.1, la estrategia de solo añadir contenido ofrece ambas ventajas.

Consulta la documentación de almacenamiento en caché de prompts.

Probar y depurar el flujo en Apidog

Guarda cada etapa como una solicitud dentro de una colección de Apidog:

  • Primera llamada.
  • Variantes de effort.
  • Streaming.
  • Bucle de herramientas.
  • Fallback.
  • Verificación de caché.

Usa variables de entorno para la clave y el modelo. Así puedes cambiar toda la colección entre claude-fable-5 y `claude-fable-5-1 editando una sola variable.

Añade estas aserciones:

text
stop_reason != "refusal"

En la segunda solicitud de caché:

text
usage.cache_read_input_tokens > 0

Cuando uses el encabezado thinking-binding, verifica que ninguna entrada de input_transformations tenga:

text
reason: "prefix_binding_mismatch"

Ejecuta la colección antes y después de cada cambio en el harness. Puedes descargar Apidog para configurarla; la misma colección puede utilizarse como verificación de CI mediante la CLI de Apidog.

Errores y trampas frecuentes

  • 400 tool_choice: type "tool" and "any" are not supported for this model

    Cambia a auto, nombra la herramienta en la instrucción y usa strict: true.

  • 400 con thinking: {"type": "disabled"}

    Elimina el campo y reduce el esfuerzo mediante output_config.effort.

  • 400 invalid_request_error con un cuerpo aparentemente válido

    Comprueba que la organización o el espacio de trabajo tenga una retención de datos de 30 días.

  • 400 Invalid signature in thinking block. The block is bound to a different conversation.

    El código modificó un turno anterior, el prompt del sistema o la matriz de herramientas. Revisa la guía de pensamiento preservado.

  • El texto de pensamiento está vacío

    Es normal con display: "omitted". Usa summarized o updates si necesitas mostrarlo.

  • Las lecturas de caché son cero

    El prefijo probablemente es variable. Revisa marcas de tiempo y objetos sin ordenar.

  • Falla la validación de Priority Tier

    Fable 5.1 no admite el nivel de prioridad; Fable 5 sí.

Preguntas frecuentes

¿Cuál es el ID del modelo de Claude Fable 5.1?

En la API de Claude es:

text
claude-fable-5-1

En Amazon Bedrock:

text
anthropic.claude-fable-5-1

Google Cloud, Microsoft Foundry y Claude Platform en AWS usan claude-fable-5-1.

¿Necesito un encabezado beta?

No para el modelo base, el pensamiento adaptativo, el esfuerzo, las herramientas ni la caché. Todas estas funciones usan el encabezado estándar:

text
anthropic-version: 2023-06-01

Los encabezados beta solo son necesarios para:

  • Cambiar el esfuerzo por mensaje.
  • Usar mensajes system con alcance de turno.
  • Mostrar actualizaciones de progreso.
  • Usar fallbacks del lado del servidor.
  • Controlar el enlace de pensamiento.

¿Puedo forzar una llamada a una herramienta?

No. tool_choice con any o tool devuelve 400.

Usa auto, menciona la herramienta en el prompt y establece strict: true para validar los argumentos. Si necesitas extraer JSON, considera salidas estructuradas.

¿Cuál es la salida máxima?

La API de Messages admite hasta 128.000 tokens. Usa streaming para respuestas grandes.

La beta de la API de Batch, con 300.000 tokens, no está listada para Fable 5.1.

¿Cómo compruebo las lecturas de caché más baratas?

Repite una solicitud con el mismo prefijo y revisa:

python
response.usage.cache_read_input_tokens

En Fable 5.1, esos tokens cuestan $0.25 por millón, frente a $1 en Fable 5 y $0.50 en Opus 5. Consulta el desglose de precios.

¿Sigue siendo válida la guía de la API de Fable 5?

En su mayor parte. El endpoint es el mismo, pero los ejemplos de uso forzado de herramientas ahora devuelven 400 y la guía anterior no cubre el esfuerzo por mensaje ni las actualizaciones de progreso.

Consulta la guía de la API de Fable 5 junto con la documentación actual de Claude.

Top comments (0)