Usando a Messages API

A Anthropic oferece duas maneiras de construir com o Claude, cada uma adequada a diferentes casos de uso:

Este guia aborda padrões comuns para trabalhar com a Messages API, incluindo requisições básicas, conversas com múltiplos turnos, técnicas de prefill (preenchimento prévio) e capacidades de visão. Para as especificações completas da API, consulte a referência da Messages API. Para o harness de agente gerenciado, consulte a visão geral do Claude Managed Agents.

Requisição e resposta 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
  }
}

Respostas de recusa (stop_reason: "refusal") também incluem um objeto stop_details que identifica a categoria de política que acionou a recusa, em todos os modelos. Consulte Tratando motivos de parada para a referência dos campos e código de exemplo de tratamento.

Múltiplos turnos de conversa

A Messages API é stateless (sem estado), o que significa que você sempre envia o histórico completo da conversa para a API. Você pode usar esse padrão para construir uma conversa ao longo do tempo. Os turnos anteriores da conversa não precisam necessariamente ter sido originados pelo Claude. Você pode usar mensagens assistant sintéticas.

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
  }
}

Role system em mensagens

Nos modelos Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 4.8, Claude Opus 5 e Claude Sonnet 5.5, você pode incluir mensagens com "role": "system" após um turno do usuário (sujeito às regras de posicionamento) para adicionar uma nova instrução de sistema no meio de uma conversa. Uma mensagem system não pode ser a primeira entrada em messages. Use o campo system de nível superior para instruções que se aplicam desde o início.

Uma mensagem de sistema no meio da conversa tem a mesma autoridade que o campo system de nível superior, mas, como é anexada ao final do histórico de mensagens, ela não invalida nenhum prefixo em cache que veio antes dela. Use o campo system de nível superior para instruções que devem se aplicar desde o primeiro turno, e uma mensagem de sistema no meio da conversa para instruções que só se tornam relevantes mais tarde.

Consulte Mensagens de sistema no meio da conversa para o guia completo, incluindo como combiná-las com o cache de prompt.

Preenchendo previamente a resposta do Claude

Você pode preencher previamente parte da resposta do Claude na última posição da lista de mensagens de entrada. Use essa técnica para moldar a resposta do Claude. O exemplo a seguir usa "max_tokens": 1 para obter uma única resposta de múltipla escolha do 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
  }
}

Visão

O Claude pode ler tanto texto quanto imagens nas requisições. Você pode fornecer imagens usando os tipos de origem base64, url ou file. O tipo de origem file referencia uma imagem enviada por meio da Files API. Os tipos de mídia suportados são image/jpeg, image/png, image/gif e image/webp. Consulte o guia de visão para mais detalhes.

import base64
import httpx2

# Opção 1: imagem codificada em 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)

# Opção 2: imagem 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 passos