A API Messages cobre o básico — enviar texto, receber texto. Mas Claude tem features que transformam a qualidade da resposta e abrem casos de uso impossíveis com chatbots genéricos. Extended thinking dá raciocínio profundo. Citations dá respostas verificáveis. Vision e PDF processam documentos nativamente. Code execution roda código real num sandbox. Cada feature tem custo, benefício e trade-offs concretos.
Extended thinking: quando Claude precisa pensar antes de responder
Extended thinking cria blocos de raciocínio interno (thinking) antes da resposta final. Claude literalmente para, analisa passo a passo, e só então responde. É a diferença entre responder de imediato e resolver um problema complexo no papel antes de falar.
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=16000,
thinking={
"type": "enabled",
"budget_tokens": 10000 # máx tokens para raciocínio
},
messages=[{
"role": "user",
"content": "Prove que existem infinitos primos p onde p mod 4 == 3"
}],
)
for block in response.content:
if block.type == "thinking":
print(f"Raciocínio: {block.thinking}")
elif block.type == "text":
print(f"Resposta: {block.text}")budget_tokens controla o teto. budget_tokens define o máximo de tokens que Claude pode gastar pensando. Deve ser menor que max_tokens. Se o problema for simples, Claude usa menos — o budget é um teto, não um alvo.
| Modelo | Output máximo | Thinking |
|---|---|---|
| Opus 4.7 | 128k tokens | Adaptive thinking (obrigatório) |
| Opus 4.6 | 128k tokens | Manual ou adaptive |
| Sonnet 4.6 | 64k tokens | Manual ou adaptive |
| Haiku 4.5 | 64k tokens | Manual |
Display modes — você controla o que volta na resposta:
| Mode | O que retorna | Custo | Quando usar |
|---|---|---|---|
| summarized (default) | Resumo do raciocínio | Paga pelo thinking completo | Debug, UX transparente |
| omitted | Campo vazio + signature | Mesmo custo, TTFT mais rápido | Produção (não mostra thinking) |
Thinking + Tool Use: regra crítica. Com extended thinking e tool use juntos, só funciona tool_choice: "auto" ou "none". Forçar uma ferramenta específica dá erro 400. E você deve passar os thinking blocks inalterados de volta ao enviar tool_results.
Interleaved thinking: raciocínio entre ferramentas
Nos modelos Claude 4+, o thinking pode acontecer entre chamadas de ferramentas — não só antes da primeira resposta. Isso permite raciocínio multi-step sofisticado:
User: "Analise a performance do auth.py e sugira otimizações"
[thinking] "Preciso primeiro ler o arquivo para entender a estrutura..."
[tool_use: Read("auth.py")]
[tool_result: conteúdo do arquivo]
[thinking] "Vejo um N+1 query na linha 42. Preciso verificar se há índice..."
[tool_use: Read("models.py")]
[tool_result: conteúdo do arquivo]
[thinking] "Confirmado — não há índice no campo user_id. A solução é..."
[text] "Encontrei 3 problemas de performance: ..."} Com interleaved thinking, o budget_tokens é o total de todos os blocos de thinking no turn — pode ser maior que max_tokens porque thinking tokens e text tokens são contados separadamente.
Citations: respostas com referências verificáveis
Citations transformam Claude de "confie em mim" para "aqui está exatamente de onde tirei isso". Você envia documentos com citations.enabled: true, e a resposta volta com ponteiros exatos para trechos do documento original.
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
messages=[{
"role": "user",
"content": [
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "O custo do S3 Standard é $0.023/GB. "
"O S3 Glacier Deep Archive custa $0.00099/GB.",
},
"title": "Preços AWS S3",
"citations": {"enabled": True},
},
{
"type": "text",
"text": "Qual a diferença de custo entre S3 Standard e Glacier?"
},
],
}],
)A resposta volta com blocos de texto interligados por citações:
{
"content": [
{"type": "text", "text": "O S3 Standard custa "},
{
"type": "text",
"text": "$0.023/GB",
"citations": [{
"type": "char_location",
"cited_text": "O custo do S3 Standard é $0.023/GB.",
"document_index": 0,
"start_char_index": 0,
"end_char_index": 36
}]
},
{"type": "text", "text": " enquanto o Glacier Deep Archive custa "},
{
"type": "text",
"text": "$0.00099/GB",
"citations": [{
"type": "char_location",
"cited_text": "O S3 Glacier Deep Archive custa $0.00099/GB.",
"document_index": 0,
"start_char_index": 37,
"end_char_index": 82
}]
}
]
}| Tipo de documento | Formato de citação | Granularidade |
|---|---|---|
| Plain text | char_location (start/end char index) | Sentença (chunking automático) |
| page_location (start/end page number) | Sentença por página | |
| Custom content | content_block_location (start/end block index) | Blocos que você define |
cited_text não conta como output token. O texto citado é extraído automaticamente e não conta na cobrança de output tokens. Quando passado de volta em conversas multi-turn, também não conta como input token. Isso torna citations mais barato que pedir "cite suas fontes" no prompt.
Vision e PDF: processamento nativo de documentos
Claude processa imagens e PDFs diretamente na API — sem OCR externo, sem conversão manual:
import base64
with open("architecture-diagram.png", "rb") as f:
image_data = base64.standard_b64encode(f.read()).decode("utf-8")
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": image_data,
},
},
{
"type": "text",
"text": "Descreva esta arquitetura. Identifique SPOFs."
},
],
}],
)Para PDFs, a API extrai texto automaticamente e permite citations por página:
with open("contract.pdf", "rb") as f:
pdf_data = base64.standard_b64encode(f.read()).decode("utf-8")
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=2048,
messages=[{
"role": "user",
"content": [
{
"type": "document",
"source": {
"type": "base64",
"media_type": "application/pdf",
"data": pdf_data,
},
"title": "Contrato de serviço",
"citations": {"enabled": True},
},
{
"type": "text",
"text": "Resuma as cláusulas de SLA e penalidades."
},
],
}],
)| Formato | Suporte | Limites |
|---|---|---|
| Imagens (PNG, JPEG, GIF, WebP) | Todos os modelos | ~1600 tokens por imagem |
| Todos os modelos ativos | Texto extraído automaticamente | |
| CSV, XLSX, DOCX | Não suportado direto | Converter para texto e enviar inline |
Code execution e Files API
O code execution permite que Claude escreva e rode código Python num sandbox seguro — útil para cálculos, geração de gráficos e transformações de dados:
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=4096,
tools=[{
"type": "computer_20241022",
"name": "code_execution",
}],
messages=[{
"role": "user",
"content": "Calcule o desvio padrão de [23, 45, 12, 67, 34, 89, 56] "
"e gere um histograma."
}],
)A Files API permite upload de arquivos que podem ser referenciados em múltiplas conversas:
# Upload do arquivo
file = client.files.create(
file=open("dataset.csv", "rb"),
purpose="assistants",
)
# Referenciar por file_id em qualquer conversa
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=2048,
messages=[{
"role": "user",
"content": [
{
"type": "document",
"source": {"type": "file", "file_id": file.id},
"citations": {"enabled": True},
},
{"type": "text", "text": "Analise as tendências neste dataset."},
],
}],
)Quando usar code execution vs ferramentas externas: Code execution é ideal para cálculos, visualizações e transformações de dados simples. Para operações complexas (acessar banco de dados, chamar APIs, manipular filesystem), use tool use ou MCP — code execution roda num sandbox isolado sem acesso externo.
Mapa de decisão: quando usar cada feature
| Preciso de... | Feature | Custo extra |
|---|---|---|
| Raciocínio profundo em problemas complexos | Extended thinking | Tokens de thinking (pode ser alto) |
| Respostas verificáveis com fontes | Citations | Leve aumento de input tokens |
| Analisar imagens ou diagramas | Vision | ~1600 tokens por imagem |
| Extrair informação de PDFs | PDF + Citations | Input tokens do documento |
| Executar cálculos e gerar gráficos | Code execution | Tokens do código + resultado |
| Reusar documentos em várias conversas | Files API | Storage + input por referência |
| Máxima qualidade em tarefa difícil | Thinking + Citations + Vision | Combinação dos custos |
Incompatibilidade: Citations + Structured Outputs. Citations e Structured Outputs (output_format com JSON schema) não podem ser usados juntos. Citations intercalam blocos de texto com citações, o que é incompatível com schema JSON estrito. Se precisar de ambos, faça em duas chamadas separadas.