Uso de la Messages API

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

Esta guía cubre patrones comunes para trabajar con la Messages API, incluyendo solicitudes básicas, conversaciones de múltiples turnos, técnicas de "prefill" (prellenado) y capacidades de visión. Para las especificaciones completas de la API, consulta la referencia de la Messages API.



Solicitud y respuesta básicas

message = anthropic.Anthropic().messages.create(
    model="claude-opus-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",
  "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 activó el rechazo, en todos los modelos. Consulta Manejo de stop reasons para ver la referencia del campo y código de ejemplo para su manejo.



Múltiples turnos conversacionales

La Messages API no tiene estado, lo que significa que siempre envías el historial conversacional completo a la API. Puedes usar este patrón para construir una conversación a lo largo del tiempo. Los turnos conversacionales anteriores no necesariamente tienen que originarse realmente de Claude. Puedes usar mensajes assistant sintéticos.

message = anthropic.Anthropic().messages.create(
    model="claude-opus-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",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 309
  }
}



Rol system en los mensajes

En Claude Fable 5, Claude Mythos 5, Claude Opus 4.8 y Claude Opus 5, puedes incluir mensajes con "role": "system" después de un turno de usuario (sujeto a las reglas de ubicación) para agregar una nueva instrucción del sistema en medio de una conversación. Un mensaje system no puede ser la primera entrada en messages; usa el campo system de nivel superior para instrucciones que apliquen desde el inicio.

Un mensaje del sistema a mitad de 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 en caché que lo preceda. Usa el campo system de nivel superior para instrucciones que deban aplicarse desde el primer turno, y un mensaje del sistema a mitad de conversación para instrucciones que solo se vuelvan relevantes más adelante.

Consulta Mensajes del sistema a mitad de conversación para ver la guía completa, incluyendo cómo combinarlo con el almacenamiento en caché de prompts.



Prellenar 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 una única respuesta de opción múltiple de Claude.

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 fuente base64, url o file. El tipo de fuente file hace referencia a una imagen cargada a través de la Files API. Los tipos de medios admitidos son image/jpeg, image/png, image/gif e image/webp. Consulta la guía de visión para más detalles.

import base64
import httpx

# 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(httpx.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-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",
    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",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1030,
    "output_tokens": 350
  }
}



Próximos pasos