How to Use the Claude Opus 5 API ?

Claude Opus 5 shipped on July 24, 2026, and Anthropic recommends it as the default choice when you are unsure which model to use. Its API model ID is exactly claude-opus-5, with no date suffix.

Try Apidog today

This guide covers the implementation path: create a key, make a first request, stream output, handle tool use and adaptive thinking, tune effort, and verify prompt-cache hits through usage. Every example uses plain HTTP and JSON, so you can build and debug requests in Apidog before integrating them into application code.

If you are moving from Opus 4.8, review the Opus 4.8 to Opus 5 migration guide alongside this post.

Before your first call: two breaking changes

1. Thinking is enabled by default

On Opus 4.8, omitting thinking meant no thinking. On Opus 5, the same request uses adaptive thinking.

max_tokens remains a hard cap for both thinking tokens and visible response tokens. A request copied from an Opus 4.8 integration can therefore stop mid-answer.

If your previous max_tokens value was tightly sized around expected output, increase it and test for truncation.

2. Disabling thinking limits effort

This combination returns a 400:

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

When thinking is disabled, effort cannot be xhigh or max. Choose one of these approaches:

• Keep thinking enabled and lower effort to control cost.
• Disable thinking and use low, medium, or high effort.

Anthropic recommends keeping thinking enabled. With thinking disabled, Opus 5 can occasionally emit tool calls as plain text instead of executable tool-use blocks, and it can expose <thinking> tags in visible output.

Both changes are covered in Anthropic’s model migration guide.

Step 1: Get an API key

Create an API key in your Claude Developer Platform organization settings. Copy it when it is created; you cannot view it again later.

Store the key in an environment variable:

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

For GUI testing, store the key as an environment variable there too. In Apidog, create environments such as Local, Staging, and Production, then reference the secret as {{ANTHROPIC_API_KEY}} in the request header. This keeps keys out of shared collections and exports.

Add billing credits before sending requests. Opus 5 costs $5 per million input tokens and $25 per million output tokens, matching Opus 4.8. See the full pricing breakdown for caching, batch, and fast-mode rates.

Step 2: Send your first request

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

Set these headers:

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

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

Use 4096 rather than the 1024 often found in starter examples. Thinking tokens now consume the same token budget as the final answer.

Here is the Python SDK equivalent:

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)

Do not assume message.content[0].text contains the answer. content is an array of typed blocks. With thinking enabled, Opus 5 can return a thinking block before the text block.

This is a common upgrade failure: the request returns 200, but application code reads the wrong block.

Useful model limits while implementing:

• Context window: 1M tokens by default and maximum
• Maximum Messages API output: 128K tokens
• Knowledge cutoff: May 2026

See Anthropic’s models overview and this Opus 5 explainer for the complete specification.

Step 3: Handle adaptive thinking

Adaptive thinking lets the model decide how much internal reasoning a request needs. You do not configure a thinking-token budget directly; use output_config.effort instead.

Implement these rules:

• Parse blocks by type. Use block.type == "text" for visible output. Handle block.type == "thinking" separately if you need to log it.
• Preserve assistant content blocks. In multi-turn or tool-use flows, append the full assistant content array to conversation history.
• Watch for truncation. Thinking and visible output share max_tokens. Check for stop_reason: "max_tokens" in tests.

To fully disable thinking:

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

high is intentional. Setting effort to xhigh or max with disabled thinking produces a 400.

Step 4: Control cost with output_config.effort

Set effort under output_config:

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

Available values are:

• low
• medium
• high
• xhigh
• max

The default is high.

Example:

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

Before tuning, account for these details:

1. Effort levels were recalibrated. Do not copy Opus 4.8 settings directly. Opus 5 low and medium are stronger than earlier Opus equivalents. Run an evaluation sweep using your own prompts and success criteria.

2. Start coding and agent workloads at xhigh. Give long agentic turns enough room. 65536 is a reasonable starting max_tokens cap for these workloads.

3. Lower effort does not shorten visible answers. It reduces thinking effort, not response length. Ask for concise output in the prompt when that is the goal.

For a practical evaluation approach, see the effort parameter deep dive.

Step 5: Stream the response

Set "stream": true to receive server-sent events instead of one JSON response.

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)

The raw SSE flow is:

1. message_start
2. content_block_start
3. content_block_delta
4. content_block_stop
5. message_delta
6. message_stop

message_delta includes the final stop_reason and output token count.

With thinking enabled, you receive two block types in sequence:

• Thinking deltas: thinking_delta
• Visible output deltas: text_delta

Do not append every delta to the same UI buffer. That can expose reasoning content to users. Route thinking and visible text separately.

A GUI API client is useful here because raw SSE output is difficult to inspect in a terminal. Apidog can render the stream as it arrives, helping you verify block boundaries and parsing behavior before implementing a production stream handler.

Step 6: Add tool use

Define tools in a tools array. When the model needs a tool, it returns:

• stop_reason: "tool_use"
• A tool_use content block

Execute the tool, then send its result back in a new user message as a tool_result block.

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,
                    }
                ],
            },
        ],
    )

Pass message.content through unchanged in the assistant turn. Rebuilding it manually can remove thinking blocks and degrade the next turn.

