Como Usar a API Claude Opus 5?

Claude Opus 5 foi lançado em 24 de julho de 2026, e a Anthropic agora direciona os desenvolvedores a ele primeiro: a documentação recomenda começar com Claude Opus 5 quando você não tiver certeza de qual modelo usar. O ID exato do modelo na API é claude-opus-5, sem sufixo de data.

Experimente o Apidog hoje

Este guia mostra o fluxo completo: criar uma chave, enviar a primeira solicitação, usar streaming, integrar ferramentas, configurar pensamento adaptativo e effort, além de validar o objeto usage para confirmar o funcionamento do cache de prompt. Todas as chamadas usam HTTP e JSON, para que você possa construí-las e depurá-las no Apidog antes de levá-las ao código da aplicação.

Se você estiver migrando um serviço existente, leia também o guia completo de migração do Opus 4.8 para o Opus 5.

Antes da primeira chamada: duas mudanças impactantes

1. O pensamento é ativado por padrão

No Opus 4.8, uma requisição sem o campo thinking era executada sem pensamento. No Opus 5, a mesma requisição usa pensamento adaptativo.

O campo max_tokens continua sendo um limite rígido que cobre tokens de pensamento e tokens de resposta juntos. Portanto, um payload migrado do Opus 4.8 pode passar a truncar a resposta no meio.

Se seu max_tokens foi dimensionado apenas para a saída visível, aumente-o.

2. Desativar o pensamento limita o esforço

A combinação abaixo retorna 400:

{
  "thinking": {"type": "disabled"},
  "output_config": {"effort": "xhigh"}
}

Com thinking: {"type": "disabled"}, o maior nível permitido é high. Você tem duas opções:

• Manter o pensamento ativado e reduzir effort para controlar custo.
• Desativar o pensamento e limitar effort a high.

A recomendação da Anthropic é manter o pensamento ativado. Com ele desativado, o Opus 5 pode escrever chamadas de ferramenta como texto simples — elas não são executadas — e também pode expor tags <thinking> na resposta visível.

As duas mudanças estão documentadas no guia de migração de modelos da Anthropic.

Passo 1: obtenha uma chave de API

Faça login na Plataforma de Desenvolvedores Claude, abra as configurações da organização, acesse a seção de chaves de API e crie uma nova chave.

Copie a chave imediatamente: ela não poderá ser exibida novamente.

Armazene-a em uma variável de ambiente:

export ANTHROPIC_API_KEY="sk-ant-..."

Evite colar chaves no código ou em coleções compartilhadas. Em clientes GUI, use variáveis de ambiente. No Apidog, por exemplo, crie ambientes como Local, Staging e Production, defina a variável ANTHROPIC_API_KEY e use {{ANTHROPIC_API_KEY}} no cabeçalho.

Você também precisa adicionar créditos de cobrança antes que as solicitações sejam bem-sucedidas. As taxas do Opus 5 são de US$ 5 por milhão de tokens de entrada e US$ 25 por milhão de tokens de saída, iguais às do Opus 4.8. Consulte o detalhamento completo de preços para taxas de cache, lote e modo rápido.

Passo 2: envie sua primeira solicitação

Use o endpoint:

POST https://api.anthropic.com/v1/messages

Inclua estes três cabeçalhos:

• x-api-key
• anthropic-version
• content-type

Exemplo com curl:

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-opus-5",
    "max_tokens": 4096,
    "messages": [
      {
        "role": "user",
        "content": "Explain the difference between a 429 and a 529 from an API perspective."
      }
    ]
  }'

O valor 4096 é intencionalmente maior que os 1024 comuns em exemplos básicos. Agora, os tokens de pensamento compartilham o mesmo orçamento da resposta.

Exemplo equivalente com o SDK oficial para Python:

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Explain the difference between a 429 and a 529 from an API perspective.",
        }
    ],
)

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

Não trate message.content como um único texto. A resposta contém um array de blocos tipados. Com pensamento ativado, normalmente haverá um bloco thinking antes do bloco text.

Evite isto:

print(message.content[0].text)

