Claude Sonnet 5 is the Sonnet model Anthropic released on June 30, 2026. Its headline features are a 1,000,000-token context window, adaptive thinking, and stability for agent workloads. One status note comes first: as of October 2026, Sonnet 5.5 is the current Sonnet model. Sonnet 5 has entered legacy status but remains available, and Anthropic has committed not to retire it before June 30, 2027. New projects should evaluate Sonnet 5.5 first. Teams already using claude-sonnet-5 still need to understand the key, context, and call details so nothing breaks before a migration.

This article covers model status, key acquisition, Messages API calls, the practical boundaries of the 1M context, caching, and cost control, then closes with common errors and an FAQ.

Note: Anthropic and Claude are trademarks of their respective owners; this article is a technical integration guide only. Model specifications, context, and billing are subject to the official Anthropic documentation and the in-site model pricing. This article does not hard-code unit prices.

1. Check model status and specifications first

Item Official information
Model ID claude-sonnet-5
Status Legacy, still available
Release date June 30, 2026
Retirement commitment Not earlier than June 30, 2027
Context window 1,000,000 tokens
Maximum output 128,000 tokens (synchronous Messages API)
Batch output 300,000 tokens (Batch API beta)
Input / output Text, images → text
Thinking mode Adaptive thinking, default effort high
Knowledge cutoff January 2026

A few points that are easy to misread:

  • "Legacy" does not mean "shut down." It means a newer model exists, but the older model is still within its service period.
  • 1M context is capacity, not a target. Longer context means higher input cost and latency.
  • Adaptive thinking is on by default; for simple tasks, you can reduce thinking depth through effort.
  • The synchronous API caps output at 128K; only consider the Batch API beta when you need longer output.

For a greenfield project, evaluate Sonnet 5.5 directly. If your prompts, evals, and production traffic are already built around Sonnet 5, run a small-traffic comparison first, then decide when to migrate.

2. Get a Claude API key

Option 1: Anthropic Console

  1. Register and sign in to the Anthropic Console, then complete organization and billing setup.
  2. Create a key on the API Keys page, named by project or environment.
  3. Confirm the balance, rate limits, and model permissions.
  4. Store the key in a server-side environment variable; never put it in frontend code or Git.

The official Base URL is https://api.anthropic.com, and the Messages endpoint path is /v1/messages.

Option 2: ZSQH AI Gateway

Register at the ZSQH AI Gateway, create a key, top up and invoice in RMB, and monitor usage for multiple models from one console. The gateway provides an Anthropic-compatible entry point with the Base URL https://ai.zhongshangqihang.com; calls also use the /v1/messages path. Which Claude models are enabled and how to fill in model names are subject to model pricing.

Configuration Anthropic direct ZSQH AI Gateway
Base URL https://api.anthropic.com https://ai.zhongshangqihang.com
Authentication header x-api-key x-api-key
Version header anthropic-version: 2023-06-01 Same as left
Model name claude-sonnet-5 Subject to the in-site pricing page
SDK Anthropic SDK Anthropic SDK

3. Calling with curl

export ANTHROPIC_API_KEY="sk-your-key"

curl "https://ai.zhongshangqihang.com/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 800,
    "system": "You are a technical editor. Be specific in your answers.",
    "messages": [
      {"role": "user", "content": "Explain in three points the boundaries of using 1M context"}
    ]
  }'

Three things to watch: max_tokens is required in the Claude Messages API; authentication uses x-api-key, not Authorization: Bearer; and the anthropic-version header cannot be omitted. Miss any one and you get a 401 or 400.

4. Calling with Python

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    base_url="https://ai.zhongshangqihang.com",
)

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="You are a customer-service QA assistant. Output JSON only.",
    messages=[
        {"role": "user", "content": "Judge the sentiment: delivery was too slow, but the support attitude was good."}
    ],
)

print(msg.content[0].text)

