Claude Platform Docs
MensagensConstruindo com Claude

Usando a Messages API

Padrões práticos e exemplos para usar a Messages API de forma eficaz

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

Messages APIClaude Managed Agents
O que éAcesso direto ao prompting do modeloHarness de agente pré-construído e configurável que é executado em infraestrutura gerenciada
Ideal paraLoops de agente personalizados e controle refinadoTarefas de longa duração e trabalho assíncrono

Este guia aborda padrões comuns para trabalhar com a Messages API, incluindo solicitações básicas, conversas com múltiplos turnos, técnicas de preenchimento prévio e recursos de visão. Para as especificações completas da API, consulte a referência da Messages APIPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar.. Para usar o harness de agente gerenciado em vez disso, consulte a visão geral do Claude Managed Agents.

Solicitaçã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)
Output
{
  "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
  }
}

As 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 Como é uma recusa para a referência do campo e um 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. Os turnos anteriores da conversa não precisam necessariamente ter sido originados pelo Claude. Você pode usar mensagens assistant sintéticas.

Com threads de mensagens, em beta, a API pode manter a conversa, de modo que cada solicitação posterior envie apenas as novas mensagens. Uma thread expira 5 minutos após sua última solicitação e é excluída no máximo 1 hora após seu último uso.

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)
Output
{
  "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
  }
}

Função de sistema nas mensagens

Para adicionar uma nova instrução de sistema no meio de uma conversa, inclua uma mensagem com "role": "system" logo após um turno do usuário. Essa mensagem não pode ser a primeira entrada em messages. Isso funciona no Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5.5 e Claude Haiku 5.5. Consulte as regras completas de posicionamento.

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 a preceda. 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 e alterações de ferramentas 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)
Output
{
  "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 solicitaçõ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)
Output
{
  "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

Trate cada valor de stop_reason e decida o que fazer quando uma resposta termina.

Dê ferramentas ao Claude para chamar serviços externos e APIs a partir da Messages API.

Controle ambientes de computador desktop com a Messages API.

Permita que o Claude navegue, leia e interaja com páginas da web em um navegador que você executa.

Obtenha saída JSON garantida e validada por esquema do Claude.

Defina um orçamento consultivo de tokens para um loop agêntico completo com output_config.task_budget.

Disponibilidade

Messages API
Os requisitos de disponibilidade de Messages API são os mesmos em todas as plataformas compatíveis.
Modelos
  • Todos os modelos

Endpoints aplicáveis

  • /v1/messages
Retenção zero de dadosElegível

Exclui Modelos cobertos

Chamadas de API padrão para gerar respostas do Claude.

HIPAAElegível

Esta página foi útil?