Esse padrão pode falhar silenciosamente após a migração: a chamada retorna 200, mas o primeiro bloco pode não ser texto visível.

O Opus 5 tem:

• Janela de contexto padrão e máxima de 1M de tokens.
• Saída máxima de 128k tokens na API de Mensagens.
• Corte de conhecimento em maio de 2026.

Consulte a visão geral dos modelos e o explicador do Opus 5 para mais detalhes.

Passo 3: trabalhe com pensamento adaptativo

Pensamento adaptativo significa que o modelo decide quanto raciocínio interno uma solicitação exige. Você não configura um orçamento específico de pensamento; você direciona o comportamento com effort.

Ao implementar, siga estas regras:

• Analise blocos por tipo. Use block.type == "text" para a resposta visível e block.type == "thinking" se precisar registrar raciocínio.
• Reenvie blocos de pensamento sem alterações. Em conversas de múltiplas rodadas ou fluxos com ferramentas, anexe todo o array content do assistente ao histórico.
• Orce max_tokens para pensamento e resposta. Verifique stop_reason nos testes para detectar truncamentos.

Exemplo para desativar o pensamento:

{
  "model": "claude-opus-5",
  "max_tokens": 4096,
  "thinking": {"type": "disabled"},
  "output_config": {"effort": "high"},
  "messages": [
    {
      "role": "user",
      "content": "Return only the HTTP status code."
    }
  ]
}

O effort é limitado a high nesse exemplo. Se você alterar para xhigh ou max, a API retornará 400.

Passo 4: controle custo com output_config.effort

O campo effort fica dentro de output_config e aceita:

low
medium
high
xhigh
max

O padrão é high.

Exemplo usando xhigh:

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-opus-5",
    "max_tokens": 65536,
    "output_config": {"effort": "xhigh"},
    "messages": [
      {
        "role": "user",
        "content": "Refactor this handler to stream responses and keep backpressure."
      }
    ]
  }'

Antes de escolher um nível, considere estes pontos:

1. Os níveis foram recalibrados. Não reutilize diretamente as configurações do Opus 4.8. Segundo a Anthropic, low e medium são significativamente mais capazes no Opus 5.

2. xhigh é o ponto de partida recomendado para código e tarefas agênticas. Nesse nível, max_tokens se torna ainda mais importante. Para rodadas longas, 65536 é um limite inicial razoável.

3. Reduzir esforço não encurta necessariamente a resposta visível. Menos esforço reduz pensamento interno. Para respostas mais curtas, peça explicitamente isso no prompt.

Veja o guia detalhado do parâmetro effort para uma metodologia de avaliação.

Passo 5: transmita a resposta com streaming

Adicione "stream": true ao payload para receber eventos enviados pelo servidor (SSE) em vez de um único JSON.

with client.messages.stream(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Draft a retry policy for a flaky upstream.",
        }
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

    final = stream.get_final_message()
    print("\n\nusage:", final.usage)

A sequência SSE é:

message_start
content_block_start
content_block_delta
content_block_stop
message_delta
message_stop

Com pensamento ativado, você recebe blocos diferentes:

• Deltas thinking_delta para o bloco de pensamento.
• Deltas text_delta para a resposta visível.

Não escreva todos os deltas no mesmo buffer da interface. Caso contrário, você pode exibir raciocínio interno para o usuário final.

Para inspecionar o SSE sem construir um cliente, use o Apidog. Ele renderiza os eventos à medida que chegam, o que ajuda a validar limites de blocos e sua estratégia de parsing antes da implementação.

Passo 6: adicione uso de ferramentas

Defina ferramentas no array tools. Quando o modelo quiser executar uma ferramenta, a resposta terá:

• stop_reason: "tool_use"
• Um bloco de conteúdo do tipo tool_use

Execute a ferramenta no seu backend e devolva o resultado como um bloco tool_result em uma nova mensagem do usuário.

tools = [
    {
        "name": "get_order_status",
        "description": "Look up the current status of a customer order by ID.",
        "input_schema": {
            "type": "object",
            "properties": {
                "order_id": {
                    "type": "string",
                    "description": "The order ID, e.g. A-10293",
                }
            },
            "required": ["order_id"],
        },
    }
]

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    tools=tools,
    messages=[
        {
            "role": "user",
            "content": "What's the status of order A-10293?",
        }
    ],
)

