

Introdução ao uso da API para Claude

Este guia foi projetado para dar ao Claude os fundamentos do uso da Claude API. Ele fornece explicações e exemplos de IDs de modelos/a API de mensagens básica, uso de ferramentas, streaming, pensamento, e nada mais.



Modelos

For complex agentic coding and enterprise work: Claude Opus 5: claude-opus-5
Previous Opus model: Claude Opus 4.8: claude-opus-4-8
Smart model: Claude Sonnet 5: claude-sonnet-5
For fast, cost-effective tasks: Claude Haiku 4.5: claude-haiku-4-5-20251001



Chamando a API



Requisição e resposta básicas

import anthropic
import os

message = anthropic.Anthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY")
).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
  }
}



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 se originar de fato do Claude. Você pode usar mensagens assistant sintéticas.

import anthropic

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)



Pré-preenchendo a resposta do Claude

Você pode pré-preencher 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 a seguir usa "max_tokens": 1 para obter uma única resposta de múltipla escolha do Claude.

import anthropic

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.content[0].text)



Visão

Claude pode ler tanto texto quanto imagens em requisições. Ambos os tipos de fonte base64 e url são suportados para imagens, junto com os tipos de mídia image/jpeg, image/png, image/gif e image/webp.

import anthropic
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-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(next(block.text for block in message.content if block.type == "text"))

# 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://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(next(block.text for block in message_from_url.content if block.type == "text"))



Pensamento

O pensamento às vezes pode ajudar o Claude com tarefas muito difíceis. O mecanismo atual é o pensamento adaptativo (thinking: {"type": "adaptive"}): Claude decide quando e quanto pensar, e você direciona a profundidade do pensamento com o parâmetro effort em vez de um orçamento de tokens. O pensamento adaptativo é suportado nos modelos Claude 4.6 e posteriores e no Claude Mythos Preview. Nos modelos Claude 5 e no Claude Mythos Preview, o pensamento está ativado por padrão quando o parâmetro thinking é omitido.

A temperatura deve ser definida como 1 (ou deixada sem definição) sempre que o pensamento estiver habilitado, em todos os modelos. Nos modelos Claude 4.7 e posteriores e no Claude Mythos Preview, temperature está obsoleto e apenas seu valor padrão é aceito, mesmo quando o pensamento está desativado.

O pensamento é suportado nos seguintes modelos:

• Claude Opus 5 (claude-opus-5, apenas pensamento adaptativo, ativado por padrão)
• Claude Sonnet 5 (claude-sonnet-5, apenas pensamento adaptativo, ativado por padrão)
• Claude Opus 4.8 (claude-opus-4-8, apenas pensamento adaptativo)
• Claude Opus 4.7 (claude-opus-4-7, apenas pensamento adaptativo)
• Claude Opus 4.6 (claude-opus-4-6, pensamento adaptativo ou manual legado)
• Claude Sonnet 4.6 (claude-sonnet-4-6, pensamento adaptativo ou manual legado)
• Claude Opus 4.5 (claude-opus-4-5-20251101, apenas pensamento manual legado)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929, apenas pensamento manual legado)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001, apenas pensamento manual legado)



Como o pensamento funciona

Quando o pensamento está ativado, Claude cria blocos de conteúdo thinking onde ele produz seu raciocínio interno. A resposta da API inclui blocos de conteúdo thinking, seguidos por blocos de conteúdo text.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# A resposta conterá blocos de pensamento resumidos e blocos de texto
for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking summary: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

O pensamento estendido manual (thinking: {"type": "enabled", "budget_tokens": N}) é o mecanismo legado. Ele funciona apenas nos modelos Claude 4 até 4.6 que suportam pensamento; os modelos Claude 4.7 e posteriores rejeitam type: enabled com um erro 400 e usam o pensamento adaptativo em vez disso. Com o pensamento estendido manual, budget_tokens define o número máximo de tokens que o Claude pode usar para seu processo de raciocínio interno; o limite se aplica aos tokens de pensamento completos, não à saída resumida. A menos que você esteja usando pensamento intercalado, budget_tokens deve ser menor que max_tokens para que o Claude tenha espaço para escrever sua resposta após o pensamento ser concluído.



