# Guía de Claude Message Threads API

> La API de hilos de Claude: el encabezado beta, las peticiones create y continue, los campos que debes reenviar, la caducidad y qué hacer tras un 404.

- Canonical HTML: https://omniakey.com/es/blog/claude-message-threads-api-guide
- Markdown: https://omniakey.com/es/blog/claude-message-threads-api-guide.md
- Published: 2026-11-04 (updated 2026-11-04)
- Author: Kiki, COO at OmniaKey
- Language: es
- Category: API setup
- Reading time: 9 min
- All posts: https://omniakey.com/blog/llms.txt

---

La API de message threads de Claude permite enviar una conversación larga una sola vez y, en cada turno posterior, mandar solo los mensajes nuevos (página Message threads de Anthropic, 4 de noviembre de 2026). Añade `"thread": {"type": "create"}` a la primera petición de Messages y el encabezado beta `message-threads-2026-08-12`: la API guarda la conversación en memoria y la siguiente petición sube menos contenido.

Es una beta en todos los modelos. Pueden usarla 17 ID de modelo, entre ellos [Claude Opus 5.5](https://omniakey.com/es/claude-opus-5-5), que es el que llama el código de abajo. El encabezado beta va en cada petición de un hilo.

## Qué ahorra un hilo

Sin hilo, cada turno lleva la transcripción completa: el system prompt, las definiciones de herramientas, todos los mensajes anteriores y todos los resultados de herramientas. Un hilo guarda esa conversación, incluida la respuesta de Claude, bajo el `id` de la respuesta, y una petición continue envía solo lo ocurrido desde entonces (página Message threads, 4 de noviembre de 2026). Cada turno sube menos.

La caché de prompts ayuda a la misma conversación por otro lado. Un acierto de caché abarata la entrada repetida: en Opus 5.5, 0,20 USD por millón de tokens frente a 4 USD de entrada nueva (página de precios de Anthropic, 4 de noviembre de 2026). Aun así, la petición sigue llevando esa entrada. El hilo reduce lo que envías; la caché reduce el precio de lo que se repite. En sesiones largas conviene usar las dos cosas, y [reducir el consumo de tokens de Claude Code](https://omniakey.com/es/blog/reduce-claude-code-token-usage) cubre la parte del contexto.

Los hilos no cambian el precio ni los límites de velocidad (página Message threads, 4 de noviembre de 2026). Las tarifas actuales están en [precios](https://omniakey.com/es/pricing).

La caché la pones tú. Envía un `cache_control` de nivel superior en cada petición y la API lo aplica al último bloque cacheable de los `messages` de esa petición. El límite de cuatro puntos de interrupción es una regla de la caché de prompts de toda la plataforma, y la caché automática usa uno de los cuatro (página de caché de prompts de Anthropic, 4 de noviembre de 2026). Reparte así:

1. el `cache_control` de nivel superior, un punto en cada petición del hilo;
2. uno en `system`, enviado con la petición create;
3. uno en `tools`, también en create;
4. uno en el mensaje más reciente.

Los puntos de interrupción de mensajes guardados antes quedan fuera de ese límite, porque una petición continue solo envía mensajes nuevos. Una vez enviado, el punto se queda donde está. Al reenviar una conversación, quita los puntos de los mensajes anteriores y deja uno en el último bloque (página Message threads, 4 de noviembre de 2026).

## Crea el primer turno y sigue

Tres pasos:

1. Pon tu clave de Anthropic en `ANTHROPIC_API_KEY`.
2. Envía la conversación completa, con `system` y `tools` si los usas, más `"thread": {"type": "create"}`.
3. Envía solo los mensajes posteriores a la última respuesta, más `"thread": {"type": "continue", "previous_message_id": "<previous id>"}`, y deja fuera `system` y `tools`.

Cada petición lleva el encabezado beta y `anthropic-version: 2026-10-21`, la versión actual (página de versiones de Anthropic, 4 de noviembre de 2026).

```bash
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: message-threads-2026-08-12" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "system": "You are a careful backend reviewer.",
    "messages": [
      {"role": "user", "content": "Read this design and list the risks."}
    ],
    "thread": {"type": "create"}
  }'
```

Guarda el `id` de esa respuesta. La siguiente petición envía solo el mensaje nuevo:

```bash
PREVIOUS_ID="<id from the previous response>"

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: message-threads-2026-08-12" \
  -H "content-type: application/json" \
  -d @- <<JSON
{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "Turn those risks into a checklist."}
  ],
  "thread": {"type": "continue", "previous_message_id": "$PREVIOUS_ID"}
}
JSON
```

Conserva el `id` más reciente de cada respuesta: un hilo solo admite añadidos, cada `id` de respuesta se puede continuar una vez y la siguiente petición debe usar el último (página Message threads, 4 de noviembre de 2026).

Si necesitas otra forma de conseguir una clave de API, OmniaKey vende acceso a la API de Claude con los mismos ID de modelo, así que el cuerpo de la petición no cambia. Los hilos son una beta del lado de Anthropic, así que antes de depender de ellos en producción comprueba que el intermediario que uses pasa el campo `thread` tal cual.

El SDK de Python guarda los id por ti. Crea un helper con `client.beta.messages.thread(...)`, que solo prepara la llamada, y envía cada turno con `thread.send()`. El helper añade el encabezado beta, crea en el primer turno, continúa solo con los mensajes nuevos y reenvía la conversación completa una vez en una nueva petición create cuando un continue devuelve `thread_not_found`, `thread_already_continued` o `thread_continue_in_flight` (página Message threads, 4 de noviembre de 2026).

```python
import anthropic

client = anthropic.Anthropic()  # lee ANTHROPIC_API_KEY

# El helper aún no envía nada; guarda los campos que reutiliza cada turno.
thread = client.beta.messages.thread(
    model="claude-opus-5-5",
    max_tokens=1024,
    system="You are a careful backend reviewer.",
)

first = thread.send({"role": "user", "content": "Read this design and list the risks."})
print(first.id, first.stop_reason)

second = thread.send({"role": "user", "content": "Turn those risks into a checklist."})
print(second.id)  # la próxima vez continúa desde este id
```

No ejecutamos estas peticiones contra la API de Anthropic; la forma de las peticiones viene de la página Message threads de Anthropic. Para streaming, `thread.stream(...)` con `stream.get_final_message()` da el mismo flujo, y `thread.previous_message_id` devuelve el id cuando prefieres llevar la cuenta tú.

## Qué reenviar y qué no reenviar nunca

Envía los campos fijos en cada petición con los mismos valores, `system` y `tools` solo en la petición create, y deja que los campos libres cambien de un turno a otro.

|Grupo|Campos|Regla|
|-|-|-|
|Solo create|`system`, `tools`|Solo en la petición create; enviar cualquiera de los dos en una petición continue, aunque sea `null`, da un 400.|
|Fijos|`model`, `tool_choice`, `thinking`, `mcp_servers` salvo el token de autorización de cada servidor, `context_management`, `output_config`, los `skills` de `container`, el `cache_control` de nivel superior y el conjunto de valores de `anthropic-beta`|El mismo valor siempre. Un valor distinto devuelve un 400 que nombra el campo que cambia.|
|Libres|`max_tokens`, `stop_sequences`, `stream`, `metadata`, `service_tier` y los campos sin nombre|Cámbialos cuando quieras.|

El 400 por un campo fijo cambiado lleva `thread_fingerprint_mismatch` y el mensaje lista los campos que difieren. Para cambiar uno de esos valores, empieza un hilo nuevo con la conversación completa y el valor nuevo.

Si omites `previous_message_id`, el continue devuelve un 400 cuyo cuerpo trae un mensaje pero ningún `error_code`; incluir `system` o `tools` hace lo mismo. Un continue debe llevar exactamente los mensajes posteriores a la última respuesta.

`mcp_servers` es fijo, pero las URL de los servidores y los tokens de autorización viven solo en tu petición, así que envía la lista en cada petición que use MCP; un token puede cambiar entre peticiones. El `id` del contenedor también vive solo en tu petición, así que envía `container` cada vez (página Message threads, 4 de noviembre de 2026).

El fallback del servidor se decide en el create: envía `fallbacks` en todas las peticiones del hilo o en ninguna. El valor puede cambiar entre turnos, pero añadir o quitar el campo devuelve `thread_fingerprint_mismatch`.

## Caducidad, reenvío y el 404

Un hilo caduca 5 minutos después de su última petición, y la API lo borra como máximo 1 hora después de su último uso. Cada respuesta guardada reinicia los 5 minutos. Los hilos no son aptos para retención cero de datos: la conversación, el system prompt y las herramientas están en memoria, cifrados, y nunca se escriben en almacenamiento duradero (página Message threads, 4 de noviembre de 2026).

Ningún campo de la respuesta dice si la API guardó un turno, ni en un create ni en un continue. Lo sabes en la siguiente petición continue, así que tu aplicación es la fuente de verdad y conserva su propia copia de cada mensaje (página Message threads, 4 de noviembre de 2026).

Cuando un continue devuelve 404 `thread_not_found`, envía la conversación completa en una nueva petición create y continúa desde el `id` de esa respuesta. La API da el mismo 404 en todos estos casos:

- el hilo caducó;
- el turno anterior se sirvió y luego se descartó, por ejemplo una llamada a herramienta cortada por `max_tokens`;
- un modelo de fallback escribió la respuesta anterior;
- la respuesta anterior aún se está generando;
- la petición viene de otra organización, espacio de trabajo, usuario o clave de espacio de trabajo;
- los mensajes nuevos añaden contenido que la conversación guardada no tiene, como la primera imagen de una conversación que no tenía ninguna.

Reenviar la conversación completa siempre es seguro y repara todos esos casos.

El streaming añade una regla: continúa desde el `id` de la respuesta solo después de `message_stop`, porque un continue enviado antes puede devolver 404. Si el stream de una petición continue se corta antes de `message_stop`, envía otra vez la misma petición continue, y reenvía si eso devuelve `thread_already_continued` o `thread_continue_in_flight`. El helper del SDK deja el stream cortado para que lo reintentes tú.

Otros tres casos tienen su propio camino:

- `pause_turn`: continúa desde el `id` de esa respuesta con `"messages": []`. Si eso da 404, reenvía incluyendo la respuesta pausada.
- `stop_reason: "refusal"`: empieza un hilo nuevo sin el turno que lo causó; la API puede tener ya el turno rechazado.
- una entrada `fallback_message` en `usage.iterations`, o en el `message_delta` final de un stream, marca una respuesta de fallback: reenvía.

## Errores

Los cinco errores de hilo vuelven antes de que se ejecute el modelo: la petición no usa tokens y el hilo conserva su plazo. `error.type` es `invalid_request_error` para los 400 y `not_found_error` para el 404 (página Message threads, 4 de noviembre de 2026).

- **404, `thread_not_found`**: la API no puede continuar este hilo. Envía la conversación completa en una nueva petición create.
- **400, `thread_fingerprint_mismatch`**: un campo fijo cambió respecto al valor guardado con el hilo. Déjalo idéntico o empieza un hilo nuevo.
- **400, `thread_already_continued`**: ese id de respuesta ya se usó una vez. Continúa desde el id más reciente y reenvía si nunca lo recibiste.
- **400, `thread_continue_in_flight`**: otro continue desde el mismo id sigue en marcha, normalmente tu intento anterior. Déjalo terminar o reenvía.
- **400, `thread_unsupported_request`**: la petición usa una función o un ajuste de la organización que los hilos no admiten. `error.details.unsupported` nombra uno de `context_management`, `cache_control`, `fallbacks`, `hipaa` o `inference_hooks`; esa lista puede crecer, así que si un valor te resulta desconocido, envía la conversación completa sin `thread`.

Message Batches rechaza el campo `thread` (un elemento de lote que lo lleve falla con `invalid_request_error`), y el conteo de tokens y la compactación devuelven 400; también la edición de contexto distinta de `clear_thinking_20251015` con `keep: "all"`. Las organizaciones listas para HIPAA y las que tienen Inference hooks activados quedan fuera. Listar, leer y borrar un hilo no están disponibles en la API.

## Preguntas frecuentes

### ¿Qué es la API de message threads de Claude?

Es una función beta de la Messages API que guarda una conversación del lado de Anthropic para que los turnos siguientes envíen solo mensajes nuevos. El encabezado beta es `message-threads-2026-08-12`, y cada petición añade un objeto `thread` con `type` en `create` o `continue`.

### ¿Los hilos funcionan con la caché de prompts?

Sí. Un hilo no cachea tu prompt por ti: envía un `cache_control` de nivel superior en cada petición y no pases de cuatro puntos de interrupción. Los puntos de los mensajes guardados quedan fuera de esa cuenta; el de nivel superior y los de `system` o `tools` sí cuentan.

### ¿Puedo cambiar de modelo a mitad de un hilo?

Cambiar de modelo exige un hilo nuevo. `model` es un campo fijo, así que un valor distinto devuelve 400 `thread_fingerprint_mismatch`; empieza un hilo nuevo con la conversación completa y el modelo nuevo.

### ¿Por qué un continue devuelve 400 sin error\_code?

Al continue le falta `previous_message_id`, o incluye `system` o `tools`, aunque sea `null`. Esos 400 llevan un mensaje y omiten `error_code`, así que lee el texto.

### ¿Cuánto dura un hilo y qué pasa cuando caduca?

Un hilo caduca 5 minutos después de su última petición y se borra como máximo 1 hora después de su último uso. Después, un continue devuelve 404 `thread_not_found`; envía la conversación completa en una nueva petición create y continúa desde su `id`.

## Fuentes consultadas

- [Anthropic: message threads](https://platform.claude.com/docs/en/build-with-claude/message-threads)
- [Anthropic: caché de prompts](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
- [Anthropic: precios de la API de Claude](https://platform.claude.com/docs/en/about-claude/pricing)
- [Anthropic: versiones de la API](https://platform.claude.com/docs/en/api/versioning)