Referencia de Roles de la API de Mensajes y Tipos de Bloques de Contenido
Una referencia densa y escaneable para los dos roles de mensaje y los cuatro tipos de bloques de contenido que encontrarás al desarrollar con la API de Mensajes.
Mantén esta página abierta mientras configuras las solicitudes; está pensada para ser consultada, no para leerse de principio a fin.
Cómo Usar Esta Referencia
- Busca un rol o tipo de bloque por su nombre en las tablas siguientes.
- Cada fila muestra en qué turno(s) puede aparecer y la forma mínima de su JSON.
- La columna "Aparece en" te indica si un bloque es algo que envías tú, algo que Claude devuelve, o ambos.
- Comprueba con Entendiendo Roles y Turnos en la API de Mensajes si una fila no tiene sentido de forma aislada.
Roles
| Rol | Quién lo envía | Notas |
|---|---|---|
user | Tu aplicación | Representa la entrada a Claude: preguntas, resultados de herramientas, imágenes. Debe ser la primera entrada en messages y debe alternar con assistant. |
assistant | Claude (repetido por ti en el siguiente turno) | Representa las respuestas anteriores de Claude, incluidos los bloques tool_use. Lo adjuntas después de cada respuesta para preservar el historial. |
system (no es un rol en messages) | Tu aplicación | Un parámetro de solicitud de nivel superior separado, no una entrada de messages; establece la personalidad/restricciones para toda la conversación. |
Tipos de Bloques de Contenido
| Tipo | Aparece en | Forma Mínima |
|---|---|---|
text | user, assistant | {"type": "text", "text": "..."} |
image | user solamente | {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "..."}} |
tool_use | assistant solamente | {"type": "tool_use", "id": "toolu_...", "name": "get_weather", "input": {"location": "Paris"}} |
tool_result | user solamente | {"type": "tool_result", "tool_use_id": "toolu_...", "content": "..."} |
Bloques de Texto
{"role": "user", "content": [{"type": "text", "text": "¿Cuál es la capital de Francia?"}]}| Campo | Tipo | Notas |
|---|---|---|
type | "text" | Siempre la cadena literal "text". |
text | string | El contenido del mensaje. Un valor content de cadena simple (sin lista) es una abreviatura de un solo bloque de texto. |
Bloques de Imagen
{
"role": "user",
"content": [
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": base64_data}},
{"type": "text", "text": "¿Qué hay en esta imagen?"},
],
}| Campo | Tipo | Notas |
|---|---|---|
type | "image" | Siempre "image". |
source.type | "base64" o "url" | base64 incrusta los datos de la imagen directamente; url hace referencia a una imagen públicamente accesible. |
source.media_type | string | Requerido para fuentes base64, por ejemplo, "image/png", "image/jpeg". |
source.data | string | Bytes de imagen codificados en Base64, requerido para fuentes base64. |
Solo aparece en turnos user; Claude produce texto que describe imágenes, nunca bloques de imagen propios.
Bloques de Uso de Herramientas (Tool Use)
# Aparece dentro del contenido de un turno assistant, producido por Claude; no lo escribes a mano.
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": {"location": "Paris, France"},
}| Campo | Tipo | Notas |
|---|---|---|
type | "tool_use" | Siempre "tool_use". |
id | string | ID único para esta llamada a la herramienta; repítelo en el tool_result correspondiente. |
name | string | El nombre de la herramienta, que coincide con una de las tools que declaraste en la solicitud. |
input | object | Argumentos analizados que coinciden con el input_schema de la herramienta. Analiza siempre con tus herramientas JSON en lugar de comparar cadenas; nunca asumas una serialización fija. |
Bloques de Resultado de Herramienta (Tool Result)
{
"role": "user",
"content": [
{"type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "72F y soleado"},
],
}| Campo | Tipo | Notas |
|---|---|---|
type | "tool_result" | Siempre "tool_result". |
tool_use_id | string | Debe coincidir con el id del bloque tool_use al que está respondiendo. |
content | string o lista de bloques | La salida de la herramienta. Puede ser en sí misma una lista de bloques text/image para resultados más ricos. |
is_error | boolean (opcional) | Establece true si la llamada a la herramienta falló, para que Claude sepa cómo adaptarse en lugar de tratar el contenido como un resultado válido. |
Combinación de Tipos de Bloques en un Solo Turno
| Escenario | Contenido del Turno |
|---|---|
| Pregunta simple | [{"type": "text", "text": "..."}] (o una cadena simple) |
| Pregunta sobre una imagen | [{"type": "image", ...}, {"type": "text", "text": "..."}] |
| Claude solicitando una llamada a herramienta | [{"type": "text", "text": "..."}, {"type": "tool_use", ...}] |
| Devolviendo el resultado de una herramienta más un comentario de seguimiento | [{"type": "tool_result", ...}, {"type": "text", "text": "..."}] |
Múltiples bloques del mismo o de diferentes tipos pueden coexistir en la lista content de un turno; la alternancia de roles se aplica al turno en su conjunto, no a bloques individuales.
Preguntas Frecuentes
¿Se puede usar una cadena simple en lugar de una lista de bloques de contenido?
Sí, content: "algún texto" es una abreviatura de content: [{"type": "text", "text": "algún texto"}]. Usa el formato de lista una vez que necesites más de un bloque o un tipo de bloque que no sea de texto.
¿Qué tipos de bloques puede producir Claude, y cuáles solo enviar?
Claude produce bloques text y tool_use en los turnos assistant. Los bloques image y tool_result son cosas que tu aplicación envía en los turnos user; Claude nunca los genera.
¿Qué identifica qué `tool_result` responde a qué `tool_use`?
El campo tool_use_id en el bloque tool_result debe coincidir exactamente con el campo id que Claude generó en el bloque tool_use correspondiente.
¿Puede un turno contener múltiples bloques `tool_use`?
Sí, Claude puede solicitar varias llamadas a herramientas en un solo turno assistant. Cuando eso sucede, devuelve todos los bloques tool_result coincidentes juntos en un solo turno user, no divididos en varios turnos.
¿Qué hace `is_error` en un bloque `tool_result`?
Le dice a Claude que la llamada a la herramienta falló en lugar de tener éxito, para que Claude razone sobre el fallo y pueda intentar un enfoque diferente en lugar de tratar el mensaje de error como datos válidos.
¿Es `system` un tipo de bloque de contenido?
No. system es un parámetro de solicitud de nivel superior separado, no un rol ni un bloque de contenido dentro de messages. No tiene tipos de bloque propios.
¿Funcionan los bloques de imagen en los turnos `assistant`?
No, los bloques de imagen solo aparecen en los turnos user, ya que representan la entrada que proporcionas a Claude, no algo que Claude genera.
¿Cuál es la diferencia entre `source.type` "base64" y "url" para las imágenes?
base64 incrusta los bytes brutos de la imagen directamente en la solicitud; url en su lugar apunta a una URL de imagen públicamente accesible que Claude recupera. Usa base64 para archivos locales y url cuando la imagen ya esté alojada.
¿Debo analizar la entrada `tool_use` como JSON o tratarla como una cadena sin procesar?
Analízala siempre; input se entrega como un objeto estructurado que coincide con el esquema de tu herramienta, y depender del formato de cadena exacto (como el escape específico) es frágil y puede fallar entre versiones del modelo.
¿Puede el contenido de `tool_result` ser más que texto plano?
Sí, content en un bloque tool_result puede ser una cadena o una lista de bloques (como text e image) para obtener resultados más ricos, como devolver una imagen de gráfico generada junto con un resumen de texto.
¿Importa el orden de los bloques dentro de la lista de contenido de un turno?
Generalmente sí, para la legibilidad y cómo Claude procesa el contexto de múltiples bloques. Coloca el texto explicativo antes o después del bloque al que se refiere de manera consistente, aunque no hay una regla de alternancia estricta dentro de la lista de contenido de un turno, como la hay entre turnos.
Relacionados
- Entendiendo Roles y Turnos en la API de Mensajes - el modelo conceptual detrás de roles y turnos.
- Manejo de Bloques de Contenido Mixtos: Texto, Imagen y Resultados de Herramientas en un Solo Turno - ejemplos prácticos que combinan múltiples tipos de bloques.
- Conceptos Básicos de la API de Mensajes - ejemplos ejecutables que utilizan varios de estos tipos de bloques.
Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026: Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5, y el SDK oficial
anthropicpara Python (última versión 0.x). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.