Como Usar a API Claude Opus 4.7?

Resumo

Claude Opus 4.7 (claude-opus-4-7) é o modelo GA mais capaz da Anthropic. Ele suporta uma janela de contexto de 1M tokens, saída máxima de 128K, pensamento adaptativo, um novo nível de esforço xhigh, orçamentos de tarefas, visão de alta resolução (3.75 MP) e uso de ferramentas. Este guia abrange a configuração da API, autenticação e exemplos de código funcionais em Python, TypeScript e cURL para cada capacidade principal.

Introdução

A Anthropic lançou o Claude Opus 4.7 em 16 de abril de 2026. É o modelo mais poderoso da família Claude e a escolha ideal para raciocínio complexo, agentes autônomos e fluxos de trabalho que exigem muita visão.

Se você já usou a API do Claude antes, a maior parte da interface é familiar. Mas o Opus 4.7 introduz diversas novas capacidades e mudanças disruptivas que exigem atualizações de código. Orçamentos de pensamento estendidos se foram. Parâmetros de amostragem (temperature, top_p, top_k) se foram. O modo de pensamento agora suporta apenas o pensamento adaptativo, e ele está desativado por padrão.

Este guia o conduzirá por cada etapa: obtendo sua chave de API, fazendo sua primeira solicitação, usando pensamento adaptativo, enviando imagens de alta resolução, configurando o uso de ferramentas, configurando orçamentos de tarefas e transmitindo respostas. Cada exemplo é testado e pronto para copiar. Você também verá como depurar e testar suas chamadas de API com o Apidog, o que torna a inspeção de conversas de uso de ferramentas de múltiplas etapas muito mais fácil do que analisar JSON puro.

Começando

Obtenha sua Chave de API

1. Cadastre-se em console.anthropic.com
2. Navegue até API Keys no painel
3. Clique em Criar Chave e copie a chave
4. Armazene-a como uma variável de ambiente:

export ANTHROPIC_API_KEY="sk-ant-your-key-here"

Instale o SDK

Python:

pip install anthropic

TypeScript/Node.js:

npm install @anthropic-ai/sdk

Endpoint da API

Todas as solicitações vão para:

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

Cabeçalhos obrigatórios:

x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

Solicitação de Texto Básica

A chamada de API mais simples. Envie uma mensagem, obtenha uma resposta.

Python:

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain how HTTP/2 server push works in three sentences."}
    ]
)

print(message.content[0].text)

TypeScript:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const message = await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "Explain how HTTP/2 server push works in three sentences." }
  ],
});

console.log(message.content[0].text);

cURL:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-7",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Explain how HTTP/2 server push works in three sentences."}
    ]
  }'

Pensamento Adaptativo

O pensamento adaptativo é o único modo de pensamento suportado no Opus 4.7. Ele permite que Claude aloque tokens de raciocínio dinamicamente com base na complexidade da tarefa. Ele está desativado por padrão — você deve ativá-lo explicitamente.

Python:

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16384,
    thinking={
        "type": "adaptive",
        "display": "summarized"  # optional: see thinking output
    },
    messages=[
        {"role": "user", "content": "Analyze this algorithm's time complexity and suggest optimizations:\n\ndef find_pairs(arr, target):\n    result = []\n    for i in range(len(arr)):\n        for j in range(i+1, len(arr)):\n            if arr[i] + arr[j] == target:\n                result.append((arr[i], arr[j]))\n    return result"}
    ]
)

for block in message.content:
    if block.type == "thinking":
        print("Thinking:", block.thinking)
    elif block.type == "text":
        print("Response:", block.text)

Pontos chave:

• "type": "adaptive" habilita o pensamento. Não defina budget_tokens — isso retorna um erro 400 agora
• "display": "summarized" torna o conteúdo do pensamento visível na resposta. O padrão é "omitted"
• Combine com o parâmetro effort para controlar a profundidade do raciocínio

Usando o Parâmetro Effort

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16384,
    thinking={"type": "adaptive"},
    output_config={"effort": "xhigh"},  # xhigh | high | medium | low
    messages=[
        {"role": "user", "content": "Review this pull request for security vulnerabilities..."}
    ]
)

Níveis de esforço para Opus 4.7:

Visão de Alta Resolução

O Opus 4.7 aceita imagens de até 2.576 pixels na borda longa (3.75 megapixels). As coordenadas mapeiam 1:1 para pixels reais.

Python — analisar uma imagem de URL:

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://example.com/architecture-diagram.png"
                    }
                },
                {
                    "type": "text",
                    "text": "Describe this architecture diagram. List every service and the connections between them."
                }
            ]
        }
    ]
)

print(message.content[0].text)

Python — analisar uma imagem local com base64:

import base64

with open("screenshot.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                },
                {
                    "type": "text",
                    "text": "What UI bugs do you see in this screenshot?"
                }
            ]
        }
    ]
)

Imagens de maior resolução consomem mais tokens. Se você não precisa de fidelidade total, redimensione as imagens antes de enviá-las para reduzir custos.

Uso de Ferramentas (Chamada de Função)

O uso de ferramentas permite que Claude chame funções que você define. O Opus 4.7 tende a usar menos chamadas de ferramentas por padrão, preferindo o raciocínio. Aumente o nível de esforço para aumentar o uso de ferramentas.

Python:

import json

tools = [
    {
        "name": "get_weather",
        "description": "Get current weather for a city. Returns temperature, conditions, and humidity.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "City name, e.g. 'San Francisco'"
                },
                "units": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "Temperature unit"
                }
            },
            "required": ["city"]
        }
    }
]

messages = [
    {"role": "user", "content": "What's the weather like in Tokyo right now?"}
]

# First call — Claude requests a tool
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=tools,
    messages=messages,
)

