Blog

Como Usar a API Claude Opus 5?

Guia passo a passo da API Claude Opus 5: obtenha uma chave, envie sua primeira chamada com o ID do modelo claude-opus-5, transmita respostas, adicione o uso de ferramentas, ajuste o esforço e leia o uso para acertos de cache.

Ashley Innocent

Ashley Innocent

25 julho 2026

Como Usar a API Claude Opus 5?

Apidog para empresas

Implantação local

SSO & RBAC

Conforme SOC 2

Explorar Apidog Enterprise

Claude Opus 5 foi lançado em 24 de julho de 2026, e a Anthropic agora direciona os desenvolvedores a ele primeiramente: a documentação diz que, se você não tiver certeza de qual modelo usar, comece com o Claude Opus 5. O ID do modelo da API é a string exata claude-opus-5, sem sufixo de data.

Este guia percorre todo o caminho: obtendo uma chave, enviando uma primeira solicitação, streaming, uso de ferramentas, pensamento adaptativo, o parâmetro effort e a leitura do objeto usage para confirmar que seu cache de prompt está funcionando. Cada solicitação aqui é HTTP simples com JSON de entrada e saída, para que você possa construí-lo e depurá-lo no Apidog antes de integrá-lo ao código do aplicativo.

botão

Duas mudanças do Opus 4.8 vão te pegar na primeira chamada, então elas vêm antes de qualquer outra coisa. Se você estiver migrando um serviço existente em vez de começar do zero, leia o guia completo de migração do Opus 4.8 para o Opus 5 junto com este.

Antes da sua primeira chamada: duas mudanças impactantes

1. O pensamento está ativado por padrão. No Opus 4.8, uma solicitação sem o campo thinking era executada sem pensar. No Opus 5, essa mesma solicitação é executada com pensamento adaptativo. max_tokens ainda é um limite rígido para tokens de pensamento e tokens de resposta combinados, então um corpo de solicitação que você copiou de uma integração 4.8 funcional agora pode truncar no meio da resposta. Se seu max_tokens foi ajustado rigidamente em torno do comprimento de saída esperado, aumente-o.

2. Desabilitar o pensamento limita seu nível de esforço. Enviar thinking: {"type": "disabled"} junto com um esforço de xhigh ou max retorna um 400. A Anthropic aplica isso por solicitação, então falha imediatamente em vez de degradar silenciosamente. A solução é escolher um: manter o pensamento ativado e diminuir o esforço para controlar o custo, ou manter o pensamento desativado e limitar o esforço a high.

O próprio conselho da Anthropic é a primeira opção. Com o pensamento desativado, o Opus 5 ocasionalmente escreve chamadas de ferramenta como texto simples (elas nunca são executadas, e o texto vazado polui as rodadas posteriores em um loop de agente) e às vezes vaza tags <thinking> para a saída visível. Manter o pensamento ativado e diminuir o esforço evita ambos.

Ambas as mudanças estão documentadas no guia de migração de modelo da Anthropic.

Passo 1: Obtenha uma chave de API

Faça login na Plataforma de Desenvolvedores Claude, abra a seção de chaves de API das configurações da sua organização e crie uma chave. Copie-a uma vez; você não poderá lê-la novamente mais tarde.

Armazene-a em uma variável de ambiente em vez de colá-la no código:

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

Se você estiver testando em um cliente GUI, coloque a chave em uma variável de ambiente também. No Apidog, isso significa criar um ambiente (Local, Staging, Production) com uma variável ANTHROPIC_API_KEY, e então referenciar {{ANTHROPIC_API_KEY}} no cabeçalho. Suas solicitações salvas permanecem compartilháveis com a equipe e o segredo nunca vai parar em uma exportação de coleção.

Captura de tela do Apidog mostrando variáveis de ambiente e configuração da chave de API

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

Passo 2: Envie sua primeira solicitação

O endpoint é POST https://api.anthropic.com/v1/messages. Três cabeçalhos importam: sua chave, a versão da API e o tipo de conteúdo.

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."}
    ]
  }'

