Skip to main content
POST

Introduction

Claude’s native message API, suitable for native Anthropic clients such as Claude Code. This API follows Anthropic’s API specification and provides full support for Claude model capabilities, including advanced features such as Extended Thinking and tool calling.
If you are using an OpenAI-compatible client (such as the OpenAI SDK), we recommend using the /v1/chat/completions endpoint instead.

Authentication

string
required
Bearer Token, e.g. Bearer sk-xxxxxxxxxx

Request Parameters

string
required
Claude model identifier. Supported models include:
  • claude-fable-5-1 - Claude Fable 5.1 (Latest, most capable, suited to the hardest reasoning and long-horizon agents)
  • claude-opus-5-5 - Claude Opus 5.5 (Latest Opus, complex agentic and coding work)
  • claude-sonnet-5-5 - Claude Sonnet 5.5 (Latest Sonnet, balance of speed and intelligence)
  • claude-haiku-5-5 - Claude Haiku 5.5 (Latest Haiku, fastest and lowest cost)
  • claude-fable-5 - Claude Fable 5
  • claude-opus-5 - Claude Opus 5
  • claude-sonnet-5 - Claude Sonnet 5
  • claude-opus-4-8 - Claude Opus 4.8
  • claude-opus-4-7 - Claude Opus 4.7
  • claude-opus-4-6 - Claude Opus 4.6
  • claude-sonnet-4-6 - Claude Sonnet 4.6 (Balanced performance)
  • claude-opus-4-5-20251101 - Claude Opus 4.5
  • claude-haiku-4-5-20251001 - Claude Haiku 4.5
  • claude-sonnet-4-5-20250929 - Claude Sonnet 4.5
  • claude-sonnet-4-20250514 - Claude Sonnet 4
  • Other Claude series models
Official docs: Models overview | Migration guides: Fable 5.1 · Opus 5.5 · Sonnet 5.5 · Haiku 5.5
array
required
List of conversation messages. Each element contains role (user / assistant; some newer models also support system, see below) and content. content can be a string or an array of media content.Model support: supported by all Claude models.Mid-conversation system messages (role: "system")Inserting {"role": "system", "content": "..."} in the middle of the messages array lets you append operator instructions while the conversation is in progress (for example switching modes or injecting state) without invalidating the previously cached conversation prefix. Compared with modifying the top-level system, this approach is more cache-friendly and harder to exploit via prompt injection. It is generally available and needs no beta header. Officially supported platforms are the Claude API, Amazon Bedrock, and Google Cloud. Official docs: Mid-conversation system messagesPlacement rules (violating them on a supported model also returns 400):
  • It cannot be messages[0];
  • It must immediately follow a user message (or an assistant message that ends with a server-side tool call);
  • It must be the last item in the array, or be immediately followed by an assistant message;
  • It cannot be inserted between an assistant tool_use and its corresponding tool_result (in an agent loop, place it after the user message that carries the tool_result).
