Claude Platform Docs
Documentation

Introdução ao uso da API para Claude

Este guia foi criado para fornecer a Claude o básico sobre o uso da Claude API. Ele traz explicações e exemplos de IDs de modelo/da API básica de mensagens, uso de ferramentas, streaming, pensamento e nada mais.

Introdução ao uso da API para Claude

Este guia foi criado para fornecer a Claude o básico sobre o uso da Claude API. Ele traz explicações e exemplos de IDs de modelo/da API básica de mensagens, uso de ferramentas, streaming, pensamento e nada mais.

Modelos

Recommended default for most work, including complex agentic coding: Claude Opus 5.5: claude-opus-5-5
Step up for the hardest long-running agentic and research tasks, at 2x Claude Opus 5.5 pricing: Claude Fable 5.2: claude-fable-5-2
Previous Opus model: Claude Opus 5: claude-opus-5
Smart model: Claude Sonnet 5.5: claude-sonnet-5-5
Previous Sonnet model: Claude Sonnet 5: claude-sonnet-5
For fast, cost-effective tasks: Claude Haiku 5.5: claude-haiku-5-5
Previous Haiku model: Claude Haiku 4.5: claude-haiku-4-5-20251001

Chamando a API

Requisição e resposta básicas

import anthropic

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

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 gerados de fato por 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.

import anthropic

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)

Preenchendo previamente a resposta de Claude

Você pode preencher previamente parte da resposta de Claude na última posição da lista de mensagens de entrada. Use essa técnica para moldar a resposta de Claude. O exemplo a seguir usa "max_tokens": 1 para obter de Claude uma única resposta de múltipla escolha.

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 nas requisições. 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 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(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-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(next(block.text for block in message_from_url.content if block.type == "text"))

Pensamento

O pensamento às vezes pode ajudar Claude em tarefas muito difíceis. O mecanismo atual é o pensamento adaptativo (thinking: {"type": "adaptive"}): Claude determina 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 posteriores e no Claude Mythos Preview, o pensamento fica ativado por padrão quando o parâmetro thinking é omitido.

O pensamento é suportado nos seguintes modelos:

  • Claude Fable 5.2 (claude-fable-5-2, apenas pensamento adaptativo, sempre ativado)
  • Claude Mythos 5.2 (claude-mythos-5-2, apenas pensamento adaptativo, sempre ativado)
  • Claude Opus 5.5 (claude-opus-5-5, apenas pensamento adaptativo, sempre ativado)
  • Claude Sonnet 5.5 (claude-sonnet-5-5, apenas pensamento adaptativo, ativado por padrão; thinking: {"type": "disabled"} retorna um erro 400, então envie thinking: {"type": "between_tools"} para desativar o pensamento inicial)
  • Claude Haiku 5.5 (claude-haiku-5-5, apenas pensamento adaptativo, ativado por padrão)
  • Claude Fable 5.1 (claude-fable-5-1, apenas pensamento adaptativo, sempre ativado)
  • Claude Mythos 5.1 (claude-mythos-5-1, apenas pensamento adaptativo, sempre ativado)
  • Claude Fable 5 (claude-fable-5, apenas pensamento adaptativo, sempre ativado)
  • Claude Mythos 5 (claude-mythos-5, apenas pensamento adaptativo, sempre ativado)
  • 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 (, 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, descontinuado, 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 nos quais 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-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 contém blocos de pensamento resumidos e blocos de texto
for block in response.content:
    match block.type:
        case "thinking":
            print(f"\nThinking summary: {block.thinking}")
        case "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 a 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 Claude pode usar em 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 o pensamento intercalado, budget_tokens deve ser menor que max_tokens para que Claude tenha espaço para escrever sua resposta após a conclusão do pensamento.

Pensamento com uso de ferramentas

O pensamento pode ser usado junto com o “tool use” (uso de ferramentas), permitindo que Claude raciocine sobre a seleção de ferramentas e o processamento dos resultados.

Limitações importantes:

  1. Limitação de escolha de ferramenta: Com o pensamento estendido manual (thinking: {"type": "enabled"}), apenas tool_choice: {"type": "auto"} (padrão) ou tool_choice: {"type": "none"} é suportado. O pensamento adaptativo aceita o uso forçado de ferramentas, exceto nos modelos listados em Forçando o uso de ferramentas. Onde é aceita, uma chamada de ferramenta forçada ignora o pensamento: a resposta começa com a chamada de ferramenta e não tem bloco thinking.
  2. Preservação dos blocos de pensamento: Durante o uso de ferramentas, você deve enviar os blocos thinking de volta à API para a última mensagem do assistente.

Preservando blocos de pensamento

Python
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-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-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 Claude pense entre chamadas de ferramentas, raciocinando sobre os resultados das ferramentas antes de determinar o próximo passo.

Em modelos mais antigos que usam pensamento estendido manual (modelos Claude 4, 4.5 e Sonnet 4.6), ative 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:
    match block.type:
        case "thinking":
            print(f"Thinking: {block.thinking}")
        case "tool_use":
            print(f"Tool call: {block.name}({block.input})")
        case "text":
            print(f"Response: {block.text}")

Com o pensamento intercalado e SOMENTE com o pensamento intercalado (não com o pensamento estendido manual comum), o budget_tokens pode exceder o parâmetro max_tokens, pois budget_tokens nesse caso representa o orçamento total de 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:

ParâmetroDescrição
nameO nome da ferramenta. Deve corresponder à regex ^[a-zA-Z0-9_-]{1,128}$.
descriptionUma descrição detalhada em texto simples do que a ferramenta faz, quando deve ser usada e como se comporta.
input_schemaUm objeto JSON Schema que define os parâmetros esperados para a ferramenta.
{
  "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"]
  }
}

Boas 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 todos os detalhes 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 ao formato, você pode fornecer exemplos concretos usando o campo input_examples (beta). Isso mostra a Claude os padrões de entrada esperados. Consulte Fornecendo exemplos de uso de ferramentas para mais 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 de Claude

Forçando o uso de ferramentas

Você pode forçar 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, há quatro opções possíveis:

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

No Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 e Claude Mythos 5.1, any e tool retornam um erro 400. Mantenha tool_choice como auto e defina "strict": true na definição da ferramenta para garantir que qualquer chamada feita por Claude corresponda ao input_schema da ferramenta. Consulte Uso estrito de ferramentas.

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 schema fornecido.

Uso paralelo de ferramentas

Por padrão, Claude pode usar várias ferramentas para responder a uma consulta do usuário. Você pode desativar esse comportamento definindo disable_parallel_tool_use=true.

Lidando com blocos de conteúdo de uso de ferramentas e de resultado de ferramentas

Lidando com resultados de ferramentas do cliente

A resposta tem um stop_reason igual a 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 ferramentas.
  • name: O nome da ferramenta sendo usada.
  • input: Um objeto contendo a entrada sendo passada para a ferramenta.
{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

Ao receber uma resposta de uso de ferramentas, você deve:

  1. Extrair 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 de Claude for cortada por atingir 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 do servidor, como a pesquisa na web, a API pode retornar um motivo de parada pause_turn. Continue a conversa enviando a resposta pausada de volta, sem alterações, em uma requisição subsequente.

Solução de erros

Erro de execução da ferramenta

Se a própria ferramenta gerar 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 de 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 nas definições das suas ferramentas.

Streaming de mensagens

Ao criar uma Message, você pode definir "stream": true para fazer o streaming incremental da 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-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 alterações 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 de streaming

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5-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"}

Esta página foi útil?