Two Opus 5 details matter for agents:

• Tool-use system prompt overhead is 286 tokens when tool_choice is auto or none, compared with 290 on Opus 4.8 and 675 on Opus 4.7.
• The mid-conversation-tool-changes-2026-07-01 beta header allows tools to be added or removed between turns without invalidating the prompt cache.

Opus 5 also delegates to subagents more readily than Opus 4.8. For cost-sensitive systems, explicitly constrain delegation in your system prompt.

Step 7: Verify cache hits with usage

Every response includes a usage object:

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

To cache stable prompt content, use 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."
    }
  ]
}

Validate caching across repeated requests:

• First request: cache_creation_input_tokens should be nonzero.
• Repeated request with the same prefix: cache_read_input_tokens should become nonzero.

If cache_read_input_tokens stays at 0, the prefix may not be byte-identical or may be below the caching minimum.

Opus 5 lowers the prompt-cache threshold to 512 tokens, down from 1,024 tokens on Opus 4.8. Cache reads cost $0.50 per million tokens compared with the $5 base input rate.

Add a test assertion for cache_read_input_tokens so prompt changes that silently break caching fail CI instead of increasing your bill. See how to cut your Claude API bill for additional cost controls.

Test and debug the flow in Apidog

Everything in this workflow is an HTTP request with headers, JSON, SSE events, and response assertions. Apidog is an API development platform for sending, inspecting, and testing these requests. It does not run inference or route models; requests still go directly to Anthropic.

Use this setup:

1. Create a request. Configure POST https://api.anthropic.com/v1/messages, the three required headers, and an environment-backed API key.

2. Save it to a collection. Give your team one known-good request shape instead of rebuilding examples from scratch.

3. Fork requests by effort level. Duplicate the request for low, medium, high, and xhigh. Run the same prompt and compare quality, latency, and token counts.

4. Inspect streaming events. Add "stream": true and verify that thinking blocks and text blocks are handled independently.

5. Inspect tool payloads. When stop_reason is tool_use, inspect the exact generated input object to identify overly loose schemas.

6. Add response assertions. Check that:

   • stop_reason is not max_tokens
   • cache_read_input_tokens is greater than zero on repeated requests

Download Apidog to follow along. The same collection workflow works with other Claude models, including Sonnet 5 and existing Opus 4.8 requests.

Errors and gotchas you will actually hit

• 400 with disabled thinking and xhigh or max effort: Use high or lower, or re-enable thinking.

• 400 with sampling parameters: Non-default temperature, top_p, and top_k values still return 400, as they did on Opus 4.8. Use prompt instructions for steering instead.

• Truncated output: stop_reason: "max_tokens" means the combined thinking and output budget was exhausted. Increase max_tokens.

• No Priority Tier support: Opus 5 does not support Priority Tier. Opus 4.8 still does, so validate capacity requirements before migrating traffic.

• Mid-conversation system messages work: Opus 5 accepts role: "system" entries inside messages, where Opus 4.8 returned a 400.

• Over-verification prompts: Opus 5 verifies work without being explicitly told to do so. Remove inherited instructions such as “double-check your answer before responding” if they only add unnecessary thinking-token usage.

The honest ceiling

Opus 5 is not the top Claude model. Fable 5 holds Anthropic’s “most capable widely released” designation at $10 per million input tokens and $50 per million output tokens.

Opus 5 also trails Mythos 5 in cybersecurity exploitation and autonomous biology research, according to Anthropic.

Anthropic’s launch benchmarks—roughly double Opus 4.8 on Frontier-Bench v0.1, about 3x the next-best model on ARC-AGI 3, and within 0.5% of Fable 5 on CursorBench 3.2—are vendor-reported results and had not been independently reproduced as of July 25, 2026.

Treat those results as a starting point, then run your own evaluations. See the Opus 5 versus Fable 5 comparison and Anthropic’s launch post for the original claims.

FAQ

What is the model ID for Claude Opus 5?

claude-opus-5, with no date suffix.

On Amazon Bedrock, use anthropic.claude-opus-5. Google Cloud and Claude Platform on AWS use the first-party ID.

Why does my Opus 4.8 request now truncate on Opus 5?

Thinking is enabled by default. Since max_tokens caps thinking and output together, a limit that fit the final answer on Opus 4.8 may not fit both reasoning and response on Opus 5.

Increase max_tokens and check for stop_reason: "max_tokens".

Why do I get a 400 when I disable thinking?

You likely used:

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

Disabled thinking cannot be combined with xhigh or max effort. Cap effort at high, or keep thinking enabled and lower effort.

Do I need a beta header for the 1M context window?

No. Opus 5 supports 1M tokens as both its default and maximum context window without a beta header or long-context price premium.

For 300K output on the Batch API, you need the output-300k-2026-03-24 beta header. The Messages API remains capped at 128K output tokens.

Can I reuse Opus 4.8 effort settings?

No. Anthropic says effort levels were recalibrated. low and medium are stronger on Opus 5, so run a fresh effort sweep against your own evaluation set.

Does Apidog run the model?

No. Apidog sends, inspects, and tests API requests. Anthropic performs inference. Apidog helps manage keys, inspect streams, validate tool-call payloads, and assert on responses.