The top-level system field works normally on all models. A role: "system" message is only a supplement to it, suited to multi-turn conversations where instructions need to be added midway. System messages passed through /v1/chat/completions (OpenAI-compatible format) are merged into Claude’s top-level system field and do not follow these rules.
Assistant prefill: ending the request with role: "assistant" to prefill the model’s reply returns 400 on claude-sonnet-4-6, claude-opus-4-6 and all later models (including claude-sonnet-5, claude-sonnet-5-5, claude-opus-5-5, claude-fable-5-1 and claude-haiku-5-5; it is not allowed on Haiku 5.5 even with thinking off). It is unavailable on any model when thinking is enabled. Use output_config.format (Structured outputs) or the system prompt to constrain the output format instead.
number
required
Maximum number of tokens to generate, which controls reply length. Must be greater than 0. Thinking tokens also count toward this limit, so reserve enough headroom when thinking is enabled, otherwise the reply may be truncated with stop_reason: "max_tokens".Model support (the per-request output limit differs by model)
string|array
System prompt, can be a string or an array of media content. Used to set the model’s behavior and role.Model support: supported by all Claude models, no differences.
number
default:"1.0"
Randomness control, 0-1. Higher values make replies more random.Model support
claude-haiku-5-5 validates more strictly: temperature only accepts 1, and any other value (including 0) returns 400; passing both temperature and top_p also returns 400. If you used temperature: 0 for classification on Haiku 4.5, remove the parameter and constrain the result with structured outputs (output_config.format) instead. Official docs: Claude Haiku 5.5 migration guide
On all Claude 4 and later models, temperature and top_p cannot be passed together; use one or the other.
number
default:"1.0"
Nucleus sampling parameter, 0-1, controls generation diversity.Model support
number
Top-K sampling parameter.Model support
boolean
default:"false"
Whether to enable streaming output, which returns data chunks in SSE format.Model support: supported by all Claude models, no differences.
The official SDKs require streaming when max_tokens > 21333, otherwise they raise an error because of HTTP timeouts (a client-side check, not a server-side limit). We recommend always enabling streaming when thinking is enabled or when using a large max_tokens.
array
List of stop sequences. Generation stops when the model produces one of these sequences, and the response’s stop_reason is then stop_sequence.Model support: supported by all Claude models, no differences.
array
List of tool definitions, supports function tools and web search tools.Model support: supported by all Claude models, no differences (the available server-side tool types vary by model generation).
object
Tool selection strategy, controls how the model uses tools. Options are auto (default), none, any, tool.Model support
On models that do not support forced calls, use {"type": "auto"} instead and state explicitly in the prompt which tool to use; also add strict: true to the tool definition to guarantee the arguments conform to the schema. auto does not guarantee that a tool will be called, so check in your code and retry if none was called. If you were forcing a call only to get JSON, switch to structured outputs (output_config.format) instead.Official docs: Forced tool use is not supported | Strict tool use
object
Extended thinking configuration, enables Claude’s deep reasoning capability.Model support (the parameter with the most variation across generations; see the table below)
Starting with Claude Opus 4.7, and across the entire Fable, Opus 5 / 5.5, Sonnet 5 / 5.5 and Haiku 5.5 lineups, {"type": "enabled", "budget_tokens": N} always returns 400. Use {"type": "adaptive"} + output_config.effort to control thinking depth instead. budget_tokens is only required on Claude 4.5 and earlier models; it is deprecated on Opus 4.6 / Sonnet 4.6 but still works for now.
The default for display varies by model: Claude Fable 5.1, Fable 5, Opus 5.5, Opus 5, Sonnet 5.5, Sonnet 5, Haiku 5.5, Opus 4.8 and Opus 4.7 default to "omitted"; Claude Opus 4.6, Sonnet 4.6 and earlier models default to "summarized". To show the thinking process to users on the former group, you must explicitly set "display": "summarized", otherwise the thinking content comes back as an empty string.
Response structure changes in Fable 5.1, Opus 5.5 and Sonnet 5.5: the longer progress notes the model writes between tool calls are returned as thinking blocks rather than text blocks. Under the default display: "omitted" these blocks are empty, so clients that render only text blocks may show no output for long stretches of a long agent turn. Parse the response by block type rather than relying on block position; across multi-turn tool calls, pass thinking blocks back unchanged.Official docs: Thinking | Controlling thinking display | Progress updates | Preserving thinking blocks
object
Exclusive to Claude Sonnet 5.5. On claude-sonnet-5-5, {"type": "disabled"} returns 400; to turn thinking off, use {"type": "between_tools"} instead. This is the model’s lowest thinking tier: the model does no extended thinking, and the short progress notes it writes between tool calls are returned as thinking blocks with summary text (unlike adaptive, which returns empty content by default). No beta header is required.Usage restrictions (violating any one returns 400 invalid_request_error):
Anthropic recommends preferring adaptive thinking + effort: "low": at the low level the model thinks very briefly, and simple requests usually skip thinking entirely. Use between_tools only when you really need to turn thinking off. If your code retries the same request body against other models (for example fallback or routing), remember to strip between_tools first.Official docs: Turn off up-front thinking (Sonnet 5.5 migration guide) | Running without up-front thinking
object
Output configuration, used to control the model’s reasoning depth and token spend.
This parameter affects all tokens in the response (reply text, tool calls, and thinking), so it takes effect even without thinking enabled.Model support
On Claude Opus 5 and Haiku 5.5, thinking cannot be disabled at "xhigh" or "max" effort; combining those levels with "thinking": {"type": "disabled"} returns 400. To disable thinking, set effort to "high" or lower. The same rule applies to between_tools on Sonnet 5.5. On Opus 5.5 thinking cannot be disabled at any level; the only way to reduce thinking is to lower effort.
Official docs: Effort | Recommended effort levels for Sonnet 5.5 | Opus 5.5 migration guide
object
Request metadata for tracking and debugging.Model support: supported by all Claude models, no differences.
string
default:"auto"
Service tier, controls which type of capacity this request may use. Options are auto (prefer Priority Tier capacity, falling back to standard capacity when it is insufficient) and standard_only (use standard capacity only). The response’s usage.service_tier reports the tier this request actually hit. See Service Tier.
array
MCP (Model Context Protocol) server configuration. Must be used together with an mcp_toolset entry in tools; omitting either one causes a parameter validation error.
object
Context management configuration, controls how conversation context is handled.
object
Enables automatic caching. Placed at the top level of the request body, the system automatically applies the cache breakpoint to the last cacheable block and moves it forward as the conversation grows, with no markers to maintain. See Prompt Caching.
The legacy Amazon Bedrock integration (InvokeModel / Converse, covering Opus 4.6 and earlier models) does not support a top-level cache_control and returns 400. Use block-level explicit breakpoints for those models; see Platform Support.