if message.stop_reason == "tool_use":
    call = next(block for block in message.content if block.type == "tool_use")
    result = get_order_status(**call.input)

    follow_up = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        tools=tools,
        messages=[
            {
                "role": "user",
                "content": "What's the status of order A-10293?",
            },
            {
                "role": "assistant",
                "content": message.content,
            },
            {
                "role": "user",
                "content": [
                    {
                        "type": "tool_result",
                        "tool_use_id": call.id,
                        "content": result,
                    }
                ],
            },
        ],
    )

O ponto crítico é este:

{"role": "assistant", "content": message.content}

Passe message.content diretamente. Não reconstrua manualmente a mensagem do assistente, pois isso pode remover blocos de pensamento e degradar o loop agêntico.

Detalhes do Opus 5 relevantes para agentes:

• A sobrecarga do prompt de sistema para uso de ferramentas é menor que no Opus 4.8: 286 tokens com tool_choice igual a auto ou none, contra 290 no Opus 4.8 e 675 no Opus 4.7.
• O cabeçalho beta mid-conversation-tool-changes-2026-07-01 permite adicionar ou remover ferramentas entre turnos sem invalidar o cache do prompt.
• O Opus 5 delega a subagentes mais facilmente que o Opus 4.8. Em cargas de trabalho sensíveis a custo, explicite limites no prompt de sistema.

Passo 7: leia usage para validar acertos de cache

Cada resposta inclui um objeto usage:

{
  "input_tokens": 84,
  "cache_creation_input_tokens": 6421,
  "cache_read_input_tokens": 0,
  "output_tokens": 913
}

Use cache_control para marcar conteúdo cacheável:

{
  "model": "claude-opus-5",
  "max_tokens": 4096,
  "system": [
    {
      "type": "text",
      "text": "<your long, stable instructions and reference material>",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "Question one."
    }
  ]
}

Valide o comportamento esperado:

• Primeira chamada: cache_creation_input_tokens > 0 e cache_read_input_tokens = 0.
• Chamadas seguintes com o mesmo prefixo: cache_read_input_tokens > 0.

Se isso não acontecer, o prefixo não é byte a byte idêntico ou está abaixo do tamanho mínimo.

No Opus 5, o cache de prompt começa a partir de 512 tokens, abaixo dos 1.024 tokens do Opus 4.8. Leituras de cache custam US$ 0,50 por milhão de tokens, contra US$ 5 por milhão de tokens de entrada na taxa base.

Inclua uma asserção em cache_read_input_tokens na sua suíte de testes. Assim, uma alteração de prompt que invalide o cache aparece como falha de teste, e não como surpresa na fatura.

Para outras estratégias, veja o guia sobre como reduzir sua fatura da API Claude.

Teste e depure todo o fluxo no Apidog

Cada etapa deste artigo é uma requisição HTTP com:

• Cabeçalhos de autenticação.
• Corpo JSON.
• Fluxo SSE opcional.
• Resposta que precisa ser validada.

O Apidog permite enviar, armazenar e testar essas requisições. A inferência continua acontecendo na Anthropic; o Apidog não executa nem roteia modelos.

Uma configuração prática para começar:

1. Crie a requisição. Use POST https://api.anthropic.com/v1/messages, os três cabeçalhos obrigatórios e uma variável de ambiente para a chave.

2. Salve-a em uma coleção. Isso cria uma referência reutilizável para toda a equipe.

3. Duplique por nível de esforço. Crie versões com output_config.effort em low, medium, high e xhigh. Envie o mesmo prompt em cada uma e compare qualidade, latência e uso de tokens.

4. Inspecione o streaming SSE. Ative "stream": true e confirme que sua implementação separa blocos de pensamento e texto.

5. Inspecione payloads de ferramentas. Quando stop_reason for tool_use, valide o objeto input retornado pelo modelo. Isso ajuda a identificar schemas muito permissivos.