Observe o valor de max_tokens. 4096 é um aumento deliberado em relação aos 1024 que você vê na maioria dos snippets iniciais, porque os tokens de pensamento agora vêm do mesmo orçamento.

O equivalente em Python através do SDK oficial:

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)

Esse loop sobre message.content não é decoração. O content da resposta é um array de blocos tipados, e com o pensamento ativado, você agora verá um bloco thinking antes do bloco text. O código que assumia que content[0].text era a resposta falha no Opus 5. Esta é a falha de atualização mais comum, e é fácil de não perceber porque a solicitação ainda retorna um 200.

Algumas especificações que vale a pena ter em mente enquanto você constrói: o Opus 5 tem uma janela de contexto de 1M de tokens como padrão e máximo (sem cabeçalho beta, sem prêmio de preço de contexto longo), uma saída máxima de 128k na API de Mensagens e um corte de conhecimento de maio de 2026. A visão geral dos modelos tem a tabela completa, e nosso explicador do Opus 5 cobre o restante da folha de especificações.

Passo 3: Trabalhe com pensamento adaptativo

Pensamento adaptativo significa que o modelo decide quanto raciocínio interno uma solicitação merece. Você não define um orçamento de tokens. Você o direciona com esforço, o que será abordado na próxima etapa.

O que você precisa lidar no código:

Para desativar completamente 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 esforço é limitado a high nessa solicitação de propósito. Aumente-o para xhigh e você obterá o 400 descrito acima.

Passo 4: Controle o custo com output_config.effort

O campo effort está sob output_config e aceita low, medium, high, xhigh ou max. O padrão é high. Este é o parâmetro que a cobertura principal descreveu como um alternador entre custo e capacidade; na API é uma string em seu corpo de solicitação.

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."}
    ]
  }'

Três coisas a saber antes de ajustá-lo.

Passo 5: Transmita a resposta

Adicione "stream": true e o endpoint retornará eventos enviados pelo servidor em vez de um corpo JSON único.

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 bruta é message_start, então content_block_start / content_block_delta / content_block_stop por bloco, então message_delta contendo stop_reason e a contagem final de tokens de saída, e então message_stop.

Com o pensamento ativado, você obtém dois blocos de conteúdo sendo transmitidos em ordem: um bloco de pensamento cujos deltas chegam como thinking_delta, e então o bloco de texto com text_delta. Uma UI que renderiza cada delta no mesmo buffer imprimirá o raciocínio do modelo para seus usuários. Direcione-os separadamente desde o início.

O streaming também é onde um cliente GUI ganha seu lugar, porque ler SSE bruto em um terminal é miserável. O Apidog renderiza o fluxo de eventos à medida que chega, para que você possa observar os limites dos blocos e confirmar suas suposições de parsing antes de escrever uma única linha de código do manipulador.

Passo 6: Adicione o uso de ferramentas

As definições de ferramentas vão em um array tools. O modelo responde com stop_reason: "tool_use" e um bloco de conteúdo tool_use; você executa a ferramenta e envia o resultado de volta 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(b for b in message.content if b.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}
            ]},
        ],
    )

Passar message.content diretamente como a vez do assistente é o que preserva o bloco de pensamento. Não reconstrua essa vez manualmente.

Dois detalhes do Opus 5 que importam para agentes. A sobrecarga do prompt do sistema de uso de ferramentas é menor do que no Opus 4.8: 286 tokens com tool_choice definido como auto ou none, contra 290 no 4.8 e 675 no Opus 4.7. Pequeno por solicitação, mas significativo em um milhão de turnos de agente. E há um cabeçalho beta, mid-conversation-tool-changes-2026-07-01, que permite adicionar ou remover ferramentas entre turnos sem invalidar o cache do prompt.

O Opus 5 também delega a subagentes mais facilmente do que o 4.8. Em cargas de trabalho sensíveis ao custo, defina isso explicitamente no seu prompt de sistema em vez de descobrir na fatura.

Passo 7: Leia o objeto de uso para acertos de cache

Cada resposta carrega um objeto usage. É a única maneira honesta de confirmar que seu cache de prompt está funcionando.

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