# Process tool calls
if response.stop_reason == "tool_use":
    messages.append({"role": "assistant", "content": response.content})

    tool_results = []
    for block in response.content:
        if block.type == "tool_use":
            # Execute your function here
            result = {"temperature": 22, "conditions": "Partly cloudy", "humidity": 65}

            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": json.dumps(result)
            })

    messages.append({"role": "user", "content": tool_results})

    # Second call — Claude uses the tool result
    final_response = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    print(final_response.content[0].text)

Padrão de Loop Agente

def run_agent(system_prompt: str, tools: list, user_message: str) -> str:
    messages = [{"role": "user", "content": user_message}]

    while True:
        response = client.messages.create(
            model="claude-opus-4-7",
            max_tokens=16384,
            system=system_prompt,
            tools=tools,
            thinking={"type": "adaptive"},
            output_config={"effort": "xhigh"},
            messages=messages,
        )

        messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason != "tool_use":
            return "".join(
                block.text for block in response.content
                if hasattr(block, "text")
            )

        tool_results = []
        for block in response.content:
            if block.type == "tool_use":
                result = execute_tool(block.name, block.input)
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result,
                })

        messages.append({"role": "user", "content": tool_results})

Orçamentos de Tarefas (Beta)

Orçamentos de tarefas dão a Claude uma alocação de tokens para um loop de agente inteiro. O modelo vê uma contagem regressiva e encerra o trabalho à medida que o orçamento é consumido.

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 128000},
    },
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
    betas=["task-budgets-2026-03-13"],
)

Restrições principais:

• Orçamento mínimo: 20.000 tokens
• Consultivo, não um limite rígido — Claude pode exceder
• Diferente de max_tokens (limite máximo que o modelo não consegue ver)
• Requer o cabeçalho beta task-budgets-2026-03-13

Streaming de Respostas

Transmita respostas para saída em tempo real em interfaces de chat.

Python:

with client.messages.stream(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Write a Python function to parse CSV files with error handling."}
    ]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

TypeScript:

const stream = await client.messages.stream({
  model: "claude-opus-4-7",
  max_tokens: 4096,
  messages: [
    { role: "user", content: "Write a Python function to parse CSV files with error handling." }
  ],
});

for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}

Se você ativou o pensamento adaptativo com display: "summarized", os blocos de pensamento são transmitidos primeiro, seguidos pela resposta de texto. Sem display: "summarized", os usuários veem uma pausa durante o pensamento, seguida pela saída de texto.

Cache de Prompts

Reduza os custos para contexto repetido (prompts de sistema, documentos longos) armazenando-os em cache.

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are a senior code reviewer. Review code for security vulnerabilities, performance issues, and best practices violations...",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "Review this function:\n\ndef process_user_input(data):\n    return eval(data)"}
    ]
)

Preços do cache para Opus 4.7:

Uma única leitura de cache paga pela escrita de cache de 5 minutos. Duas leituras pagam pela escrita de 1 hora.

Conversas Multi-Turno

Mantenha o contexto entre as interações adicionando ao array de mensagens.

messages = []

# Turn 1
messages.append({"role": "user", "content": "I need to build a REST API for a todo app."})

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
)

messages.append({"role": "assistant", "content": response.content})

# Turn 2
messages.append({"role": "user", "content": "Add authentication with JWT tokens."})

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
)

Testando suas Chamadas de API com Apidog

A construção de uma integração com a API Claude envolve payloads complexos: mensagens multi-turno, definições de ferramentas, resultados de ferramentas, imagens base64 e respostas de streaming. Uma ferramenta como Apidog simplifica a depuração e o teste.

Configure seu ambiente:

1. Crie um novo projeto no Apidog e adicione o endpoint da API Claude Messages
2. Armazene sua ANTHROPIC_API_KEY em variáveis de ambiente
3. Defina os cabeçalhos obrigatórios (x-api-key, anthropic-version, content-type)

Teste fluxos de uso de ferramentas:

O Apidog permite encadear solicitações, para que você possa simular um loop completo de uso de ferramentas: envie a mensagem inicial, inspecione a chamada de ferramenta de Claude, construa o resultado da ferramenta e envie-o de volta. O inspetor visual de solicitação/resposta mostra exatamente o que está em cada payload.

Compare modelos:

Execute os mesmos prompts contra claude-opus-4-6 e claude-opus-4-7 para comparar contagens de tokens, qualidade de resposta e latência. O executor de testes do Apidog torna as comparações A/B repetíveis.

Valide esquemas:

Defina esquemas JSON para o formato de resposta esperado e permita que o Apidog valide automaticamente se as respostas de Claude correspondem. Isso detecta regressões quando você muda prompts ou troca de modelos.

Erros Comuns e Soluções

Referência de Preços

Nota: O novo tokenizador do Opus 4.7 pode usar até 35% mais tokens para o mesmo texto em comparação com o Opus 4.6. Use o endpoint /v1/messages/count_tokens para estimar os custos antes da implantação em produção.

Conclusão

Claude Opus 4.7 é o modelo mais capaz da família Claude. A API é amplamente compatível com o Opus 4.6, mas a remoção de orçamentos de pensamento estendidos e parâmetros de amostragem requer mudanças no código. As novas capacidades — pensamento adaptativo, esforço xhigh, orçamentos de tarefas e visão de alta resolução — dão a você mais controle sobre como o modelo raciocina e quanto custa.

Comece com a solicitação de texto básica, adicione pensamento adaptativo para tarefas complexas e incorpore o uso de ferramentas e orçamentos de tarefas à medida que seu agente cresce. Use o Apidog para testar sua integração, validar payloads e comparar o desempenho entre as versões do modelo.