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 de múltiplos turnos, técnicas de "prefill" (preenchimento prévio) e recursos de visão. Para especificações completas da API, consulte a referência da Messages API.



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

No Claude Opus 4.7 e modelos posteriores, respostas de recusa (stop_reason: "refusal") também incluem um objeto stop_details que identifica a categoria de política que acionou a recusa. Consulte Lidando com stop reasons para a referência do campo e exemplo de código 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. Turnos de conversa anteriores não precisam necessariamente ter sido originados pelo Claude. Você pode usar mensagens assistant sintéticas.

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



Role system em mensagens

No Claude Opus 4.8, 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.



Colocando palavras na boca do Claude

Você pode preencher previamente parte da resposta do Claude na última posição da lista de mensagens de entrada. Isso pode ser usado para moldar a resposta do Claude. O exemplo abaixo 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. Imagens podem ser fornecidas usando os tipos de fonte base64, url ou file. O tipo de fonte file referencia uma imagem enviada através 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 httpx

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

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



Próximos passos