Skip to content

Multimodal Understanding API Reference โ€‹

Updated

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.

json
{
  "SubAppId": 123456789
}

When using the TC3 call script:

bash
python3 tencent-api.py vod CreateAigcApiToken create-token.json

Use 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 โ€‹

bash
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 โ€‹

OperationVOD actionAuth
IssueCreateAigcApiTokenTC3 signature
ListDescribeAigcApiTokensTC3 signature
DeleteDeleteAigcApiTokenTC3 signature
Query quotaDescribeAigcQuotasTC3 signature
Create / change / delete quotaCreateAigcQuota / ModifyAigcQuota / DeleteAigcQuotaTC3 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 โ€‹

ProtocolRequest pathCentral input fieldCentral result field
Chat CompletionsPOST /v1/chat/completionsmessageschoices.message
ResponsesPOST /v1/responsesinputoutput
MessagesPOST /v1/messagesmessages / systemcontent

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 โ€‹

HeaderRequiredValue / purpose
AuthorizationRequiredBearer ${VOD_API_TOKEN}
Content-TypeRequiredapplication/json
x-api-keyOptionalAPI key header available in Messages integration
X-Request-IdOptionalRequest trace ID
Tx-User-Session-IdOptionalSession ID that links requests in the same conversation

List callable models โ€‹

bash
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 โ€‹

ParameterRequiredTypeDescription
modelRequiredStringModel ID
messagesRequiredArrayConversation history including role and content
streamOptionalBooleanWhether to use SSE streaming
max_tokensOptionalIntegerMaximum number of generation tokens. Includes reasoning tokens
max_completion_tokensOptionalIntegerSDK-compatible generation token limit. Do not specify together with max_tokens
temperatureOptionalNumberSampling temperature. See each model's document for the allowed range
top_pOptionalNumberSampling based on cumulative probability
top_kOptionalIntegerLimit on candidate tokens for supported models
reasoning_effortOptionalStringReasoning effort per model
thinking_enabledOptionalBooleanWhether reasoning is enabled for supported models
toolsOptionalArrayCallable tools and input schema
tool_choiceOptionalString / ObjectAuto select, force tool use, or select a specific tool
response_formatOptionalObjectPlain text, JSON, or JSON Schema output
stream_optionsOptionalObjectReceive 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 โ€‹

FieldTypeDescription
roleStringsystem / developer / user / assistant / tool
contentString / ArrayText or an array of media parts
tool_callsArrayFunction name and arguments requested by the model
tool_call_idStringID that links a tool result to the original call

Response example โ€‹

