Application Process
To use Claude Messages API, first go to the Ace Data Cloud Console to obtain your API Token and keep it for later use.
If you have not yet logged in or registered, you will be automatically redirected to the login page and invited to register and log in. After completion, you will automatically return to the current page.
One API Token can invoke all platform services; there is no need to apply separately for each service. Your first application includes free credits for a free trial; when credits are insufficient, you can recharge your general balance in the Console.
📘 Full documentation: Claude Messages API →
Basic Usage
The request path for Claude Messages API is/v1/messages, consistent with the official Anthropic API. We need to provide at least three required parameters:
model: Select the Claude model to use.claude-opus-5-5is available only through the Messages API, supports 1 million Token context, a maximum output of 128K Tokens, and always enables adaptive thinking. The latest flagship isclaude-fable-5-1(1 million Token context, maximum output of 128K Tokens); the originalclaude-fable-5is still retained for compatibility.claude-sonnet-5-5has joined the native Messages series interface, supports image input and adaptive thinking; its official reference prices for input, output, and cache reads are 2, 10, and 0.20 USD per million Tokens, respectively.messages: An array of input messages. Each message containsrole(role) andcontent(content), whererolesupportsuserandassistant.max_tokens: The maximum number of output tokens, used to limit the length of a single response.
system: System prompt, used to set the model’s behavior and role.temperature: Generation randomness, between 0 and 1. The higher the value, the more divergent the response.stream: Whether to use streaming responses. Setting it totrueenables a word-by-word return effect.stop_sequences: Custom stop sequences. The model stops generating when it encounters these texts.top_p: Nucleus sampling parameter, used together with temperature to control generation randomness.top_k: Sample only from the K options with the highest probabilities.tools: Tool definitions, used to allow the model to call external functions.tool_choice: Controls how the model uses the provided tools.cache_control: Automatically creates a cache breakpoint at the last cacheable content block of the request; it can also be written on a specific content block.
cURL Example
Python Example
id: Unique identifier of this message.type: Alwaysmessage.role: Alwaysassistant.content: An array of response content. Each element containstype(such astext) and the corresponding content.model: The name of the model processing the request.stop_reason: The reason for stopping. Stable values includeend_turn,max_tokens,stop_sequence,tool_use,pause_turn(you can return the current assistant content unchanged to continue),refusal, andmodel_context_window_exceeded.stop_sequence: If stopped due to a custom stop sequence, displays the matching stop sequence text.stop_details: Whenstop_reasonisrefusal, it may contain the refusal category and description.usage: Token usage statistics.input_tokensis uncached input;cache_creation_input_tokensandcache_read_input_tokensare cache writes and reads respectively;output_tokensis the total number of output tokens. Ifoutput_tokens_details.thinking_tokensis returned, this value is a subset ofoutput_tokens; do not add it again when calculating totals or costs. This detail may benullor omitted when there is no authoritative count.usage.cache_creation: Optional cache write TTL details, containingephemeral_5m_input_tokensandephemeral_1h_input_tokens. When the object exists, the sum of the two equalscache_creation_input_tokens; a field beingnullor omitted means that the current response has no available TTL breakdown and must not be interpreted as0.usage.cost: Non-streaming responses may contain a credit consumption object recorded by Ace Data Cloud, whereamountis the actual consumption for this request,currencyis the unit of measurement, andlist_amountis the amount before discount (if any). The official base price for Fable 5.1 cache reads is $0.25 per million Tokens, while the base prices for 5-minute and 1-hour cache writes are $12.50 and $20 per million Tokens, respectively; actual platform prices are converted according to plan discounts.
System Prompt
Claude Messages API supports setting a system prompt through thesystem field, used to define the model’s behavior, role, and context.
Python Example
system prompt, you can precisely control Claude’s role and behavior.
Streaming Responses
This interface also supports streaming responses. Set thestream parameter to true to receive results progressively, which is highly suitable for implementing character-by-character display on web pages.
Python Example
event: and data:. Streaming event types include:
message_start: The message starts, containing the basic message information and model name.content_block_start: A content block starts.content_block_delta: An incremental update to a content block, containing newly generated text fragments.content_block_stop: A content block ends.message_delta: An incremental update at the message level, containingstop_reasonand the finalusageinformation. The authoritative value ofoutput_tokens_details.thinking_tokensshould only be read from the lastmessage_delta.usage; do not accumulate it across events.message_stop: The message ends.
content_block_delta events in the streaming response contain progressively generated text content. By concatenating all text_delta values, you can obtain the complete reply.
JavaScript Example
Multi-turn Conversations
If you want to integrate multi-turn conversation functionality, you need to alternately arrange messages with theuser and assistant roles in the messages array, and pass in the previous conversation history together.
Python Example
messages, Claude can provide accurate answers based on the context.
Deep Thinking Models
Claude’s thinking and thinking summary are two different concepts: the model can perform internal reasoning, but the API does not return the original chain of thought. When the reasoning process needs to be displayed, the API returns a processed summary. Current models are recommended to use adaptive thinking, and the overall reasoning effort is controlled throughoutput_config.effort:
display: "summarized"returns a readable thinking summary; it is not the raw chain of thought.display: "omitted"returnsthinking: "", while still retaining the opaquesignatureto support subsequent conversations.display: "updates"is Anthropic’s beta mode and requiresanthropic-beta: thinking-display-updates-2026-08-18. The official definition is to hide the reasoning body and display brief progress updates between tool calls. The platform passes through this parameter and beta request header as-is, and will not forcibly rewrite it assummarized; the actual output content depends on the support of the selected model.thinking,output_config, effort, sampling parameters, and newly added extension fields are passed through as-is. The platform does not maintain hardcoded value enumerations or combination restrictions by model, nor does it automatically rewrite thinking modes; whether these parameters are accepted is determined by the selected model, and parameter errors returned by the model are passed back to the client.- The default display value for Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8, and Opus 4.7 is
omitted; Opus 4.6, Sonnet 4.6, and earlier models that support thinking usesummarizedby default. - Display affects only returned content and streaming latency; it does not disable reasoning or reduce billing for thinking tokens.
- Whether thinking is enabled by default and the display default value are two independent matters. Opus 5 and Sonnet 5 enable adaptive thinking by default; for Opus 5, omitting
thinkingis equivalent to adaptive, and omittingoutput_config.effortis equivalent tohigh. Opus 4.8, 4.7, and 4.6 require explicit enablement. - Thinking and the final body jointly use the
max_tokensoutput budget. When the budget is too small, thinking may consume most of the allowance, causing the body to be empty or truncated; please increasemax_tokens, or uselow/mediumeffort to control reasoning investment. - For models that allow thinking to be disabled, you can pass
thinking: {"type":"disabled"}. New modes such asbetween_toolsand effort combinations depend on the selected model; the platform does not reject them in advance based on old model rules. - Fixed thinking budgets can be passed through
budget_tokens; new models typically usethinking.type=adaptiveandoutput_config.effort. Whether fixed budgets or disabling thinking are supported depends on the current capabilities of the selected model. - During multi-turn conversations and tool calls, the complete thinking block and signature returned by the assistant should be passed back as-is; do not modify or generate the signature yourself.
- Parameter pass-through does not mean that every model supports every feature. Cross-protocol calls still require conversion, and the support scope and errors for content such as
redacted_thinkingare determined by the model service that actually processes the request.
summarized produces thinking_delta; omitted does not produce thinking_delta, and only retains the thinking block lifecycle and signature_delta.
Vision Models
Claude supports multimodal input and can process text and images simultaneously. In the Messages API, vision capabilities can be used by settingcontent to an array format and passing image content blocks.
Using Base64-Encoded Images
Using URL Images
cURL Example
image/jpeg, image/png, image/gif, and image/webp.
Documents and PDFs
PDFs usedocument content blocks and support two stable sources: Base64 and URL. Base64 sources must use application/pdf:
{"type":"url","url":"https://example.com/report.pdf"}. document also supports text/plain and content sources composed of text/image blocks; optional fields include title, context, and citations. The file_id source of the Files API belongs to an independent beta feature and is not part of the stable contract of this interface.
Prompt Caching
Top-levelcache_control automatically places the cache breakpoint on the final cacheable block:
cache_control on text, image, document, tool_use, tool_result content blocks, or tool definitions. ttl supports 5m (default) and 1h; please use usage.cache_creation_input_tokens and usage.cache_read_input_tokens to determine cache writes and hits.
When the response provides usage.cache_creation, ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens. If cache_creation is null or omitted, it indicates that there is only a total cache write volume and no authoritative TTL breakdown; in this case, do not treat either bucket as a known 0, and billing and totals should still be based on the aggregate fields.
Example return result:
Tool Use
The Claude Messages API natively supports tool use, allowing the model to call your predefined tools/functions when needed.Python Example
content in the returned result will include a content block of type tool_use:
stop_reason is tool_use, indicating that the model needs to call a tool. After receiving this result, you need to execute the tool function and return the result to the model in the form of tool_result:
Differences from the Chat Completion API
Ace Data Cloud provides two Claude API formats. The main differences between them are as follows: For the Messages API,usage.input_tokens only represents uncached input, while cache_read_input_tokens and cache_creation_input_tokens are independently billed buckets; all three are calculated separately according to their respective prices.
If your system has already integrated with an OpenAI-format API, you can use the Chat Completion API for a seamless switch. If you need to use all of Claude’s native capabilities, the Messages API is recommended.
Error Handling
Error responses from public APIs use the Ace Data Cloud platform envelope:error.code is a stable error code, error.message is a description, and trace_id is used for request troubleshooting. Common HTTP statuses include:
400: Request parameters or protocol content is invalid.401: The authorization token is invalid, missing, or expired.403: Access is forbidden, the balance is insufficient, or the quota is restricted.404: The API or model does not exist.413: The request body is too large.429: Too many requests.500/503/504: Service error, temporarily unavailable, or processing timeout.
Error Response Example
error.code.