Pensamento com uso de ferramentas

O pensamento pode ser usado junto com o uso de ferramentas, permitindo que o Claude raciocine sobre a seleção de ferramentas e o processamento de resultados.

Limitações importantes:

1. Limitação de escolha de ferramenta: Suporta apenas tool_choice: {"type": "auto"} (padrão) ou tool_choice: {"type": "none"}.
2. Preservando blocos de pensamento: Durante o uso de ferramentas, você deve passar os blocos thinking de volta para a API para a última mensagem do assistente.



Preservando blocos de pensamento

import anthropic

client = anthropic.Anthropic()

weather_tool = {
    "name": "get_weather",
    "description": "Get the current weather for a location.",
    "input_schema": {
        "type": "object",
        "properties": {"location": {"type": "string", "description": "The city name."}},
        "required": ["location"],
    },
}

weather_data = {"temperature": 72}

# Primeira requisição - Claude responde com pensamento e solicitação de ferramenta
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

# Extrai o bloco de pensamento e o bloco de uso de ferramentas
thinking_block = next(
    (block for block in response.content if block.type == "thinking"), None
)
tool_use_block = next(
    (block for block in response.content if block.type == "tool_use"), None
)

# Segunda requisição - Inclui o bloco de pensamento e o resultado da ferramenta
continuation = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"},
        # Observe que o thinking_block é passado junto com o tool_use_block
        {"role": "assistant", "content": [thinking_block, tool_use_block]},
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": tool_use_block.id,
                    "content": f"Current temperature: {weather_data['temperature']}°F",
                }
            ],
        },
    ],
)

for block in continuation.content:
    if block.type == "text":
        print(block.text)



Pensamento intercalado

O pensamento intercalado permite que o Claude pense entre chamadas de ferramentas, raciocinando sobre os resultados das ferramentas antes de decidir o próximo passo.

Em modelos mais antigos que usam pensamento estendido manual (modelos Claude 4, 4.5 e Sonnet 4.6), habilite o pensamento intercalado adicionando o cabeçalho beta interleaved-thinking-2025-05-14 à sua requisição de API:

import anthropic

client = anthropic.Anthropic()

calculator_tool = {
    "name": "calculator",
    "description": "Perform arithmetic calculations.",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "The math expression to evaluate.",
            }
        },
        "required": ["expression"],
    },
}

database_tool = {
    "name": "database_query",
    "description": "Query the product database.",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "The database query."}
        },
        "required": ["query"],
    },
}

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    tools=[calculator_tool, database_tool],
    messages=[
        {
            "role": "user",
            "content": "What's the total revenue if we sold 150 units of product A at $50 each?",
        }
    ],
    betas=["interleaved-thinking-2025-05-14"],
)

for block in response.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "tool_use":
        print(f"Tool call: {block.name}({block.input})")
    elif block.type == "text":
        print(f"Response: {block.text}")

Com o pensamento intercalado e APENAS com o pensamento intercalado (não o pensamento estendido manual regular), o budget_tokens pode exceder o parâmetro max_tokens, pois budget_tokens neste caso representa o orçamento total em todos os blocos de pensamento dentro de um turno do assistente.



Uso de ferramentas



Especificando ferramentas do cliente

As ferramentas do cliente são especificadas no parâmetro de nível superior tools da requisição de API. Cada definição de ferramenta inclui:

{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}



Melhores práticas para definições de ferramentas

Forneça descrições extremamente detalhadas. Este é de longe o fator mais importante no desempenho das ferramentas. Suas descrições devem explicar cada detalhe sobre a ferramenta, incluindo:

• O que a ferramenta faz
• Quando ela deve ser usada (e quando não deve)
• O que cada parâmetro significa e como ele afeta o comportamento da ferramenta
• Quaisquer ressalvas ou limitações importantes

Considere usar input_examples para ferramentas complexas. Para ferramentas com objetos aninhados, parâmetros opcionais ou entradas sensíveis a formato, você pode fornecer exemplos concretos usando o campo input_examples (beta). Isso ajuda o Claude a entender os padrões de entrada esperados. Consulte Fornecendo exemplos de uso de ferramentas para detalhes.

Exemplo de uma boa descrição de ferramenta:

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}



