Usando a API de Mensagens

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 API de Mensagens, incluindo requisições básicas, conversas de múltiplos turnos, técnicas de preenchimento prévio e recursos de visão. Para especificações completas da API, consulte a referência da API de Mensagens.



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

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 Tratamento de motivos de parada para a referência de campos e exemplos de código de tratamento.



Múltiplos turnos de conversa

A API de Mensagens é 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. 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",
    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
  }
}



Papel system em mensagens

No Claude Fable 5, Claude Mythos 5, Claude Opus 4.8 e Claude Opus 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 ela é anexada ao final do histórico de mensagens, não invalida nenhum prefixo em cache que veio antes dela. Use o campo system de nível superior para instruções que devem ser aplicadas 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 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 em requisições. Você pode fornecer imagens usando os tipos de fonte base64, url ou file. O tipo de fonte file referencia uma imagem enviada por meio da API de Arquivos. 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 httpx

# 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(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)

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