6. Adicione asserções. Verifique se stop_reason não é max_tokens e se cache_read_input_tokens é maior que zero em chamadas repetidas.

Baixe o Apidog para acompanhar o fluxo. O mesmo padrão de coleção funciona com outros modelos Claude, incluindo Sonnet 5 e suas solicitações existentes do Opus 4.8.

Erros e pegadinhas que você realmente encontrará

• 400 com thinking: disabled e esforço xhigh ou max. Reduza o esforço para high ou reative o pensamento.

• 400 em parâmetros de amostragem. temperature, top_p e top_k com valores não padrão continuam retornando 400, como no Opus 4.8. Direcione o comportamento pelo prompt de sistema.

• Respostas truncadas. stop_reason: "max_tokens" com pensamento ativado significa que o limite foi consumido por pensamento e saída. Aumente max_tokens.

• Tier de Prioridade não é suportado no Opus 5. O Opus 4.8 continua suportando-o. Se sua estratégia de capacidade depende desse recurso, resolva isso antes de migrar tráfego.

• Mensagens de sistema no meio da conversa funcionam. Uma entrada role: "system" dentro de messages é aceita no Opus 5, enquanto no Opus 4.8 retornava 400.

• Superverificação. O Opus 5 já verifica o próprio trabalho sem ser solicitado. Remova instruções herdadas como “verifique novamente sua resposta antes de responder” se elas não agregarem valor à sua avaliação.

O limite honesto

O Opus 5 não é o topo da pilha Claude. O Fable 5 mantém a designação de “mais capaz amplamente lançado” da Anthropic, a US$ 10 por milhão de tokens de entrada e US$ 50 por milhão de tokens de saída.

O Opus 5 também fica atrás do Mythos 5 em exploração de cibersegurança e pesquisa autônoma de biologia, segundo a própria Anthropic.

As alegações de benchmark de lançamento — aproximadamente o dobro do Opus 4.8 no Frontier-Bench v0.1, cerca de 3x o próximo melhor modelo no ARC-AGI 3 e dentro de 0,5% do Fable 5 no CursorBench 3.2 — são números da Anthropic e não haviam sido reproduzidos independentemente até 25 de julho de 2026.

Trate esses números como resultados fornecidos pelo fabricante e execute suas próprias avaliações. Veja a comparação entre Opus 5 e Fable 5 e o post de lançamento da Anthropic.

FAQ

Qual é o ID do modelo para Claude Opus 5?

claude-opus-5, exatamente, sem sufixo de data.

No Amazon Bedrock, é anthropic.claude-opus-5. O Google Cloud e a Plataforma Claude na AWS usam o ID proprietário.

Por que minha solicitação do Opus 4.8 começou a truncar no Opus 5?

Porque o pensamento agora é ativado por padrão. max_tokens limita conjuntamente os tokens de pensamento e de resposta.

Aumente max_tokens e verifique se stop_reason é "max_tokens".

Por que recebo 400 ao desativar o pensamento?

Provavelmente porque você combinou:

{"thinking": {"type": "disabled"}}

com:

{"output_config": {"effort": "xhigh"}}

Limite o esforço a high ou mantenha o pensamento ativado.

Preciso de um cabeçalho beta para usar a janela de contexto de 1M?

Não. No Opus 5, 1M de tokens é o padrão e o máximo, sem cabeçalho beta e sem preço adicional de contexto longo.

Para chegar a 300k de saída na API de Lote, use o cabeçalho beta output-300k-2026-03-24. A API de Mensagens limita a saída a 128k.

Posso reutilizar minhas configurações de esforço do Opus 4.8?

Não é recomendado. Os níveis foram recalibrados, e low e medium são significativamente mais fortes no Opus 5.

Execute uma nova varredura no seu próprio conjunto de avaliação.

O Apidog executa o modelo?

Não. O Apidog envia, inspeciona e testa a requisição HTTP. A inferência ocorre na Anthropic.

Ele ajuda a gerenciar chaves, streaming, payloads de chamadas de ferramenta e asserções de resposta ao redor da chamada.