Controlando a saída do Claude



Forçando o uso de ferramentas

Você pode forçar o Claude a usar uma ferramenta específica especificando a ferramenta no campo tool_choice:

tool_choice = {"type": "tool", "name": "get_weather"}

Ao trabalhar com o parâmetro tool_choice, existem quatro opções possíveis:

• auto permite que o Claude decida se deve chamar alguma das ferramentas fornecidas ou não (padrão).
• any diz ao Claude que ele deve usar uma das ferramentas fornecidas.
• tool força o Claude a sempre usar uma ferramenta específica.
• none impede o Claude de usar qualquer ferramenta.



Saída JSON

As ferramentas não precisam necessariamente ser funções do cliente. Você pode usar ferramentas sempre que quiser que o modelo retorne uma saída JSON que siga um esquema fornecido.



Cadeia de pensamento

Ao usar ferramentas, o Claude frequentemente mostra sua "cadeia de pensamento", ou seja, o raciocínio passo a passo que ele usa para decompor o problema e decidir quais ferramentas usar.

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}



Uso paralelo de ferramentas

Por padrão, o Claude pode usar múltiplas ferramentas para responder a uma consulta do usuário. Você pode desabilitar esse comportamento definindo disable_parallel_tool_use=true.



Lidando com blocos de conteúdo tool_use e tool_result



Lidando com resultados de ferramentas do cliente

A resposta tem um stop_reason de tool_use e um ou mais blocos de conteúdo tool_use que incluem:

• id: Um identificador único para este bloco específico de uso de ferramenta.
• name: O nome da ferramenta sendo usada.
• input: Um objeto contendo a entrada sendo passada para a ferramenta.

Quando você recebe uma resposta de uso de ferramenta, você deve:

1. Extrair o name, id e input do bloco tool_use.
2. Executar a ferramenta real em sua base de código correspondente a esse nome de ferramenta.
3. Continuar a conversa enviando uma nova mensagem com um tool_result:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}



Lidando com o motivo de parada max_tokens

Se a resposta do Claude for cortada porque atingiu o limite de max_tokens durante o uso de ferramentas, tente a requisição novamente com um valor de max_tokens maior.



Lidando com o motivo de parada pause_turn

Ao usar ferramentas de servidor, como busca na web, a API pode retornar um motivo de parada pause_turn. Continue a conversa passando a resposta pausada de volta como está em uma requisição subsequente.



Solucionando erros



Erro de execução de ferramenta

Se a própria ferramenta lançar um erro durante a execução, retorne a mensagem de erro com "is_error": true:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}



Nome de ferramenta inválido

Se a tentativa do Claude de usar uma ferramenta for inválida (por exemplo, faltando parâmetros obrigatórios), tente a requisição novamente com valores de description mais detalhados em suas definições de ferramentas.



Streaming de mensagens

Ao criar uma Message, você pode definir "stream": true para transmitir incrementalmente a resposta usando "server-sent events" (eventos enviados pelo servidor), ou SSE.



Streaming com SDKs

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    model="claude-opus-5",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)



Tipos de eventos

Cada evento enviado pelo servidor inclui um tipo de evento nomeado e dados JSON associados. Cada stream usa o seguinte fluxo de eventos:

1. message_start: contém um objeto Message com content vazio.
2. Uma série de blocos de conteúdo, cada um com content_block_start, um ou mais eventos content_block_delta e content_block_stop.
3. Um ou mais eventos message_delta, indicando mudanças de nível superior no objeto Message final.
4. Um evento message_stop final.

Aviso: As contagens de tokens mostradas no campo usage do evento message_delta são cumulativas.



Tipos de delta de bloco de conteúdo



Delta de texto

{
  "type": "content_block_delta",
  "index": 0,
  "delta": { "type": "text_delta", "text": "Hello frien" }
}



Delta de JSON de entrada

Para blocos de conteúdo tool_use, os deltas são strings JSON parciais:

{"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}



Delta de pensamento

Ao usar pensamento com streaming:

{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "type": "thinking_delta",
    "thinking": "Let me solve this step by step..."
  }
}



Exemplo básico de requisição com streaming

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}

event: message_stop
data: {"type": "message_stop"}