One compatibility change you must know: Sonnet 5 returns 400 for non-default values of temperature, top_p, and top_k. If old code habitually passes temperature=0.2, remove it when migrating to Sonnet 5, and use prompts and effort to control output stability instead.

5. How to use 1M context cost-effectively

1M tokens is roughly 550,000 English words or 2.5 million Unicode characters, estimated with the official current tokenizer. It suits scenarios where you put a complete set of materials in at once, but not scenarios where you stuff everything in indiscriminately.

Scenario Recommended approach Why
Long contract review Put in the full text and request JSON by clause Avoid retrieval missing key clauses
Codebase Q&A Retrieve relevant files first, then assemble context Full code is both expensive and distracting
Multi-turn customer service Keep recent turns plus a summary of history Control input growth
Batch offline analysis Use the Batch API Official batch processing has a separate discount
Long report generation Generate in sections, then merge Avoid hitting the output ceiling in one call

The priority for context management is: retrieve first, summarize next, and only then consider the full text. Full context is worth the premium only for tasks where missing one passage can cause an error.

6. Caching and cost control

Claude billing consists of input, output, cache writes, and cache reads. Under the official pricing page, cache reads cost about one tenth of the input rate, a 5-minute cache write costs about 1.25 times the input rate, and a 1-hour cache write costs more; Batch API input and output are billed at 50%. For specific unit prices, see model pricing.

Cost per request =
  Uncached input tokens × input rate
+ Cache write tokens × cache write rate
+ Cache read tokens × cache read rate
+ Output tokens × output rate

Control costs in this order:

  1. Cache stable prefixes: put the system prompt, tool definitions, and fixed knowledge base first, and add cache_control.
  2. Cache only what will be reused: do not cache one-off documents, or you pay the write premium for nothing.
  3. Retrieve before loading full text: five to ten RAG passages are usually cheaper than stuffing in the whole corpus.
  4. Send offline jobs through Batch: tagging, summarization, and classification that do not need real-time responses should be batched first.
  5. Adjust effort: lower thinking depth for simple tasks and raise it for complex ones.
  6. Limit output: set max_tokens, require structured output, and cut wasted long responses.
  7. Split keys by project: set budget caps and alerts, and review the consumption ranking weekly.

7. Common errors

Error Common cause Fix
401 Unauthorized Wrong key, missing x-api-key Copy the key again and check the request headers
404 Not Found Wrong Base URL or path Confirm /v1/messages
400 invalid_request_error A non-default temperature or similar parameter was sent Remove the parameter and retry
429 rate_limit_error Concurrency or request rate exceeded Reduce concurrency and use exponential backoff
529 overloaded_error Server-side load too high Retry later and prepare a fallback channel
invalid_request_error (prompt is too long) Input exceeds 1M Split into batches, retrieve, or summarize
max_tokens-related error Missing or above the limit Fill it in according to the model specifications

FAQ

Do I have to migrate from Sonnet 5 to Sonnet 5.5?

Not mandatory. Sonnet 5 is still within its service period, and Anthropic has committed not to retire it before June 30, 2027. New projects should evaluate Sonnet 5.5 first. For existing projects, run a small-traffic comparison and confirm that prompts, tool calls, and output formats are compatible before migrating.

Is a Claude API key the same as a Claude subscription?

No. Subscriptions cover the web and client products; an API key is a developer credential, and billing and permissions are managed separately.

Does a 1M context cost more?

Yes. Context itself does not carry an extra "capacity fee," but more input tokens mean a higher bill and longer latency. For long-document tasks, retrieve and summarize first; use the full context only when a full-text judgment is required.

Does Sonnet 5 support image input?

Yes. The official specification is text and image input with text output. Images are converted into input tokens according to the rules, so estimate the cost before batch processing.

Why does setting temperature return 400?

Sonnet 5 does not accept non-default values of temperature, top_p, or top_k. Remove those parameters and control output with prompts and effort.

Next steps

First create a test key at the ZSQH AI Gateway, run a Messages request with curl, then connect the Anthropic SDK. Model availability and prices are subject to model pricing.

Related reading: