Uso de la API de Messages

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 API de Messages, incluyendo solicitudes básicas, conversaciones de múltiples turnos, técnicas de prellenado y capacidades de visión. Para las especificaciones completas de la API, consulta la referencia de la API de Messages.

Solicitud y respuesta básicas

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

En Claude Opus 4.7 y modelos posteriores, 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. Consulta Manejo de motivos de detención para ver la referencia del campo y código de ejemplo para su manejo.

Múltiples turnos conversacionales

La API de Messages 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-4-8",
    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-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 309
  }
}

Rol de sistema en los mensajes

En Claude Opus 4.8, 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 a mitad 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 de sistema a mitad de conversación tiene la misma autoridad que el campo system de nivel superior, pero como se añade 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 instrucciones que deban aplicarse desde el primer turno, y un mensaje de sistema a mitad de conversación para instrucciones que solo se vuelvan relevantes más adelante.

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

Poner palabras en boca de Claude

Puedes prellenar parte de la respuesta de Claude en la última posición de la lista de mensajes de entrada. Esto se puede usar para dar forma a la respuesta de Claude. El ejemplo a continuación 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. Las imágenes se pueden proporcionar 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 API de Files. Los tipos de medios admitidos 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 httpx

# Opción 1: Imagen codificada en Base64
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.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-4-8",
    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-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url)

{
  "id": "msg_01EcyWo6m4hyW8KHs2y2pei5",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an ant, specifically a close-up view of an ant. The ant is shown in detail, with its distinct head, antennae, and legs clearly visible. The image is focused on capturing the intricate details and features of the ant, likely taken with a macro lens to get an extreme close-up perspective."
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1551,
    "output_tokens": 71
  }
}

Uso de herramientas y uso de computadora

Consulta la guía de uso de herramientas para ver ejemplos de cómo usar herramientas con la API de Messages. Consulta la guía de uso de computadora para ver ejemplos de cómo controlar entornos de escritorio de computadora con la API de Messages. Para obtener salida JSON garantizada, consulta Salidas estructuradas. Para un presupuesto de tokens orientativo a lo largo de un ciclo agéntico completo, establece output_config.task_budget; consulta Presupuestos de tareas.