json
{
  "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 โ€‹

ParameterRequiredTypeDescription
modelRequiredStringModel ID
inputRequiredString / ArrayInput text, messages, tool results
instructionsOptionalStringResponse instructions for the model to follow
max_output_tokensOptionalIntegerMaximum output tokens including reasoning
reasoningOptionalObjectReasoning settings for supported models such as effort
textOptionalObjectOutput format and text settings for supported models
toolsOptionalArrayFunction name, description, parameter schema
tool_choiceOptionalString / ObjectTool selection method
streamOptionalBooleanWhether to use SSE streaming

Request example โ€‹

json
{
  "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 โ€‹

json
{
  "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 โ€‹

ParameterRequiredTypeDescription
modelRequiredStringModel ID
messagesRequiredArrayuser / assistant conversation history
max_tokensRequiredIntegerMaximum generation tokens
systemOptionalString / ArrayResponse instructions kept separate from the conversation history
streamOptionalBooleanWhether to use SSE streaming
temperatureOptionalNumberSampling temperature for supported models
top_p / top_kOptionalNumber / IntegerSampling settings for supported models
thinkingOptionalObjectReasoning method and budget for supported models
output_configOptionalObjectOutput settings such as reasoning effort for supported models
toolsOptionalArrayname, description, input_schema
tool_choiceOptionalObjectTool selection methods such as auto, any, tool
stop_sequencesOptionalArrayList of strings that stop generation

Request example โ€‹

json
{
  "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 โ€‹

json
{
  "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 โ€‹

ProtocolWhere to setExample
Chat CompletionsTop-level reasoning_effort"reasoning_effort": "high"
Chat CompletionsSupported models' thinking_enabled"thinking_enabled": true
Responsesreasoning.effort"reasoning": {"effort": "high"}
MessagesPer-model thinking / output_configSee 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 โ€‹

typeInput fieldContent
texttextQuestions and instructions
image_urlimage_url.urlImage URL or data URL
video_urlvideo_url.urlVideo URL
input_audioinput_audioAudio URL or data / format
filefile.file_url / file.file_data / file.file_nameFile 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 โ€‹

ParameterTypeRequiredDefaultDescription
modelStringRequired-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.
messagesArrayRequired-Array of chat context messages. See Messages parameters.
streamBooleanOptionalfalseWhether to enable streaming output (SSE).
stream_optionsObjectOptional-Streaming options. Applies only when stream=true.
stream_options.include_usageBooleanOptionalfalseWhether 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 โ€‹

FieldTypeRequiredDescription
roleStringRequiredFixed to "system"
contentStringRequiredSystem instructions that set model behavior and context.
FieldTypeRequiredDescription
roleStringRequiredFixed to "user"
contentString or ArrayRequiredPlain text maps to a string; multimodal content maps to an array (see Content Part below).
FieldTypeDescription
typeStringContent type: "text" / "image_url" / "video_url" / "file_url"
textStringText content when type="text".
image_urlObjectImage information when type="image_url".
image_url.urlStringImage HTTP(S) URL, or a Data URL in data:image/...;base64,... format
image_url.detailStringImage resolution policy: "auto" / "low" / "high". The default is "auto".
video_urlObjectVideo information when type="video_url".
video_url.urlStringVideo HTTP(S) URL.
file_urlObjectFile information when type="file_url".
file_url.urlStringFile HTTP URL (only direct HTTP links are supported; Base64 is not).
FieldTypeRequiredDescription
roleStringRequiredFixed to "assistant"
contentStringOptionalModel response text (required if tool_calls is absent).
reasoning_contentStringOptionalReasoning chain content. Returned with the model response when thinking; pass it back unchanged to keep context continuity in multi-turn conversations.
reasoning_detailsArrayOptionalArray of reasoning chain blocks that include signatures. Pass them back unchanged to keep context continuity in multi-turn conversations.
tool_callsArrayOptionalList of tool calls. See tool call parameters.
prefixBooleanOptionalSupported 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.
FieldTypeRequiredDescription
roleStringRequiredFixed to "tool"
contentStringRequiredResult content returned by the tool function (JSON string format recommended).
tool_call_idStringRequiredThe value corresponding to assistant.tool_calls.id.
nameStringOptionalTool function name.

Generation control parameters โ€‹

ParameterTypeRequiredDefaultValue rangeDescription
temperatureFloatOptional1.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_pFloatOptional1.0(0.0, 1.0]Nucleus sampling probability threshold. top_p=0 is normalized to null on the platform (same as the default).
max_tokensIntegerOptionalModel maximumโ‰ฅ 1Maximum number of tokens that can be generated in a single response. If this limit is exceeded, finish_reason is "length".
max_completion_tokensIntegerOptionalModel maximumโ‰ฅ 1Maximum 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.
nIntegerOptional1โ‰ฅ 1Number 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.
stopString or ArrayOptional-Up to 4Stop sequences. Generation stops immediately when a matching sequence appears. Exceeding 4 is rejected during validation.
seedIntegerOptional-Any integerRandom seed. With the same seed, the system does its best to guarantee consistent output.
frequency_penaltyFloatOptional0[-2.0, 2.0]Frequency penalty. Positive values lower the probability of repeating tokens that already appeared. 0 is normalized to null.
presence_penaltyFloatOptional0[-2.0, 2.0]Presence penalty. Positive values encourage generating new topics. 0 is normalized to null.
logprobsBooleanOptionalfalse-Whether to return log probabilities of output tokens.
top_logprobsIntegerOptional0[0, 20]Returns the top N tokens by probability at each position. logprobs=true is required; otherwise validation fails.
reasoning_effortStringOptional-"low" / "medium" / "high"Reasoning depth. Applies to reasoning models. An internal mapping conversion is applied to Hunyuan models.

Response format parameters โ€‹

ParameterTypeRequiredDefaultDescription
response_formatObjectOptional{"type":"text"}Controls the response format.
response_format.typeStringRequired"text"Format type: "text" / "json_object" / "json_schema".
response_format.json_schemaObjectConditional-Required when type="json_schema". Defines the output JSON structure.
response_format.json_schema.nameStringRequired-Schema name.
response_format.json_schema.schemaObjectRequired-JSON Schema definition (follows the JSON Schema specification).
response_format.json_schema.strictBooleanOptionalfalseWhether to enforce strict Schema matching.

Tool call parameters โ€‹

ParameterTypeRequiredDefaultDescription
toolsArrayOptional-List of tool definitions.
tools.typeStringRequired-Fixed to "function".
tools.functionObjectRequired-Function definition.
tools.function.nameStringRequired-Tool function name (letters, digits, underscores, and hyphens only).
tools.function.descriptionStringOptional-Describes the tool function so the model can judge when to call it.
tools.function.parametersObjectOptional{}Input parameter definition (JSON Schema object format).
tool_choiceString or ObjectOptional"auto"Tool call policy. See the enum below for details.
parallel_tool_callsBooleanOptionaltrueWhether to allow parallel calls to multiple tools.
ValueDescription
"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 โ€‹

ParameterTypeRequiredDefaultDescriptionApplicable models
thinkingObjectOptional-Thinking mode control (standard method)Thinking models (e.g. Hy and DeepSeek)
thinking.typeStringRequired-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_tokensIntegerOptional8192 (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_thinkingBooleanOptional-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_budgetIntegerOptional-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_thinkingBooleanOptional-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_splitBooleanOptional-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 โ€‹

ParameterTypeRequiredDefaultDescriptionApplicable models
prompt_cache_keyStringOptional-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 โ€‹

ParameterTypeRequiredDefaultDescription
userStringOptional-End-user identifier. Passed through to the model service unchanged for abuse detection and usage tracking.
user_idString or NumberOptional-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_identifierStringOptional-Security identifier. Used by the risk control system to track user-level content moderation.
extra_bodyObjectOptional-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 โ€‹

FieldTypeDescription
idStringUnique request identifier in chatcmpl-{uuid} format (generated by the platform, unrelated to the ID returned by the model service).
objectStringObject type, fixed to "chat.completion".
createdIntegerCreation time (Unix timestamp, in seconds).
modelStringThe original model name passed in the user request (not the model name actually used by the model service).
choicesArrayList of candidate results; the number of elements equals n specified in the request.
usageObjectToken usage statistics. See the "usage" object for details.
search_infoObject or nullWeb search information (included when using the Hunyuan/AISearch path; otherwise null).

Choices array elements โ€‹

FieldTypeDescription
indexIntegerIndex of the option within the choices array, starting from 0.
messageObjectResponse message object. See message object.
finish_reasonStringReason generation finished. See the enum below.
logprobsObject or nullToken probability information (logprobs=true must be set in the request).
ValueDescriptionRecommended 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.
FieldTypeDescriptionApplicable scenario
roleStringFixed to "assistant"All
contentString or nullResponse text content. When tool_calls is present, it can be null.All
reasoning_contentStringReasoning chain / reasoning process contentThinking models
reasoning_detailsArrayArray of reasoning chain blocks (including signature)Thinking models
tool_callsArrayList of tool callsFunction calling
refusalString or nullRefusal reasonContent security filtering
FieldTypeDescription
idStringUnique tool call ID in call_{uuid} format.
typeStringFixed to "function".
function.nameStringName of the function being called.
function.argumentsStringFunction parameters (JSON string format; parse with JSON.parse before use).

Usage object โ€‹

FieldTypeDescription
prompt_tokensIntegerNumber of input tokens (including tokens for system, messages, and tool definitions).
completion_tokensIntegerNumber of output tokens (including reasoning tokens).
total_tokensIntegerTotal number of tokens
cache_read_tokensIntegerNumber of tokens read from a Prompt Cache hit (available on some models; can reduce billing).
cache_write_tokensIntegerNumber of tokens written to the Prompt Cache (available on some models).
prompt_tokens_detailsObjectInput token breakdown (available on some models).
prompt_tokens_details.cached_tokensIntegerNumber of cached tokens
completion_tokens_detailsObjectOutput token breakdown (available on some models).
completion_tokens_details.reasoning_tokensIntegerNumber of tokens used for reasoning (OpenAI-compatible path).
completion_tokens_details.audio_tokensIntegerNumber of tokens used for audio output
FieldTypeDescription
objectStringFixed to "chat.completion.chunk".
choices.deltaObjectIncremental content.
choices.delta.roleStringAppears only in the first chunk; the value is "assistant".
choices.delta.contentStringIncremental text fragment; concatenating them cumulatively produces the complete response.
choices.delta.reasoning_contentStringIncremental reasoning chain fragment (output before content in reasoning chain mode).
choices.delta.reasoning_detailsArrayIncremental reasoning chain blocks (including signature. Collect them completely after the stream ends and return them across turns).
choices.delta.tool_callsArrayIncremental tool calls (including the index field that identifies the array position).
choices.delta.search_resultsArrayIncremental web search results (pushed in the stream by some models).
choices.finish_reasonString or nullnull while generating; changes to the finish reason on completion.
usageObject or nullIncluded only in the last formal chunk when include_usage=true.
ScenarioHandling
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 sentThe 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 โ€‹

ParameterTypeRequiredDescription
modelStringOptionalModel ID used to generate the response (e.g. hy3).
inputString or ArrayOptionalText, 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.
instructionsStringOptionalSystem (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.
streamBooleanOptionalWhen 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 โ€‹

ParameterTypeValue rangeDescription
max_output_tokensNumberโ‰ฅ 1Maximum 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.
temperatureNumber[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_pNumber(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.
truncationString"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 โ€‹

ParameterTypeDescription
toolsArrayArray of tools the model can call when generating a response. Supports function calling, file search, web search, and more. See tool type description.
tool_choiceString or ObjectHow the model selects tools. See the table below for concrete values.
parallel_tool_callsBooleanWhether to allow the model to run tool calls in parallel.
Value / typeDescription
"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 typeDescription
{ "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).
ValueDescription
file_search_call.resultsContains search results from file search tool calls.
web_search_call.resultsContains results from web search tool calls.
message.input_image.image_urlContains image URLs in input messages.
code_interpreter_call.outputsContains code interpreter execution output.
reasoning.encrypted_contentContains an encrypted version of reasoning tokens used for stateless multi-turn conversations.
message.output_text.logprobsContains log probabilities of assistant messages.

Reasoning control โ€‹

FieldTypeDescription
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 โ€‹

ParameterTypeDescription
backgroundBooleanWhether to run asynchronously in the background. All models accept this parameter, but in practice all return synchronously.
storeBooleanWhether 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.
metadataObjectKey-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_tierStringService tier: auto / default / flex / scale / priority.
FieldTypeDescription
contentString or ArrayText, 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.
FieldTypeDescription
detail"low" / "high" / "auto" / "original"Image detail level; the default is auto.
type"input_image"Type; always input_image.
file_idStringOptional. File ID.
image_urlStringOptional. Image URL or base64-encoded data URL.
FieldTypeDescription
type"input_file"Type; always input_file.
file_dataStringOptional. File content (base64 encoded).
file_idStringOptional. File ID.
file_urlStringOptional. File URL.
filenameStringOptional. File name.
FieldTypeDescription
type"function"Type; always function.
nameStringFunction name
parametersObjectJSON Schema object describing the function parameters.
strictBooleanWhether to enforce strict parameter validation. The default is true.
descriptionStringOptional. Function description the model uses to judge whether to call it.
FieldTypeDescription
type"file_search"Type; always file_search.
vector_store_idsString arrayList of vector store IDs to search.
max_num_resultsNumberOptional. Maximum number of results to return; the range is 1-50.
filtersComparisonFilter or CompoundFilterOptional. Filter conditions. See filter types.
FieldTypeDescription
idStringUnique identifier of the response.
object"response"Object type; always response.
created_atNumberUnix timestamp (seconds) when the response was created.
statusStringResponse status: completed / incomplete / failed / in_progress / cancelled.
completed_atNumberUnix timestamp (seconds) when the response completed.
errorObjectError object returned when the request fails. Not returned on successful completion.
incomplete_detailsObjectDetails when the response is truncated. The reason field can be "max_output_tokens" or "content_filter".
instructionsStringReturns the system message passed in the request unchanged.
max_output_tokensNumberMaximum output tokens specified in the request. Not returned if unspecified.
modelStringModel ID used to generate the response.
outputArrayList of output items generated by the model. See output item types.
parallel_tool_callsBoolean or nullWhether parallel tool calls are allowed.
previous_response_idStringID of the previous response in a multi-turn conversation. Not returned for single-turn conversations.
usageObjectToken consumption statistics. See ResponseUsage object.
service_tierStringService tier actually used.
FieldTypeDescription
input_tokensNumberNumber of input tokens.
input_tokens_detailsObjectInput token details, including cached_tokens
output_tokensNumberNumber of output tokens.
output_tokens_detailsObjectOutput token details, including reasoning_tokens
total_tokensNumberTotal number of tokens (input + output).
FieldTypeDescription
idStringUnique ID of the output message.
type"message"Type; always message.
role"assistant"Role; always assistant.
status"in_progress" / "completed" / "incomplete"Message status.
contentArrayArray of message content. Each item includes the type: "output_text" and text fields.
FieldTypeDescription
idStringUnique ID.
type"function_call"Type; always function_call.
call_idStringFunction call ID; it must be passed when submitting function_call_output.
nameStringName of the function being called.
argumentsStringJSON string of the function parameters.
statusStringin_progress / completed / incomplete.
FieldTypeDescription
idStringUnique ID.
type"reasoning"Type; always reasoning.
summaryArrayList of reasoning summary texts. Each item includes the type: "summary_text" and text fields.
statusStringStatus.

Example: reasoning model โ€‹

FieldTypeDescription
keyStringKey of the attribute to compare
type"eq" / "ne" / "gt" / "gte" / "lt" / "lte" / "in" / "nin"Comparison operator
valueString / Number / Boolean / ArrayValue to compare
FieldTypeDescription
type"and" / "or"Operation type
filtersArrayArray 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 โ€‹

ParameterTypeRequiredDescription
modelstringRequiredName of the model to use. Example: deepseek-v4-flash.
messagesarrayRequiredList 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.
systemstring or arrayOptionalSystem prompt. Not included in messages; passed separately through the top-level system field. This is the main difference from the OpenAI Chat protocol.
max_tokensintegerRequiredMaximum 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".
streambooleanOptionalWhether to enable streaming responses (default: false). When true, the response is returned event by event in SSE format.

Generation control parameters โ€‹

ParameterTypeRangeDescription
temperaturefloat[0, 1]Sampling temperature. The Messages protocol's range is [0, 1], different from OpenAI's [0, 2].
top_pfloat(0, 1]Nucleus sampling. In general, adjust only one of temperature and top_p.
top_kinteger-Samples only from the top K tokens by probability. Messages-protocol-specific parameter; not present in the OpenAI Chat protocol.
stop_sequencesstring[]-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 โ€‹

FieldTypeRequiredDescription
namestringRequiredTool name.
descriptionstringOptionalDescribes the tool's purpose so the model can judge when to call it.
input_schemaobjectRequiredParameter definition that follows the JSON Schema format.
typestringOptionalLeave empty for regular tools. For built-in tools, enter the type name (e.g. web_search_20250305).
max_usesintegerOptionalMaximum number of calls per session for built-in tools.
cache_controlobjectOptionalCache flag at the tool definition level.
Messages tool_choiceEquivalent OpenAI valueDescription
{"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) โ€‹

FieldTypeRequiredDescription
typestringRequiredEnable is "enabled" / disable is "disabled" / adaptive mode is "adaptive".
budget_tokensintegerConditionalRecommended when enabled. Thinking chain token budget (recommended range: 1024~32000). The value must be less than max_tokens.
displaystringOptionalHow the reasoning process is displayed (supported by some models).

Output composition โ€‹

FieldTypeDescription
effortstringOutput job level: low / medium / high / xhigh / max.
format.typestringStructured output type (e.g. json_schema).
format.schemaobjectJSON Schema definition.

Caching (prompt caching) โ€‹

LevelTag locationDescription
Tool leveltools[n].cache_controlTool definition cache
System levelsystem[n].cache_controlSystem content block cache
Message / content block levelmessages[n].content[m].cache_controlCache of past messages or content blocks

Metadata and service tier โ€‹

ValueDescription
autoAuto select
standardStandard tier
priorityPriority tier (higher guarantees)
batchBatch tier

Request headers โ€‹

Request headerRequiredDescription
x-api-keyRequiredAPI key (Messages protocol rule); the platform also supports Authorization: Bearer <key>.
anthropic-versionRequiredAPI version, fixed to 2023-06-01.
content-typeRequiredapplication/json
anthropic-betaOptionalBeta feature switch (e.g. prompt-caching and interleaved-thinking); the platform passes it through to the model service transparently and unchanged.
roleDescriptionWhere used
userHuman user input (including tool_result)Odd-numbered conversation turns.
assistantThe model's past responses (can include text / thinking / tool_use)Used in even-numbered turns. In multi-turn conversations, pass the past context.
Block typeMain fieldsApplicable roleDescription
texttext, cache_controluser / assistantText content
imagesourceuserImage
videosourceuserVideo
documentsource, title, context, citations, cache_controluserDocument input and citations
search_resultsource, title, content, citationsuserSearch result content block
tool_useid, name, inputassistantModel request asking for a tool call
tool_resulttool_use_id, contentuserTool execution result
thinkingthinking, signatureassistantReasoning chain content
redacted_thinkingdataassistantEdited reasoning chain
source fieldTypeDescription
typestring"base64" or "url".
media_typestringRequired when base64 is selected. Example: image/jpeg, image/png, image/gif, or image/webp.
datastringImage data when base64 is selected.
urlstringImage address when url is selected.
detailstringlow / high / auto that specifies the image analysis detail level.
FieldTypeDescription
idstringUnique ID of the tool call; it must be returned in the corresponding tool_result.
namestringName of the tool to call.
inputobjectTool parameters (an object, not a JSON string; different from OpenAI's arguments string).
FieldTypeDescription
tool_use_idstringCorresponds to tool_use.id.
contentstring or arrayTool result; it can be plain text or an array of content blocks (text+image supported).
is_errorbooleanSet to true when tool execution fails.
cache_controlobjectCache flag.
FieldTypeDescription
thinkingstringText of the model's reasoning process
signaturestringIntegrity signature of the reasoning block

Non-streaming response โ€‹

FieldTypeDescription
idstringUnique identifier of the response (prefix msg_).
typestringFixed to "message".
rolestringFixed to "assistant".
modelstringName of the model actually used.
contentarrayArray of content blocks; the usual order is thinking โ†’ text โ†’ tool_use.
stop_reasonstringStop reason. See the enum below.
stop_sequencestring or nullThe stop sequence that matched (when stop_sequences matched).
usageobjectToken usage. See token usage.
containerobjectCode execution container information (id, expires_at). Returned only when the built-in code_execution tool is used.
service_tierstringService tier actually matched.

Streaming response (SSE) โ€‹

EventDescriptionMain fields
message_startMarks the start of a message and returns the initial message skeleton.message (initial usage, input/cache included)
content_block_startContent block startindex and content_block (type is text/thinking/tool_use)
content_block_deltaContent deltaindex and delta (see the table below)
content_block_stopContent block endindex
message_deltaMessage-level deltadelta.stop_reason and usage (final output_tokens)
message_stopMessage end-
delta.typeFieldMeaning
text_deltatextText delta.
thinking_deltathinkingReasoning process delta.
signature_deltasignatureIntegrity signature of the reasoning block (delivered before the thinking block ends).
input_json_deltapartial_jsonTool parameter JSON fragment; accumulate it and parse as a whole.

stop_reason enum โ€‹

ValueDescriptionRecommended handling
end_turnThe model finished normally.Process it normally.
max_tokensOutput was truncated because the max_tokens limit was reached.Raise the max_tokens value or generate the content in parts.
stop_sequencestop_sequences matched.Check the stop_sequence field that matched.
tool_useThe model requests a tool call.Run the tool and return the result via tool_result to continue the conversation.
pause_turnLong-turn pause of a server toolReturn the current content unchanged and continue the request to resume.
refusalThe model refuses to respond for security reasons.Check whether the input triggers a security policy.

Token usage โ€‹

FieldTypeDescription
input_tokensintegerNet input tokens (excluding cache read / write operations)
output_tokensintegerOutput tokens (including thinking content)
cache_creation_input_tokensintegerNumber of tokens written to the cache
cache_read_input_tokensintegerNumber of tokens read from a cache hit (billing drops sharply)
cache_creation.ephemeral_5m_input_tokensinteger5 minutes TTL cache creation tokens (breakdown by TTL)
cache_creation.ephemeral_1h_input_tokensinteger1 hour TTL cache creation tokens (breakdown by TTL)
server_tool_use.web_search_requestsintegerNumber of built-in web_search calls
server_tool_use.web_fetch_requestsintegerNumber of built-in web_fetch calls
service_tierstringService 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.

text
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 โ€‹

ProtocolTool declarationModel's callResult delivery
Chat Completionstools.function.parametersmessage.tool_callsrole=tool / tool_call_id
Responsestools.parameterstype=function_calltype=function_call_output / call_id
Messagestools.input_schematype=tool_usetype=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.

SituationHandling
Authentication failureCheck the key's validity status and the application it is tied to
Invalid model / parameterCheck the model ID, protocol, and per-version allowed values
Call rate / token limit exceededReduce requests and retry with intervals
Server error / timeoutRecord 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 โ€‹

ProtocolInput / output tokensCache read
Chat Completionsprompt_tokens / completion_tokensprompt_tokens_details.cached_tokens
Responsesinput_tokens / output_tokensinput_tokens_details.cached_tokens
Messagesinput_tokens / output_tokenscache_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 โ€‹

APIPurposeLimit
DescribeAigcUsageDataPer-model input / output / cache input usageWithin the last 365 days, up to 90 days at a time
GET /v1/statisticsRequest count, status codes, tokens, cache, TTFT2 times per second
GET /v1/request-logsPer-request model, tokens, latency, result code2 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.

Built with VitePress ยท Deployed on Tencent EdgeOne Pages