Parameter Support Quick Reference

Availability of each parameter across the Claude models supported by this endpoint (✅ supported / ⚠️ conditional / ❌ returns 400 when passed): Latest generation models Previous generation and earlier models
The tables above are compiled from Anthropic’s official API documentation (verified on 2026-10-14). For per-model details see the official migration guides: Fable 5.1 · Opus 5.5 · Sonnet 5.5 · Haiku 5.5. Model capabilities change between releases; refer to the Model Marketplace and actual call responses for the authoritative answer.

Prompt Caching

Prompt Caching lets you cache frequently used context, significantly reducing cost and improving response speed. Official docs: Prompt caching. There are two ways to enable it, usable separately or together:

Cache Control Parameters

Both approaches use the same field structure. Field descriptions:

Automatic Caching (Top-level cache_control)

Just write cache_control at the root level of the request body; no markers on any content block are needed:
The breakpoint moves forward automatically as the conversation grows. Each request caches up to the last cacheable block, and earlier content is read from the cache:

Platform Support

Automatic caching (top-level cache_control) is available on the vast majority of platforms, with the sole exception of the legacy Amazon Bedrock integration: So whether AWS supports it depends on which Bedrock integration is used, and the integration is determined by the model. By model:
If you are unsure which path a model actually takes, send two requests in a row with the same prefix and check whether usage.cache_read_input_tokens in the second response is greater than 0 to verify that the cache is really being hit.

Explicit Breakpoints (Block-level cache_control)

Mark it inside an element of the system array or an element of a messages content array:

Combining Both Approaches

Automatic caching and explicit breakpoints can be used at the same time. A typical scenario is to pin the system prompt with an explicit breakpoint and let automatic caching handle the growing conversation:
Rules and edge cases when combining:
  • Automatic caching uses 1 of the 4 breakpoint slots
  • If there are already 4 explicit breakpoints, passing a top-level cache_control returns 400 (no slots left)
  • If the last block already has an explicit cache_control with the same ttl, automatic caching is a no-op and takes no extra slot
  • If the last block already has an explicit cache_control with a different ttl, it returns 400
  • If the last block is not suitable as a breakpoint, the system automatically walks backward to find the nearest usable block; if none is found, caching is skipped (no error)

Caching Mechanics

  • Cache breakpoints: a single request can mark up to 4 blocks. Each breakpoint writes its own cache entry, caching the complete prefix “from the beginning up to that block”
  • Cache hits: on a request the system compares the prefix at each breakpoint, and on a miss walks backward block by block, with a lookback window of up to 20 content blocks; older cache entries beyond the window will not be hit, in which case we recommend adding another breakpoint further forward
  • Cache threshold: content shorter than the model’s minimum cacheable length is not cached (no error; it is simply processed as normal input). See the table below for each model’s threshold
  • Cache lifetime: 5 minutes (default) or 1 hour
  • Cost: cache reads cost 10% of the normal input price (90% cheaper); cache writes carry a premium: 1.25x for the 5-minute cache and 2x for the 1-hour cache

Minimum Cacheable Length by Model

Use Cases

  1. Long document analysis: cache a large document in system and ask multiple questions
  2. Codebase understanding: cache code context for multi-turn code analysis
  3. Knowledge base Q&A: cache knowledge base content to provide fast lookups
  4. Multi-turn conversations: cache conversation history to keep context coherent

Basic Examples

Advanced Features

System Prompts

The system prompt can be set as a string or as an array of media content:

Extended Thinking

Claude supports extended thinking, where the model reasons internally before giving its final answer. The syntax differs by generation (official docs: Thinking):
  • budget_tokens is only for older models, with a minimum of 1024, and must be less than max_tokens
  • When thinking is enabled, temperature / top_k are unavailable on older models and top_p can only be 0.95 ~ 1; on newer models, simply do not pass these sampling parameters
  • Thinking tokens count toward max_tokens, so reserve enough headroom (long-horizon agentic coding can start at 64K)
  • On newer models display defaults to "omitted"; to see the thinking content you must explicitly set "display": "summarized"; both streaming and non-streaming responses return thinking blocks
  • Across multi-turn tool calls, pass thinking blocks (including signature) back unchanged; do not modify or delete them

Tool Use (Tools)

Supports function tools and web search tools:

tool_choice Parameter Details

tool_choice controls how the model uses tools:
any and tool return 400 on claude-fable-5-1, claude-opus-5-5 and claude-sonnet-5-5; see the tool_choice parameter description above for the alternative. disable_parallel_tool_use: true combined with auto still works, and means “call at most once”.
Example:

Text Editor Tool

An Anthropic-defined file read/write tool that lets the model view and modify local files, commonly used for code debugging, refactoring and document editing. Anthropic defines the schema and your program executes it locally: the model returns a tool_use block, you perform the corresponding file operation, and then pass the result back as a tool_result. Declaring it requires no input_schema, only type and name:
The model returns one of the following commands in tool_use.input.command:
path is generated by the model and is untrusted input. Before executing, always resolve it to a canonical path and verify it is still inside the project root, to prevent path traversal via .., symlinks and the like; on error, return a tool_result with is_error: true so the model can retry.
The legacy text_editor_20250124 + str_replace_editor is no longer supported on Claude 4 and later models, and the undo_edit command has also been removed. For the full command reference and reference implementations in each language, see Anthropic’s official docs: Text editor tool.

Service Tier

Anthropic offers three service tiers to trade off availability, performance and cost: Standard (default, best effort), Priority Tier (prioritized scheduling, fewer overloaded errors during peak periods), and Batch (asynchronous batch processing). Use the service_tier parameter to control which capacity this request may use:
The response’s usage.service_tier reports the tier this request actually hit (such as "priority" / "standard"), which you can use to determine the scheduling outcome:
Priority Tier capacity commitments are no longer available for new purchase; only customers with existing contracts can continue to use them until the contract expires, and requests from all other accounts actually go through standard capacity. In addition, Priority Tier does not cover claude-fable-5-1, claude-opus-5-5, claude-sonnet-5-5, claude-opus-5 or claude-sonnet-5; specifying Priority Tier when requesting these models fails validation.
service_tier is an official Anthropic parameter that this platform passes through to the upstream; the actual scheduling outcome is determined by usage.service_tier in the response. For the full description see the official docs: Service tiers.

Multimodal Input (Images)

Images can be included in messages:

Prompt Caching

Caching frequently used context can significantly reduce cost and improve response speed.
First request response:
Another request within 5 minutes (different question, same system):
Key points about caching:
  • Content must be ≥ 1024 tokens (Claude Sonnet 4.5) to trigger caching
  • When ttl is omitted, the cache is valid for 5 minutes
  • With ttl: "1h", the cache is valid for 1 hour
  • Cache reads are 90% cheaper than normal input; cache writes carry a premium (1.25x for 5 minutes, 2x for 1 hour)
  • A single request can mark up to 4 blocks, and each breakpoint writes its own cache entry
  • Caching is based on an exact content match; any change invalidates the cache
Best practices:
  • Put long, unchanging context (documents, codebases, etc.) in system and enable caching
  • For long-lived, stable content, use the 1-hour cache (ttl: "1h")
  • For frequently changing content, use the default 5-minute cache (omit ttl)
  • In multi-turn conversations, you can cache the conversation history
  • Regularly monitor cache_creation_input_tokens and cache_read_input_tokens to optimize cost

Response Format

The usage fields when caching is used:
  • input_tokens: non-cached input tokens for the current request
  • cache_creation_input_tokens: tokens written when the cache is first created (only has a value on the first request)
  • cache_read_input_tokens: tokens read from the cache (has a value on a cache hit)
  • output_tokens: generated output tokens

Error Handling

The system handles errors from the upstream Claude API uniformly and returns a standardized error response format. Example error response:

Comparison with /v1/chat/completions

  • If you use Claude Code or another native Anthropic client, we recommend the /v1/messages endpoint
  • If you use the OpenAI SDK or need OpenAI format compatibility, we recommend the /v1/chat/completions endpoint
  • The two endpoints are functionally almost identical; the main difference is the request/response format

Notes

  • max_tokens is a required parameter and must be greater than 0
  • The messages array cannot be empty
  • budget_tokens is only for Claude 4.5 and earlier models, with a minimum of 1024; for newer models use thinking.type: "adaptive" + output_config.effort
  • Newer models do not return thinking content by default; to show it, set thinking.display: "summarized"
  • thinking.type: "between_tools" is only available on claude-sonnet-5-5 and cannot be passed together with other thinking fields
  • claude-fable-5-1, claude-opus-5-5 and claude-sonnet-5-5 do not support forced tool calls (tool_choice of any / tool)
  • Tool use requires multiple rounds of interaction: the first round returns the tool call request, and the second round returns the tool execution result
  • Image input must use base64 encoding
  • Using streaming output improves time to first token and the interactive experience
  • Build timeout and retry mechanisms for tool calls to avoid blocking the model’s response
  • Extended thinking can significantly improve reasoning quality on complex problems

Chat Completions (OpenAI Compatible)

View the OpenAI-compatible chat completions documentation

Model List

View information on all supported models