Multimodal Understanding API Reference โ
A VOD API that passes text, images, video, and audio to a model and receives text or structured results. Specify the VOD application's SubAppId to issue a API key first, then call the model with the issued ApiToken.
Call specification โ
Call preparation โ
1. Select the VOD application โ
Create the application you will use in VOD and confirm its SubAppId. This ID is used for key issuance and quota management. Model calls apply the application information tied to the key.
2. Issue a API key โ
Call vod.intl.tencentcloudapi.com's CreateAigcApiToken. This step signs with TC3 using Tencent Cloud SecretId and SecretKey.
{
"SubAppId": 123456789
}When using the TC3 call script:
python3 tencent-api.py vod CreateAigcApiToken create-token.jsonUse the ApiToken in the response as the Bearer key for later model requests. Do not pass the application ID or SecretKey as the Bearer key.
3. Call the model with the issued key โ
export VOD_API_TOKEN='your-vod-aigc-token'
curl https://mmu.vod-qcloud.com/v1/chat/completions \
-H "Authorization: Bearer ${VOD_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.8-flash",
"messages": [
{
"role": "user",
"content": "Explain in one sentence why retry intervals should gradually increase."
}
],
"max_tokens": 2048,
"stream": false
}'The address for model calls is mmu.vod-qcloud.com. Keep it distinct from the Tencent Cloud API address used to issue keys.
API key management โ
| Operation | VOD action | Auth |
|---|---|---|
| Issue | CreateAigcApiToken | TC3 signature |
| List | DescribeAigcApiTokens | TC3 signature |
| Delete | DeleteAigcApiToken | TC3 signature |
| Query quota | DescribeAigcQuotas | TC3 signature |
| Create / change / delete quota | CreateAigcQuota / ModifyAigcQuota / DeleteAigcQuota | TC3 signature |
Keys are valid indefinitely and up to 50 can be issued. After creation or deletion, it may take about 30 seconds to show up in the list. Grant the CAM permission for the corresponding VOD action to sub-accounts.
Protocol selection โ
| Protocol | Request path | Central input field | Central result field |
|---|---|---|---|
| Chat Completions | POST /v1/chat/completions | messages | choices.message |
| Responses | POST /v1/responses | input | output |
| Messages | POST /v1/messages | messages / system | content |
Even when the same model can be called over multiple protocols, the request fields and response structure differ. Choose the path in Supported protocols in each model's document, then build the request to that specification.
Auth and session headers โ
| Header | Required | Value / purpose |
|---|---|---|
Authorization | Required | Bearer ${VOD_API_TOKEN} |
Content-Type | Required | application/json |
x-api-key | Optional | API key header available in Messages integration |
X-Request-Id | Optional | Request trace ID |
Tx-User-Session-Id | Optional | Session ID that links requests in the same conversation |
List callable models โ
curl https://mmu.vod-qcloud.com/v1/models \
-H "Authorization: Bearer ${VOD_API_TOKEN}"The data.id in the response is the model value you put in the request. Distinguish the model's display name from the API identifier.
API list and request parameters โ
Chat Completions โ
Request parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
model | Required | String | Model ID |
messages | Required | Array | Conversation history including role and content |
stream | Optional | Boolean | Whether to use SSE streaming |
max_tokens | Optional | Integer | Maximum number of generation tokens. Includes reasoning tokens |
max_completion_tokens | Optional | Integer | SDK-compatible generation token limit. Do not specify together with max_tokens |
temperature | Optional | Number | Sampling temperature. See each model's document for the allowed range |
top_p | Optional | Number | Sampling based on cumulative probability |
top_k | Optional | Integer | Limit on candidate tokens for supported models |
reasoning_effort | Optional | String | Reasoning effort per model |
thinking_enabled | Optional | Boolean | Whether reasoning is enabled for supported models |
tools | Optional | Array | Callable tools and input schema |
tool_choice | Optional | String / Object | Auto select, force tool use, or select a specific tool |
response_format | Optional | Object | Plain text, JSON, or JSON Schema output |
stream_options | Optional | Object | Receive stream usage via include_usage=true |
max_tokens is not the context limit of input and output combined. The model's context limit, generation limit, and the account's TPM quota each apply separately.
Message structure โ
| Field | Type | Description |
|---|---|---|
role | String | system / developer / user / assistant / tool |
content | String / Array | Text or an array of media parts |
tool_calls | Array | Function name and arguments requested by the model |
tool_call_id | String | ID that links a tool result to the original call |
Response example โ
{
"id": "chatcmpl-example",
"object": "chat.completion",
"model": "gemini-3.8-flash",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Increasing the retry interval reduces the burst of requests hitting a failing server."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 24,
"completion_tokens": 32,
"total_tokens": 56
}
}finish_reason=length means the generation limit was reached. For requests that use reasoning, set the limit so tokens remain for the final answer.
Responses โ
Request parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
model | Required | String | Model ID |
input | Required | String / Array | Input text, messages, tool results |
instructions | Optional | String | Response instructions for the model to follow |
max_output_tokens | Optional | Integer | Maximum output tokens including reasoning |
reasoning | Optional | Object | Reasoning settings for supported models such as effort |
text | Optional | Object | Output format and text settings for supported models |
tools | Optional | Array | Function name, description, parameter schema |
tool_choice | Optional | String / Object | Tool selection method |
stream | Optional | Boolean | Whether to use SSE streaming |
Request example โ
{
"model": "gpt-5.6-sol",
"instructions": "Answer concisely in English.",
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "Explain when cache invalidation is needed."
}
]
}
],
"reasoning": {
"effort": "low"
},
"max_output_tokens": 2048,
"stream": false
}Response example โ
{
"id": "resp_example",
"object": "response",
"status": "completed",
"model": "gpt-5.6-sol",
"output": [
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "When the source data changes, the cache must be refreshed or invalidated.",
"annotations":
}
]
}
],
"usage": {
"input_tokens": 24,
"output_tokens": 32,
"total_tokens": 56
}
}output can contain reasoning and function-call items in addition to messages. type=message's content holds the text and is read as type=output_text.
Messages โ
Request parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
model | Required | String | Model ID |
messages | Required | Array | user / assistant conversation history |
max_tokens | Required | Integer | Maximum generation tokens |
system | Optional | String / Array | Response instructions kept separate from the conversation history |
stream | Optional | Boolean | Whether to use SSE streaming |
temperature | Optional | Number | Sampling temperature for supported models |
top_p / top_k | Optional | Number / Integer | Sampling settings for supported models |
thinking | Optional | Object | Reasoning method and budget for supported models |
output_config | Optional | Object | Output settings such as reasoning effort for supported models |
tools | Optional | Array | name, description, input_schema |
tool_choice | Optional | Object | Tool selection methods such as auto, any, tool |
stop_sequences | Optional | Array | List of strings that stop generation |
Request example โ
{
"model": "deepseek-v4.1-flash",
"system": "Answer in English.",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Explain request timeouts and retry policies."
}
]
}
],
"max_tokens": 2048,
"stream": false
}Response example โ
{
"id": "msg_example",
"type": "message",
"role": "assistant",
"model": "deepseek-v4.1-flash",
"content": [
{
"type": "text",
"text": "A timeout can leave it unclear whether the request completed, so retries must account for duplicate execution."
}
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 24,
"output_tokens": 32
}
}Reasoning settings โ
| Protocol | Where to set | Example |
|---|---|---|
| Chat Completions | Top-level reasoning_effort | "reasoning_effort": "high" |
| Chat Completions | Supported models' thinking_enabled | "thinking_enabled": true |
| Responses | reasoning.effort | "reasoning": {"effort": "high"} |
| Messages | Per-model thinking / output_config | See the settings in each model's document |
Reasoning setting names and allowed values differ by protocol and model version. Do not put thinking_enabled in every model as if it were common. Returned reasoning tokens count toward generation token usage.
Media Input โ
Parts in Chat Completions โ
| type | Input field | Content |
|---|---|---|
text | text | Questions and instructions |
image_url | image_url.url | Image URL or data URL |
video_url | video_url.url | Video URL |
input_audio | input_audio | Audio URL or data / format |
file | file.file_url / file.file_data / file.file_name | File URL, or Base64 data and name |
Check the supported media range in each model's document. Do not treat video and audio support the same as image input support. For videos longer than 100MB, use URL input.
Conversation and roles โ
Use system for answer rules, user for questions and media, and assistant for previous model responses. Tool results are delivered through tool in Chat Completions, function_call_output in Responses, and tool_result in Messages.
Chat Completions detailed fields โ
The field structure of the protocol. Per-model supported features and allowed values follow that model's per-version specification.
Core parameters โ
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
model | String | Required | - | Model identifier. The platform's default service ID is the same as the model name (e.g. hy3, deepseek-v4-flash). The custom service format is ep-xxxxxxxx. |
messages | Array | Required | - | Array of chat context messages. See Messages parameters. |
stream | Boolean | Optional | false | Whether to enable streaming output (SSE). |
stream_options | Object | Optional | - | Streaming options. Applies only when stream=true. |
stream_options.include_usage | Boolean | Optional | false | Whether to include usage statistics in the last chunk in streaming mode. The platform always requests usage; this field only controls whether it is passed on to the client. |
Messages parameters โ
| Field | Type | Required | Description |
|---|---|---|---|
role | String | Required | Fixed to "system" |
content | String | Required | System instructions that set model behavior and context. |
| Field | Type | Required | Description |
|---|---|---|---|
role | String | Required | Fixed to "user" |
content | String or Array | Required | Plain text maps to a string; multimodal content maps to an array (see Content Part below). |
| Field | Type | Description |
|---|---|---|
type | String | Content type: "text" / "image_url" / "video_url" / "file_url" |
text | String | Text content when type="text". |
image_url | Object | Image information when type="image_url". |
image_url.url | String | Image HTTP(S) URL, or a Data URL in data:image/...;base64,... format |
image_url.detail | String | Image resolution policy: "auto" / "low" / "high". The default is "auto". |
video_url | Object | Video information when type="video_url". |
video_url.url | String | Video HTTP(S) URL. |
file_url | Object | File information when type="file_url". |
file_url.url | String | File HTTP URL (only direct HTTP links are supported; Base64 is not). |
| Field | Type | Required | Description |
|---|---|---|---|
role | String | Required | Fixed to "assistant" |
content | String | Optional | Model response text (required if tool_calls is absent). |
reasoning_content | String | Optional | Reasoning chain content. Returned with the model response when thinking; pass it back unchanged to keep context continuity in multi-turn conversations. |
reasoning_details | Array | Optional | Array of reasoning chain blocks that include signatures. Pass them back unchanged to keep context continuity in multi-turn conversations. |
tool_calls | Array | Optional | List of tool calls. See tool call parameters. |
prefix | Boolean | Optional | Supported by some DeepSeek models. When set to true, the model uses the content of this message as a prefix for continuation, and the corresponding Beta endpoint is required. On the standard endpoint this field is ignored and does not affect the request result. |
| Field | Type | Required | Description |
|---|---|---|---|
role | String | Required | Fixed to "tool" |
content | String | Required | Result content returned by the tool function (JSON string format recommended). |
tool_call_id | String | Required | The value corresponding to assistant.tool_calls.id. |
name | String | Optional | Tool function name. |
Generation control parameters โ
| Parameter | Type | Required | Default | Value range | Description |
|---|---|---|---|---|---|
temperature | Float | Optional | 1.0 | [0.0, 2.0] | Sampling temperature. Higher values make output more random; lower values make it more deterministic. In general, adjust only one of this parameter and top_p. |
top_p | Float | Optional | 1.0 | (0.0, 1.0] | Nucleus sampling probability threshold. top_p=0 is normalized to null on the platform (same as the default). |
max_tokens | Integer | Optional | Model maximum | โฅ 1 | Maximum number of tokens that can be generated in a single response. If this limit is exceeded, finish_reason is "length". |
max_completion_tokens | Integer | Optional | Model maximum | โฅ 1 | Maximum number of tokens that can be generated (OpenAI's new field, semantically the same as max_tokens). Provide only one of the two. The platform uses max_completion_tokens first. |
n | Integer | Optional | 1 | โฅ 1 | Number of candidate responses. When n > 1, billing is based on the total number of tokens. Some models do not support this. When reasoning mode is enabled, n must be 1; otherwise a 400 error is returned. |
stop | String or Array | Optional | - | Up to 4 | Stop sequences. Generation stops immediately when a matching sequence appears. Exceeding 4 is rejected during validation. |
seed | Integer | Optional | - | Any integer | Random seed. With the same seed, the system does its best to guarantee consistent output. |
frequency_penalty | Float | Optional | 0 | [-2.0, 2.0] | Frequency penalty. Positive values lower the probability of repeating tokens that already appeared. 0 is normalized to null. |
presence_penalty | Float | Optional | 0 | [-2.0, 2.0] | Presence penalty. Positive values encourage generating new topics. 0 is normalized to null. |
logprobs | Boolean | Optional | false | - | Whether to return log probabilities of output tokens. |
top_logprobs | Integer | Optional | 0 | [0, 20] | Returns the top N tokens by probability at each position. logprobs=true is required; otherwise validation fails. |
reasoning_effort | String | Optional | - | "low" / "medium" / "high" | Reasoning depth. Applies to reasoning models. An internal mapping conversion is applied to Hunyuan models. |
Response format parameters โ
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
response_format | Object | Optional | {"type":"text"} | Controls the response format. |
response_format.type | String | Required | "text" | Format type: "text" / "json_object" / "json_schema". |
response_format.json_schema | Object | Conditional | - | Required when type="json_schema". Defines the output JSON structure. |
response_format.json_schema.name | String | Required | - | Schema name. |
response_format.json_schema.schema | Object | Required | - | JSON Schema definition (follows the JSON Schema specification). |
response_format.json_schema.strict | Boolean | Optional | false | Whether to enforce strict Schema matching. |
Tool call parameters โ
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
tools | Array | Optional | - | List of tool definitions. |
tools.type | String | Required | - | Fixed to "function". |
tools.function | Object | Required | - | Function definition. |
tools.function.name | String | Required | - | Tool function name (letters, digits, underscores, and hyphens only). |
tools.function.description | String | Optional | - | Describes the tool function so the model can judge when to call it. |
tools.function.parameters | Object | Optional | {} | Input parameter definition (JSON Schema object format). |
tool_choice | String or Object | Optional | "auto" | Tool call policy. See the enum below for details. |
parallel_tool_calls | Boolean | Optional | true | Whether to allow parallel calls to multiple tools. |
| Value | Description |
|---|---|
"none" | Do not call tools (in the Hunyuan environment the tools field is also left empty). |
"auto" | The model decides on its own whether to call a tool (default). |
"required" | Forces the model to call one or more tools. Note: when thinking mode is enabled (enabled by default on models such as deepseek-v4-*), using this value or specifying a function object returns a 400 error. You must pass thinking: {"type": "disabled"} explicitly before using it. |
{"type":"function","function":{"name":"xxx"}} | Specifies the tool to call. |
Thinking mode parameters โ
| Parameter | Type | Required | Default | Description | Applicable models |
|---|---|---|---|---|---|
thinking | Object | Optional | - | Thinking mode control (standard method) | Thinking models (e.g. Hy and DeepSeek) |
thinking.type | String | Required | - | Enable is "enabled" / disable is "disabled" / adaptive mode is "adaptive". This field is required when passing a thinking object. Without type, providing only budget_tokens returns a 400 error. | Thinking models (same as thinking; the concrete usable values differ by model). |
thinking.budget_tokens | Integer | Optional | 8192 (auto-filled) | Maximum number of tokens for the reasoning process. If type=enabled and this value is not specified, 8192 is filled in automatically. This value is an expected upper bound, not a hard limit. Actual reasoning tokens on some models may exceed the set value. See usage.completion_tokens_details.reasoning_tokens in the response for the exact reasoning token count. | Thinking models (on some models it is reference only and not strictly enforced). |
enable_thinking | Boolean | Optional | - | Whether thinking mode is enabled (simplified switch). An alternative to thinking.type, available on some models (e.g. the DeepSeek series). Using thinking.type consistently is recommended. | Some models such as Hy and DeepSeek |
thinking_budget | Integer | Optional | - | Maximum number of tokens for the reasoning process (simplified field). Must be used together with enable_thinking. Using thinking.budget_tokens consistently is recommended. | Some models such as Hy and DeepSeek |
interleaved_thinking | Boolean | Optional | - | Interleaved reasoning chain mode. Reasoning and output run at the same time, which suits streaming display. This field is an extension; actual support varies by model. Models that do not support it raise no error and ignore the field. | Some models (per each model's feature description) |
reasoning_split | Boolean | Optional | - | Outputs reasoning content and the final answer as separate segments. This field is an extension. Models that do not support it raise no error and ignore the field. | Some models |
Cache parameters โ
| Parameter | Type | Required | Default | Description | Applicable models |
|---|---|---|---|---|---|
prompt_cache_key | String | Optional | - | Manually specifies the Prompt cache key. Requests with the same key can reuse the cache. After a cache hit, billing is based on the cache price. You can check the number of cache tokens hit in the response's usage.prompt_tokens_details.cached_tokens. | Models that support Prompt Cache |
Other parameters โ
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
user | String | Optional | - | End-user identifier. Passed through to the model service unchanged for abuse detection and usage tracking. |
user_id | String or Number | Optional | - | User ID at the platform business layer (compatible with the number type; the platform converts it to a string automatically). Used only for internal user identification on the platform and not passed to the model service. To pass a user identifier to the model service, use the user field. |
safety_identifier | String | Optional | - | Security identifier. Used by the risk control system to track user-level content moderation. |
extra_body | Object | Optional | - | Additional parameters that the platform does not parse and passes to the model service unchanged. Some models merge this field into the top level of the request body, while other model services ignore it. |
Top-level structure โ
| Field | Type | Description |
|---|---|---|
id | String | Unique request identifier in chatcmpl-{uuid} format (generated by the platform, unrelated to the ID returned by the model service). |
object | String | Object type, fixed to "chat.completion". |
created | Integer | Creation time (Unix timestamp, in seconds). |
model | String | The original model name passed in the user request (not the model name actually used by the model service). |
choices | Array | List of candidate results; the number of elements equals n specified in the request. |
usage | Object | Token usage statistics. See the "usage" object for details. |
search_info | Object or null | Web search information (included when using the Hunyuan/AISearch path; otherwise null). |
Choices array elements โ
| Field | Type | Description |
|---|---|---|
index | Integer | Index of the option within the choices array, starting from 0. |
message | Object | Response message object. See message object. |
finish_reason | String | Reason generation finished. See the enum below. |
logprobs | Object or null | Token probability information (logprobs=true must be set in the request). |
| Value | Description | Recommended handling |
|---|---|---|
"stop" | Finished normally (the model stopped on its own or matched a stop sequence). | Process it normally. |
"length" | Output was truncated because the max_tokens / max_completion_tokens limit was reached. | Consider raising the max_tokens value or generating the content in several segments. |
"tool_calls" | The model needs to call a tool. | Run the tool and continue the request with the result included as a tool message. |
"content_filter" | Content was filtered by a security policy. | Check whether the input content triggers security rules. |
| Field | Type | Description | Applicable scenario |
|---|---|---|---|
role | String | Fixed to "assistant" | All |
content | String or null | Response text content. When tool_calls is present, it can be null. | All |
reasoning_content | String | Reasoning chain / reasoning process content | Thinking models |
reasoning_details | Array | Array of reasoning chain blocks (including signature) | Thinking models |
tool_calls | Array | List of tool calls | Function calling |
refusal | String or null | Refusal reason | Content security filtering |
| Field | Type | Description |
|---|---|---|
id | String | Unique tool call ID in call_{uuid} format. |
type | String | Fixed to "function". |
function.name | String | Name of the function being called. |
function.arguments | String | Function parameters (JSON string format; parse with JSON.parse before use). |
Usage object โ
| Field | Type | Description |
|---|---|---|
prompt_tokens | Integer | Number of input tokens (including tokens for system, messages, and tool definitions). |
completion_tokens | Integer | Number of output tokens (including reasoning tokens). |
total_tokens | Integer | Total number of tokens |
cache_read_tokens | Integer | Number of tokens read from a Prompt Cache hit (available on some models; can reduce billing). |
cache_write_tokens | Integer | Number of tokens written to the Prompt Cache (available on some models). |
prompt_tokens_details | Object | Input token breakdown (available on some models). |
prompt_tokens_details.cached_tokens | Integer | Number of cached tokens |
completion_tokens_details | Object | Output token breakdown (available on some models). |
completion_tokens_details.reasoning_tokens | Integer | Number of tokens used for reasoning (OpenAI-compatible path). |
completion_tokens_details.audio_tokens | Integer | Number of tokens used for audio output |
| Field | Type | Description |
|---|---|---|
object | String | Fixed to "chat.completion.chunk". |
choices.delta | Object | Incremental content. |
choices.delta.role | String | Appears only in the first chunk; the value is "assistant". |
choices.delta.content | String | Incremental text fragment; concatenating them cumulatively produces the complete response. |
choices.delta.reasoning_content | String | Incremental reasoning chain fragment (output before content in reasoning chain mode). |
choices.delta.reasoning_details | Array | Incremental reasoning chain blocks (including signature. Collect them completely after the stream ends and return them across turns). |
choices.delta.tool_calls | Array | Incremental tool calls (including the index field that identifies the array position). |
choices.delta.search_results | Array | Incremental web search results (pushed in the stream by some models). |
choices.finish_reason | String or null | null while generating; changes to the finish reason on completion. |
usage | Object or null | Included only in the last formal chunk when include_usage=true. |
| Scenario | Handling |
|---|---|
Failure before the first packet (before the HTTP 200 header is written) | A standard JSON error body is returned, from which the error code can be parsed normally. If a Fallback Provider is configured, an automatic fallback retry is performed. |
Error after the 200 response header is sent | The platform inserts a data: {"error":{"type":"...","message":"..."}}\\n\\n error frame into the SSE stream, then sends a data: [DONE]\\n\\n frame to end the stream. The client must check whether delta contains the error field. |
Example: multi-turn thinking-process conversation (with signature) โ
Responses detailed fields โ
The field structure of the protocol. Per-model supported features and allowed values follow that model's per-version specification.
Basic parameters โ
| Parameter | Type | Required | Description |
|---|---|---|---|
model | String | Optional | Model ID used to generate the response (e.g. hy3). |
input | String or Array | Optional | Text, image, or file input sent to the model. A string represents plain text (equivalent to text in the user role). An array represents a list of input items. See input type details. |
instructions | String | Optional | System (or developer) message inserted into the model context. When a system message is used together with previous_response_id, instructions from previous responses do not carry over to the next response, so the system message can be replaced. |
stream | Boolean | Optional | When set to true, model response data is streamed over SSE, and events include response.created, response.output_text.delta, response.completed, and others. |
Generation control parameters โ
| Parameter | Type | Value range | Description |
|---|---|---|---|
max_output_tokens | Number | โฅ 1 | Maximum number of tokens that can be generated in the response, including displayed output tokens and reasoning tokens. Reasoning tokens of reasoning models also count toward this limit. |
temperature | Number | [0, 2] | Sampling temperature that controls output randomness. Higher values make output more random and creative; lower values make it more focused and deterministic. |
top_p | Number | (0, 1] | Nucleus sampling parameter. The model considers only tokens whose cumulative probability mass is in the top top_p. Adjusting only one of temperature and top_p is recommended. |
truncation | String | "auto" / "disabled" | Truncation policy applied when the context exceeds the model's maximum length. auto deletes items starting from the beginning of the conversation; disabled (default) fails the request with a 400 error when the limit is exceeded. All three models accept this parameter but do not return it as-is in the response body. |
Tool calls โ
| Parameter | Type | Description |
|---|---|---|
tools | Array | Array of tools the model can call when generating a response. Supports function calling, file search, web search, and more. See tool type description. |
tool_choice | String or Object | How the model selects tools. See the table below for concrete values. |
parallel_tool_calls | Boolean | Whether to allow the model to run tool calls in parallel. |
| Value / type | Description |
|---|---|
"none" | The model generates a message directly without calling tools. |
"auto" | The model can generate a message or call one or more tools. |
{ "type": "function", "name": "..." } | Forces the model to call a specific function. |
{ "type": "mcp", "server_label": "...", "name": "..." } | Forces the model to call a tool on a specific MCP server. |
Output format control โ
| Format type | Description |
|---|---|
{ "type": "text" } | Default format that generates a text response. |
{ "type": "json_schema", "name": "...", "schema": {...} } | Structured output that guarantees the model output follows the specified JSON Schema. |
{ "type": "json_object" } | Guarantees the output is valid JSON (legacy JSON mode; not recommended for new models). |
| Value | Description |
|---|---|
file_search_call.results | Contains search results from file search tool calls. |
web_search_call.results | Contains results from web search tool calls. |
message.input_image.image_url | Contains image URLs in input messages. |
code_interpreter_call.outputs | Contains code interpreter execution output. |
reasoning.encrypted_content | Contains an encrypted version of reasoning tokens used for stateless multi-turn conversations. |
message.output_text.logprobs | Contains log probabilities of assistant messages. |
Reasoning control โ
| Field | Type | Description |
|---|---|---|
effort | "none" / "low" / "medium" / "high" | Limits the reasoning effort level. Lowering the reasoning effort level reduces response time and reasoning token consumption. |
summary | "auto" / "concise" / "detailed" | Summary of the model's reasoning process, used for debugging and understanding the reasoning. |
Other parameters โ
| Parameter | Type | Description |
|---|---|---|
background | Boolean | Whether to run asynchronously in the background. All models accept this parameter, but in practice all return synchronously. |
store | Boolean | Whether to store the response for later retrieval. All three models accept this parameter without error, but in practice do not return it as-is in the response. |
metadata | Object | Key-value pair metadata attached to the response (up to 16 pairs, key length โค 64 characters, value length โค 512 characters). All three models accept this parameter but do not return it as-is in the response body. |
service_tier | String | Service tier: auto / default / flex / scale / priority. |
| Field | Type | Description |
|---|---|---|
content | String or Array | Text, image, or audio input; can also include previous assistant responses. |
role | "user" / "assistant" / "system" / "developer" | Message role. Instructions from developer or system take precedence over instructions from user. |
phase | "commentary" / "final_answer" | Optional. Marks an assistant message as intermediate commentary or the final answer. |
type | "message" | Optional. Message input type; always message. |
| Field | Type | Description |
|---|---|---|
detail | "low" / "high" / "auto" / "original" | Image detail level; the default is auto. |
type | "input_image" | Type; always input_image. |
file_id | String | Optional. File ID. |
image_url | String | Optional. Image URL or base64-encoded data URL. |
| Field | Type | Description |
|---|---|---|
type | "input_file" | Type; always input_file. |
file_data | String | Optional. File content (base64 encoded). |
file_id | String | Optional. File ID. |
file_url | String | Optional. File URL. |
filename | String | Optional. File name. |
| Field | Type | Description |
|---|---|---|
type | "function" | Type; always function. |
name | String | Function name |
parameters | Object | JSON Schema object describing the function parameters. |
strict | Boolean | Whether to enforce strict parameter validation. The default is true. |
description | String | Optional. Function description the model uses to judge whether to call it. |
| Field | Type | Description |
|---|---|---|
type | "file_search" | Type; always file_search. |
vector_store_ids | String array | List of vector store IDs to search. |
max_num_results | Number | Optional. Maximum number of results to return; the range is 1-50. |
filters | ComparisonFilter or CompoundFilter | Optional. Filter conditions. See filter types. |
| Field | Type | Description |
|---|---|---|
id | String | Unique identifier of the response. |
object | "response" | Object type; always response. |
created_at | Number | Unix timestamp (seconds) when the response was created. |
status | String | Response status: completed / incomplete / failed / in_progress / cancelled. |
completed_at | Number | Unix timestamp (seconds) when the response completed. |
error | Object | Error object returned when the request fails. Not returned on successful completion. |
incomplete_details | Object | Details when the response is truncated. The reason field can be "max_output_tokens" or "content_filter". |
instructions | String | Returns the system message passed in the request unchanged. |
max_output_tokens | Number | Maximum output tokens specified in the request. Not returned if unspecified. |
model | String | Model ID used to generate the response. |
output | Array | List of output items generated by the model. See output item types. |
parallel_tool_calls | Boolean or null | Whether parallel tool calls are allowed. |
previous_response_id | String | ID of the previous response in a multi-turn conversation. Not returned for single-turn conversations. |
usage | Object | Token consumption statistics. See ResponseUsage object. |
service_tier | String | Service tier actually used. |
| Field | Type | Description |
|---|---|---|
input_tokens | Number | Number of input tokens. |
input_tokens_details | Object | Input token details, including cached_tokens |
output_tokens | Number | Number of output tokens. |
output_tokens_details | Object | Output token details, including reasoning_tokens |
total_tokens | Number | Total number of tokens (input + output). |
| Field | Type | Description |
|---|---|---|
id | String | Unique ID of the output message. |
type | "message" | Type; always message. |
role | "assistant" | Role; always assistant. |
status | "in_progress" / "completed" / "incomplete" | Message status. |
content | Array | Array of message content. Each item includes the type: "output_text" and text fields. |
| Field | Type | Description |
|---|---|---|
id | String | Unique ID. |
type | "function_call" | Type; always function_call. |
call_id | String | Function call ID; it must be passed when submitting function_call_output. |
name | String | Name of the function being called. |
arguments | String | JSON string of the function parameters. |
status | String | in_progress / completed / incomplete. |
| Field | Type | Description |
|---|---|---|
id | String | Unique ID. |
type | "reasoning" | Type; always reasoning. |
summary | Array | List of reasoning summary texts. Each item includes the type: "summary_text" and text fields. |
status | String | Status. |
Example: reasoning model โ
| Field | Type | Description |
|---|---|---|
key | String | Key of the attribute to compare |
type | "eq" / "ne" / "gt" / "gte" / "lt" / "lte" / "in" / "nin" | Comparison operator |
value | String / Number / Boolean / Array | Value to compare |
| Field | Type | Description |
|---|---|---|
type | "and" / "or" | Operation type |
filters | Array | Array of filters to combine (ComparisonFilter or CompoundFilter) |
Messages detailed fields โ
The field structure of the protocol. Per-model supported features and allowed values follow that model's per-version specification.
Basic parameters โ
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Required | Name of the model to use. Example: deepseek-v4-flash. |
messages | array | Required | List of conversation messages sorted chronologically and containing the full context. The platform does not manage sessions. In multi-turn conversations the client must pass the full history. See message object details. |
system | string or array | Optional | System prompt. Not included in messages; passed separately through the top-level system field. This is the main difference from the OpenAI Chat protocol. |
max_tokens | integer | Required | Maximum number of tokens that can be generated in a single model output. Each model has its own limit. Tokens consumed by the reasoning chain also count toward this limit. Therefore, when thinking is enabled, this value must be greater than budget_tokens. When the limit is reached, stop_reason is "max_tokens". |
stream | boolean | Optional | Whether to enable streaming responses (default: false). When true, the response is returned event by event in SSE format. |
Generation control parameters โ
| Parameter | Type | Range | Description |
|---|---|---|---|
temperature | float | [0, 1] | Sampling temperature. The Messages protocol's range is [0, 1], different from OpenAI's [0, 2]. |
top_p | float | (0, 1] | Nucleus sampling. In general, adjust only one of temperature and top_p. |
top_k | integer | - | Samples only from the top K tokens by probability. Messages-protocol-specific parameter; not present in the OpenAI Chat protocol. |
stop_sequences | string[] | - | Custom stop sequences. If any sequence matches, it stops immediately and sets stop_reason to "stop_sequence". The matched sequence is written back into the response's stop_sequence field. |
Tool calls โ
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Tool name. |
description | string | Optional | Describes the tool's purpose so the model can judge when to call it. |
input_schema | object | Required | Parameter definition that follows the JSON Schema format. |
type | string | Optional | Leave empty for regular tools. For built-in tools, enter the type name (e.g. web_search_20250305). |
max_uses | integer | Optional | Maximum number of calls per session for built-in tools. |
cache_control | object | Optional | Cache flag at the tool definition level. |
| Messages tool_choice | Equivalent OpenAI value | Description |
|---|---|---|
{"type":"auto"} | "auto" | Default; the model decides on its own. |
{"type":"any"} | "required" | Makes the model call one of the available tools. |
{"type":"none"} | "none" | Disables tool calls. |
{"type":"tool","name":"x"} | {"type":"function","function":{"name":"x"}} | Makes the model call the specified tool. |
Thinking chain (extended thinking) โ
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Required | Enable is "enabled" / disable is "disabled" / adaptive mode is "adaptive". |
budget_tokens | integer | Conditional | Recommended when enabled. Thinking chain token budget (recommended range: 1024~32000). The value must be less than max_tokens. |
display | string | Optional | How the reasoning process is displayed (supported by some models). |
Output composition โ
| Field | Type | Description |
|---|---|---|
effort | string | Output job level: low / medium / high / xhigh / max. |
format.type | string | Structured output type (e.g. json_schema). |
format.schema | object | JSON Schema definition. |
Caching (prompt caching) โ
| Level | Tag location | Description |
|---|---|---|
| Tool level | tools[n].cache_control | Tool definition cache |
| System level | system[n].cache_control | System content block cache |
| Message / content block level | messages[n].content[m].cache_control | Cache of past messages or content blocks |
Metadata and service tier โ
| Value | Description |
|---|---|
auto | Auto select |
standard | Standard tier |
priority | Priority tier (higher guarantees) |
batch | Batch tier |
Request headers โ
| Request header | Required | Description |
|---|---|---|
x-api-key | Required | API key (Messages protocol rule); the platform also supports Authorization: Bearer <key>. |
anthropic-version | Required | API version, fixed to 2023-06-01. |
content-type | Required | application/json |
anthropic-beta | Optional | Beta feature switch (e.g. prompt-caching and interleaved-thinking); the platform passes it through to the model service transparently and unchanged. |
| role | Description | Where used |
|---|---|---|
user | Human user input (including tool_result) | Odd-numbered conversation turns. |
assistant | The model's past responses (can include text / thinking / tool_use) | Used in even-numbered turns. In multi-turn conversations, pass the past context. |
| Block type | Main fields | Applicable role | Description |
|---|---|---|---|
text | text, cache_control | user / assistant | Text content |
image | source | user | Image |
video | source | user | Video |
document | source, title, context, citations, cache_control | user | Document input and citations |
search_result | source, title, content, citations | user | Search result content block |
tool_use | id, name, input | assistant | Model request asking for a tool call |
tool_result | tool_use_id, content | user | Tool execution result |
thinking | thinking, signature | assistant | Reasoning chain content |
redacted_thinking | data | assistant | Edited reasoning chain |
source field | Type | Description |
|---|---|---|
type | string | "base64" or "url". |
media_type | string | Required when base64 is selected. Example: image/jpeg, image/png, image/gif, or image/webp. |
data | string | Image data when base64 is selected. |
url | string | Image address when url is selected. |
detail | string | low / high / auto that specifies the image analysis detail level. |
| Field | Type | Description |
|---|---|---|
id | string | Unique ID of the tool call; it must be returned in the corresponding tool_result. |
name | string | Name of the tool to call. |
input | object | Tool parameters (an object, not a JSON string; different from OpenAI's arguments string). |
| Field | Type | Description |
|---|---|---|
tool_use_id | string | Corresponds to tool_use.id. |
content | string or array | Tool result; it can be plain text or an array of content blocks (text+image supported). |
is_error | boolean | Set to true when tool execution fails. |
cache_control | object | Cache flag. |
| Field | Type | Description |
|---|---|---|
thinking | string | Text of the model's reasoning process |
signature | string | Integrity signature of the reasoning block |
Non-streaming response โ
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier of the response (prefix msg_). |
type | string | Fixed to "message". |
role | string | Fixed to "assistant". |
model | string | Name of the model actually used. |
content | array | Array of content blocks; the usual order is thinking โ text โ tool_use. |
stop_reason | string | Stop reason. See the enum below. |
stop_sequence | string or null | The stop sequence that matched (when stop_sequences matched). |
usage | object | Token usage. See token usage. |
container | object | Code execution container information (id, expires_at). Returned only when the built-in code_execution tool is used. |
service_tier | string | Service tier actually matched. |
Streaming response (SSE) โ
| Event | Description | Main fields |
|---|---|---|
message_start | Marks the start of a message and returns the initial message skeleton. | message (initial usage, input/cache included) |
content_block_start | Content block start | index and content_block (type is text/thinking/tool_use) |
content_block_delta | Content delta | index and delta (see the table below) |
content_block_stop | Content block end | index |
message_delta | Message-level delta | delta.stop_reason and usage (final output_tokens) |
message_stop | Message end | - |
| delta.type | Field | Meaning |
|---|---|---|
text_delta | text | Text delta. |
thinking_delta | thinking | Reasoning process delta. |
signature_delta | signature | Integrity signature of the reasoning block (delivered before the thinking block ends). |
input_json_delta | partial_json | Tool parameter JSON fragment; accumulate it and parse as a whole. |
stop_reason enum โ
| Value | Description | Recommended handling |
|---|---|---|
end_turn | The model finished normally. | Process it normally. |
max_tokens | Output was truncated because the max_tokens limit was reached. | Raise the max_tokens value or generate the content in parts. |
stop_sequence | stop_sequences matched. | Check the stop_sequence field that matched. |
tool_use | The model requests a tool call. | Run the tool and return the result via tool_result to continue the conversation. |
pause_turn | Long-turn pause of a server tool | Return the current content unchanged and continue the request to resume. |
refusal | The model refuses to respond for security reasons. | Check whether the input triggers a security policy. |
Token usage โ
| Field | Type | Description |
|---|---|---|
input_tokens | integer | Net input tokens (excluding cache read / write operations) |
output_tokens | integer | Output tokens (including thinking content) |
cache_creation_input_tokens | integer | Number of tokens written to the cache |
cache_read_input_tokens | integer | Number of tokens read from a cache hit (billing drops sharply) |
cache_creation.ephemeral_5m_input_tokens | integer | 5 minutes TTL cache creation tokens (breakdown by TTL) |
cache_creation.ephemeral_1h_input_tokens | integer | 1 hour TTL cache creation tokens (breakdown by TTL) |
server_tool_use.web_search_requests | integer | Number of built-in web_search calls |
server_tool_use.web_fetch_requests | integer | Number of built-in web_fetch calls |
service_tier | string | Service tier actually matched |
Example: prompt caching โ
Response and execution flow โ
Streaming โ
Chat Completions โ
Specify stream=true and concatenate choices.delta.content in order. With stream_options.include_usage=true, the final usage event is also processed.
data: {"choices":[{"index":0,"delta":{"content":"Hello"}}]}
data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":12,"completion_tokens":3,"total_tokens":15}}
data: [DONE]Responses โ
Read the text from response.output_text.delta and check the final status and usage in response.completed. Also handle error and interruption events.
Messages โ
Build messages in the order message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop. Tool input is handled as a block separate from the text response.
SSE event boundaries do not match network packet boundaries. Accumulate the received data line by line and treat a blank line as the event separator.
Tool calls โ
| Protocol | Tool declaration | Model's call | Result delivery |
|---|---|---|---|
| Chat Completions | tools.function.parameters | message.tool_calls | role=tool / tool_call_id |
| Responses | tools.parameters | type=function_call | type=function_call_output / call_id |
| Messages | tools.input_schema | type=tool_use | type=tool_result / tool_use_id |
Even if a tool is declared, API does not run your user function. The application must check the function name and arguments, run it, and pass the result to the next request. In later calls that need the signature or reasoning block returned by the model, preserve those fields.
Errors and call limits โ
Call limits and error handling โ
The default call range is 30 RPM / 300K TPM. Adjust the number of concurrent requests and the retry interval based on the quota applied to the account.
| Situation | Handling |
|---|---|
| Authentication failure | Check the key's validity status and the application it is tied to |
| Invalid model / parameter | Check the model ID, protocol, and per-version allowed values |
| Call rate / token limit exceeded | Reduce requests and retry with intervals |
| Server error / timeout | Record the request ID and check whether it completed and whether duplicate execution is possible |
The quota management API is called with a TC3 signature. The Text quota is based on ApiToken. To restart cumulative quota from scratch, delete the existing quota and create it again.
Request examples โ
Use the request example for the model or protocol you want to call. Do not mix authentication methods and request fields from different paths in one request. Also check the engine documents below and the per-protocol parameters.
Result and resource management โ
Usage and cache โ
| Protocol | Input / output tokens | Cache read |
|---|---|---|
| Chat Completions | prompt_tokens / completion_tokens | prompt_tokens_details.cached_tokens |
| Responses | input_tokens / output_tokens | input_tokens_details.cached_tokens |
| Messages | input_tokens / output_tokens | cache_read_input_tokens |
Check the Messages cache creation amount in cache_creation_input_tokens. Usage fields mean different things per protocol, so do not mix them in the same formula.
Statistics and logs โ
| API | Purpose | Limit |
|---|---|---|
DescribeAigcUsageData | Per-model input / output / cache input usage | Within the last 365 days, up to 90 days at a time |
GET /v1/statistics | Request count, status codes, tokens, cache, TTFT | 2 times per second |
GET /v1/request-logs | Per-request model, tokens, latency, result code | 2 times per second / scroll_token paging |
statistics uses granularity=1m, 5m, and 1h. 1 minute / 5 minutes data is kept for 31 days, and 1 hour data is kept for 90 days. The query's app_id must match the application that owns the API key.