Uso de la Messages API

Anthropic ofrece dos formas de construir con Claude, cada una adecuada para diferentes casos de uso:

Esta guía cubre patrones comunes para trabajar con la API de Messages, incluidas solicitudes básicas, conversaciones de varios turnos, técnicas de “prefill” (prellenado) y capacidades de visión. Para ver las especificaciones completas de la API, consulta la referencia de la API de MessagesVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver.. Si prefieres el entorno de agente administrado, consulta la descripción general de Claude Managed Agents.

Solicitud y respuesta básicas

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

Las respuestas de rechazo (stop_reason: "refusal") también incluyen un objeto stop_details que identifica la categoría de política que desencadenó el rechazo, en todos los modelos. Consulta Cómo se ve un rechazo para ver la referencia del campo y código de ejemplo para manejarlo.

Múltiples turnos de conversación

La API de Messages es “stateless” (sin estado), lo que significa que siempre envías el historial completo de la conversación a la API. Puedes usar este patrón para construir una conversación a lo largo del tiempo. Los turnos anteriores de la conversación no necesariamente tienen que provenir realmente de Claude. Puedes usar mensajes assistant sintéticos.

Con los hilos de mensajes, en beta, la API puede conservar la conversación, de modo que cada solicitud posterior envíe solo los mensajes nuevos. Un hilo expira 5 minutos después de su última solicitud y se elimina como máximo 1 hora después de su último uso.

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)

{
  "id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Sure, I'd be happy to provide..."
    }
  ],
  "model": "claude-opus-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 309
  }
}

Rol de sistema en los mensajes

Para agregar una nueva instrucción del sistema a mitad de una conversación, incluye un mensaje con "role": "system" justo después de un turno del usuario. Ese mensaje no puede ser la primera entrada en messages. Esto funciona en Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5.5 y Claude Haiku 5.5. Consulta las reglas de ubicación completas.

Un mensaje del sistema a mitad de la conversación tiene la misma autoridad que el campo system de nivel superior, pero como se agrega al final del historial de mensajes, no invalida ningún prefijo almacenado en caché que lo preceda. Usa el campo system de nivel superior para las instrucciones que deben aplicarse desde el primer turno, y un mensaje del sistema a mitad de la conversación para las instrucciones que solo se vuelven relevantes más adelante.

Consulta Mensajes del sistema y cambios de herramientas a mitad de conversación para ver la guía completa, incluido cómo combinarlo con el “prompt caching” (almacenamiento en caché de prompts).

Prellenado de la respuesta de Claude

Puedes prellenar parte de la respuesta de Claude en la última posición de la lista de mensajes de entrada. Usa esta técnica para dar forma a la respuesta de Claude. El siguiente ejemplo usa "max_tokens": 1 para obtener de Claude una sola respuesta de opción múltiple.

message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1,
    messages=[
        {
            "role": "user",
            "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
        },
        {"role": "assistant", "content": "The answer is ("},
    ],
)
print(message)

{
  "id": "msg_01Q8Faay6S7QPTvEUUQARt7h",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "C"
    }
  ],
  "model": "claude-sonnet-4-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1
  }
}

Visión

Claude puede leer tanto texto como imágenes en las solicitudes. Puedes proporcionar imágenes usando los tipos de origen base64, url o file. El tipo de origen file hace referencia a una imagen cargada mediante la API de Files. Los tipos de medios compatibles son image/jpeg, image/png, image/gif e image/webp. Consulta la guía de Visión para obtener más detalles.

import base64
import httpx2

# Opción 1: imagen codificada en base64
image_url = "https://platform.claude.com/docs/images/vision-example.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx2.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message)

# Opción 2: imagen referenciada por URL
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://platform.claude.com/docs/images/vision-example.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url)

{
  "id": "msg_011CdKmWtV3oFx1C5yUbf5CY",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image is a beautiful minimalist/flat-design illustration of a sunset landscape. Here's what it contains:\n\n**Sky & Sun:**\n- A warm gradient sky transitioning from golden-yellow at the top to deep orange toward the horizon\n- A large pale yellow sun positioned in the upper-right area\n\n**Birds:**\n- Three small silhouetted birds flying in the upper-left portion of the sky, depicted as simple \"M\" or \"v\" shapes\n\n**Mountains:**\n- Multiple layered mountain peaks in purple and maroon tones\n- The mountains overlap to create depth, with varying shades of dusty purple and deep burgundy\n\n**Water:**\n- A dark purple body of water at the bottom of the image\n- A reflection of the sun shown as horizontal cream/peach colored lines in the center-bottom area\n\nThe overall style is clean, geometric, and uses a warm sunset color palette (oranges, yellows, purples, and maroons), giving it a peaceful, serene aesthetic typical of modern vector/flat design artwork."
    }
  ],
  "model": "claude-opus-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1030,
    "output_tokens": 350
  }
}

Próximos pasos