Para armazenar um bloco em cache, marque-o com cache_control:

{
  "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."}]
}
```

Primeira chamada: cache_creation_input_tokens é diferente de zero e cache_read_input_tokens é 0. Segunda chamada com o mesmo prefixo: eles se invertem. Se nunca se inverterem, seu prefixo não é byte-idêntico ou está abaixo do mínimo.

Esse mínimo é a boa notícia no Opus 5. O cache de prompt agora entra em ação a partir de 512 tokens, abaixo dos 1.024 no Opus 4.8. Prompts que antes eram muito curtos para cache agora são armazenados em cache sem nenhuma alteração de código, e as leituras de cache são cobradas a $0.50 por milhão de tokens, contra uma taxa de entrada base de $5. Faça uma asserção em cache_read_input_tokens em sua suíte de testes para que uma edição de prompt que quebre silenciosamente o cache apareça como um teste falho em vez de uma fatura. Para mais alavancas, consulte nosso guia sobre como reduzir sua fatura da API Claude.

Teste e depure todo o fluxo no Apidog

Tudo acima é uma solicitação HTTP com cabeçalhos de autenticação, um corpo JSON, um fluxo SSE e uma resposta contra a qual você precisa fazer asserções. O Apidog é uma plataforma de desenvolvimento de API tudo-em-um, e este é exatamente o tipo de endpoint que ele lida: ele envia a solicitação, armazena a chave, renderiza o fluxo e testa a resposta. Ele não executa inferência ou roteia modelos; a chamada ainda vai para a Anthropic.

Captura de tela do Apidog mostrando uma solicitação e resposta de API

Uma configuração que se paga no primeiro dia:

  1. Crie a solicitação. POST https://api.anthropic.com/v1/messages com os três cabeçalhos, e a chave extraída de uma variável de ambiente em vez de colada diretamente.
  2. Salve-a em uma coleção. Sua equipe reutiliza um formato de solicitação conhecido e funcional em vez de cada pessoa reconstruí-lo a partir de um trecho de blog.
  3. Duplique-o por nível de esforço. Duplique a solicitação com output_config.effort definido como low, medium, high e xhigh, envie o mesmo prompt para cada um e compare a qualidade da saída, latência e contagens de tokens lado a lado. Esta é a varredura de esforço que a Anthropic pede para você executar, feita sem escrever um arnés.
  4. Observe o fluxo SSE. Ative "stream": true e leia os eventos conforme chegam para confirmar que você lida com blocos de pensamento e blocos de texto separadamente.
  5. Inspecione os payloads de chamadas de ferramenta. Quando stop_reason retorna como tool_use, o objeto input exato que o modelo produziu está lá, que é como você descobre que seu input_schema era muito solto.
  6. Faça asserções na resposta. Adicione verificações de que stop_reason não é max_tokens (seu canário de truncamento) e que cache_read_input_tokens está acima de zero em chamadas repetidas (seu canário de cache).

Baixe o Apidog se quiser acompanhar. O mesmo padrão de coleção funciona com qualquer modelo Claude, então você pode apontá-lo para o Sonnet 5 ou suas solicitações Opus 4.8 existentes e comparar o comportamento.

Erros e pegadinhas que você realmente encontrará

O limite honesto

O Opus 5 não é o topo da pilha Claude, e vale a pena dizer claramente. O Fable 5 ainda detém a designação de "mais capaz amplamente lançado" da Anthropic, a $10 por milhão de entradas e $50 por milhão de saídas. O Opus 5 também fica atrás do Mythos 5 em exploração de cibersegurança e pesquisa de biologia autônoma, o que a própria Anthropic afirma.

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, dentro de 0.5% do Fable 5 no CursorBench 3.2) são todos números próprios da Anthropic e não foram reproduzidas independentemente até 25 de julho de 2026. Leia-os como resultados executados pelo fornecedor e, em seguida, execute suas próprias avaliações. A comparação Opus 5 versus Fable 5 analisa onde a diferença de preço vale a pena e onde não vale, e o post de lançamento da Anthropic é a fonte primária para as próprias alegações.

FAQ

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar