Referência de Papéis da API de Mensagens e Tipos de Blocos de Conteúdo
Uma referência densa e escaneável para os dois papéis de mensagem e os quatro tipos de blocos de conteúdo que você encontrará ao construir com a API de Mensagens.
Mantenha esta página aberta enquanto configura as requisições - ela serve para consulta, não para ser lida do início ao fim.
Como Usar Esta Referência
- Procure um papel ou tipo de bloco pelo nome nas tabelas abaixo.
- Cada linha mostra em qual(is) turno(s) ele pode aparecer e a forma mínima de seu JSON.
- A coluna "Aparece Em" informa se um bloco é algo que você envia, algo que o Claude envia de volta, ou ambos.
- Verifique com Entendendo Papéis e Turnos na API de Mensagens se uma linha não fizer sentido isoladamente.
Papéis
| Papel | Quem envia | Observações |
|---|---|---|
user | Sua aplicação | Representa a entrada para o Claude - perguntas, resultados de ferramentas, imagens. Deve ser a primeira entrada em messages e deve alternar com assistant. |
assistant | Claude (ecoado por você no próximo turno) | Representa as próprias respostas anteriores do Claude, incluindo quaisquer blocos tool_use. Você o anexa após cada resposta para preservar o histórico. |
system (não é um papel em messages) | Sua aplicação | Um parâmetro de requisição separado e de nível superior, não uma entrada em messages - define a persona/restrições para toda a conversa. |
Tipos de Blocos de Conteúdo
| Tipo | Aparece Em | Forma Mínima |
|---|---|---|
text | user, assistant | {"type": "text", "text": "..."} |
image | user apenas | {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "..."}} |
tool_use | assistant apenas | {"type": "tool_use", "id": "toolu_...", "name": "get_weather", "input": {"location": "Paris"}} |
tool_result | user apenas | {"type": "tool_result", "tool_use_id": "toolu_...", "content": "..."} |
Blocos de Texto
{"role": "user", "content": [{"type": "text", "text": "Qual é a capital da França?"}]}| Campo | Tipo | Observações |
|---|---|---|
type | "text" | Sempre a string literal "text". |
text | string | O conteúdo da mensagem. Um valor content de string simples (sem lista) é um atalho para um único bloco de texto. |
Blocos de Imagem
{
"role": "user",
"content": [
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": base64_data}},
{"type": "text", "text": "O que há nesta imagem?"},
],
}| Campo | Tipo | Observações |
|---|---|---|
type | "image" | Sempre "image". |
source.type | "base64" ou "url" | base64 incorpora os dados da imagem diretamente; url referencia uma imagem publicamente acessível. |
source.media_type | string | Necessário para fontes base64, por exemplo, "image/png", "image/jpeg". |
source.data | string | Bytes da imagem codificados em Base64, necessário para fontes base64. |
Aparece apenas em turnos user - o Claude produz texto descrevendo imagens, nunca blocos de imagem próprios.
Blocos de Uso de Ferramenta (Tool Use)
# Aparece dentro do conteúdo de um turno assistant, produzido pelo Claude - você não escreve isso manualmente.
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": {"location": "Paris, France"},
}| Campo | Tipo | Observações |
|---|---|---|
type | "tool_use" | Sempre "tool_use". |
id | string | ID único para esta chamada de ferramenta - ecoe-o de volta no tool_result correspondente. |
name | string | O nome da ferramenta, correspondendo a uma das tools que você declarou na requisição. |
input | object | Argumentos analisados que correspondem ao input_schema da ferramenta. Sempre analise com suas ferramentas de JSON em vez de correspondência de strings - nunca assuma uma serialização fixa. |
Blocos de Resultado de Ferramenta (Tool Result)
{
"role": "user",
"content": [
{"type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "72F and sunny"},
],
}| Campo | Tipo | Observações |
|---|---|---|
type | "tool_result" | Sempre "tool_result". |
tool_use_id | string | Deve corresponder ao id do bloco tool_use ao qual está respondendo. |
content | string ou lista de blocos | A saída da ferramenta. Pode ser uma lista de blocos text/image para resultados mais ricos. |
is_error | boolean (opcional) | Defina como true se a chamada da ferramenta falhou, para que o Claude saiba como se adaptar em vez de tratar o conteúdo como um resultado válido. |
Combinando Tipos de Blocos em um Único Turno
| Cenário | Conteúdo do Turno |
|---|---|
| Pergunta simples | [{"type": "text", "text": "..."}] (ou uma string simples) |
| Pergunta sobre uma imagem | [{"type": "image", ...}, {"type": "text", "text": "..."}] |
| Claude solicitando uma chamada de ferramenta | [{"type": "text", "text": "..."}, {"type": "tool_use", ...}] |
| Retornando um resultado de ferramenta mais um comentário de acompanhamento | [{"type": "tool_result", ...}, {"type": "text", "text": "..."}] |
Múltiplos blocos do mesmo tipo ou de tipos diferentes podem coexistir na lista content de um único turno - a alternância de papéis se aplica ao turno como um todo, não a blocos individuais.
FAQs
Uma string simples pode ser usada em vez de uma lista de blocos de conteúdo?
Sim - content: "algum texto" é um atalho para content: [{"type": "text", "text": "algum texto"}]. Use o formato de lista assim que precisar de mais de um bloco ou de um tipo de bloco não textual.
Quais tipos de blocos o Claude pode produzir, versus apenas enviar?
O Claude produz blocos text e tool_use em turnos assistant. Blocos image e tool_result são coisas que sua aplicação envia em turnos user; o Claude nunca os gera.
O que identifica qual tool_result responde a qual tool_use?
O campo tool_use_id no bloco tool_result deve corresponder exatamente ao campo id que o Claude gerou no bloco tool_use correspondente.
Um turno pode conter múltiplos blocos tool_use?
Sim - o Claude pode solicitar várias chamadas de ferramenta em um único turno assistant. Quando isso acontece, retorne todos os blocos tool_result correspondentes juntos em um único turno user, não divididos em múltiplos turnos.
O que faz o is_error em um bloco tool_result?
Ele informa ao Claude que a chamada da ferramenta falhou em vez de ter sucesso, para que o Claude raciocine sobre a falha e possa tentar uma abordagem diferente em vez de tratar a mensagem de erro como dados válidos.
System é um tipo de bloco de conteúdo?
Não. system é um parâmetro de requisição separado de nível superior, não um papel ou um bloco de conteúdo dentro de messages. Ele não tem tipos de bloco próprios.
Blocos de imagem funcionam em turnos assistant?
Não - blocos de imagem aparecem apenas em turnos user, pois representam a entrada que você está fornecendo ao Claude, não algo que o Claude gera.
Qual a diferença entre source.type "base64" e "url" para imagens?
base64 incorpora os bytes brutos da imagem diretamente na requisição; url aponta para uma URL de imagem publicamente acessível que o Claude busca. Use base64 para arquivos locais e url quando a imagem já estiver hospedada.
Devo analisar a entrada tool_use como JSON ou tratá-la como uma string bruta?
Sempre analise - input é entregue como um objeto estruturado que corresponde ao schema da sua ferramenta, e depender de formatação de string exata (como escape específico) é frágil e pode falhar entre versões do modelo.
O conteúdo de tool_result pode ser mais do que texto simples?
Sim - content em um bloco tool_result pode ser uma string, ou uma lista de blocos (como text e image) para resultados mais ricos, como retornar uma imagem de gráfico gerada junto com um resumo em texto.
A ordem dos blocos dentro da lista de conteúdo de um único turno importa?
Geralmente sim, para legibilidade e como o Claude processa o contexto de múltiplos blocos - coloque o texto explicativo antes ou depois do bloco ao qual se refere de forma consistente, embora não haja uma regra de alternância estrita dentro da lista de conteúdo de um turno, como há entre os turnos.
Relacionados
- Entendendo Papéis e Turnos na API de Mensagens - o modelo conceitual por trás de papéis e turnos.
- Lidando com Blocos de Conteúdo Mistos: Texto, Imagem e Resultados de Ferramentas em um Único Turno - exemplos práticos combinando múltiplos tipos de blocos.
- Noções Básicas da API de Mensagens - exemplos executáveis usando vários desses tipos de blocos.
Versões da Stack: Escrito com base na linha de modelos Claude atual em aproximadamente Junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o SDK oficial
anthropicpara Python (última versão 0.x). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.