Create a response
Use the OpenAI-compatible Responses API to call the Qwen model. This topic describes the input and output parameters and provides a call example.
Advantages over the OpenAI Chat Completions API:- Built-in tools: Get better results on complex tasks with built-in tools like web search, web scraping, a code interpreter, text-to-image, image-to-image, and knowledge base search. For more information, see tool calling.
- More flexible input: Supports both direct string input and message arrays in the chat format.
- Simplified context management: Avoid manually constructing a message history array by passing the
previous_response_idfrom the last response. - Convenient context caching: Add
x-dashscope-session-cache: enable(default value: disable) to the request header to enable automatic server-side caching of the conversation context. This reduces inference latency and costs for multi-turn conversations with no code changes required. For details, see session cache.
Compatibility and limitations
This API is compatible with OpenAI to reduce developer migration cost, but differs in its parameters, functionality, and behavior.
Core Principle: Only the parameters explicitly listed in this document are processed. Any OpenAI parameters not mentioned are ignored.
The following key differences will help you adapt quickly:
- Unsupported Parameters: This API does not support some OpenAI API parameters, such as the asynchronous execution parameter
background. The API currently supports only synchronous calls. - Reasoning Effort Control: Use the
reasoning.effortparameter to control the model's reasoning effort. For usage details, see the description of this parameter. - Context Limit: To reserve space for built-in tool calls and reasoning generation, the maximum input context of the Responses API is approximately 80% of the model's context window (leaving a buffer of about 20%). Any excess is automatically truncated without raising an error or interrupting the request.
China (Beijing)
SDK call configuration base_url: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
HTTP request endpoint: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/responses
Singapore
SDK call configuration base_url: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
HTTP request endpoint: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/responses
US (Virginia)
SDK call configuration base_url: https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1
HTTP request endpoint: POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1/responses
Germany (Frankfurt)
SDK call configuration base_url: https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1
HTTP request endpoint: POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1/responses
Japan (Tokyo)
SDK call configuration base_url: https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1
HTTP request endpoint: POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1/responses
China (Hong Kong)
SDK call configuration base_url: https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1
HTTP request endpoint: POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1/responses
Replace {WorkspaceId} with your actual workspace ID.
ImportantAlibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing), Singapore, and China (Hong Kong) regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:
- China (Beijing): from
https://dashscope.aliyuncs.comtohttps://{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore: from
https://dashscope-intl.aliyuncs.comtohttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} is your workspace ID, which can be found on the Workspace Details page in the Alibaba Cloud Model Studio console. The existing domain remains fully functional.
ImportantThe legacy URL path /api/v2/apps/protocols/compatible-mode/v1/responses for the OpenAI-compatible Responses API is no longer maintained and its functionality is no longer guaranteed. Migrate to the new path /compatible-mode/v1/responses as soon as possible.
Request bodymodel The ID of the model to use. Supported models
ImportantText generation models not in the list above but available through Alibaba Cloud Model Studio support only basic compatibility features. Agent capabilities (built-in tools, etc.) are limited. input The input for the model. The following formats are supported:
Array item types EasyInputMessage An object with a Properties role The role of the message's author. Valid values: content The message content. Supported formats:
Array element types One of the following: input_text Text input. Properties type Fixed as text The text content to input to the model. prompt_cache_breakpoint Supported only by Properties mode Only input_image Image input. User role only. Properties type Fixed as image_url The public URL or Base64-encoded data of the image. For Base64, provide a complete Data URI, for example: prompt_cache_breakpoint Supported only by Properties mode Only input_file File input. User role only. Currently supported by Properties type Fixed as file_url The public URL of a PDF file, up to 100 MB. The PDF page limit depends on prompt_cache_breakpoint Supported only by Properties mode Only input_audio Audio input. Supported only for Properties type Fixed as format The audio format, for example audio_url The URL of the audio. Use either data A complete data URI containing a MIME type prefix and Base64-encoded audio, such as use_multichannel Specifies whether to process the audio as spatial audio. Defaults to input_video Video input. Supported only for Properties type Fixed as video_url The URL of the video. fps The frame sampling rate, which specifies how many frames to sample per second. For example, output_text Assistant reply. Assistant role only. Properties type Fixed as text The text content of the assistant reply. Audio and video inputs use the same response format and streaming events as text inputs. Streaming text uses type Fixed as ResponseOutputMessage The model's output message. To continue a conversation, you can pass the Properties type Fixed as id The unique identifier of the output message, from the previous response. role Fixed as status The message status. Valid values: content An array of content, where elements are Properties type Fixed as text The response text. annotations Annotation information. Function call A structured instruction generated when the model decides to call an external tool. Properties type Fixed as id The unique identifier for the function call, from the previous response. name The name of the tool function. arguments The tool call arguments, in JSON string format. call_id The identifier for the tool call. This must match the status The status. Valid values: Function call output The output of a tool call. In the message list, this object must immediately follow its corresponding Properties type Fixed as id The unique identifier for the function call output. call_id The tool call identifier must match the output The execution result of the tool function. Pass a Array element types One of the following. input_text Text result. Properties type Fixed as text The text content. input_image Image result. Properties type Fixed as image_url The public URL or Base64-encoded data of the image. For Base64, provide a complete Data URI, for example: status The status. Valid values: Reasoning The model's reasoning process. You can pass the Properties type Fixed as id The unique identifier for the reasoning content, from the previous response. encrypted_content
summary The reasoning summary content. Properties type Fixed as text The summary text. status The status. Valid values: Web Search Call A web search call object. You can pass back the web_search_call item from the previous response's output to the input, providing search result context in multi-turn conversations. Properties type Always id The unique identifier of the search call, from the previous response. status The search status. Valid values: action The search action details. Only the Properties type The search type. Always queries A list of search queries. Each element is a string. sources A list of search result sources. Properties type The source type. Always url The source URL. instructions It is inserted at the beginning of the context as a system instruction. When previous_response_id The unique ID of the previous response. A response's conversation The conversation that the current response belongs to (see the Conversations API). The conversation's history is automatically included as context. The input and output of this request are added to the conversation upon completion. Cannot be used with prompt_cache_options Supported only by Properties mode
ttl Cache TTL. Supports stream Enables stream output. If set to store Specifies whether to store the model response generated for this session.
tools An array of tools the model can call when generating a response. Supports both built-in tools and custom
For Properties Web search Searches the internet for up-to-date information. Related documentation: Web Search Properties type Fixed as Example: Accesses and extracts content from web pages. It must be used with the Properties type Fixed as Example: A code interpreter tool that allows the model to execute code and return results, supporting tasks like data analysis. For Properties type Fixed as Example: Searches for images based on a text description. Related documentation: Text-to-Image Search Properties type Fixed as Example: Searches for similar or related images based on an input image. The input must include the image's URL. Related documentation: Image-to-Image Search Properties type Fixed as Example: Performs knowledge retrieval by searching a specified knowledge base. Related documentation: Knowledge Retrieval Properties type Fixed as vector_store_ids The ID of the knowledge base to search. Currently, only one knowledge base ID can be provided. Example: Calls an external service through the Model Context Protocol (MCP). Related documentation: MCP Properties type Fixed as server_protocol The communication protocol with the MCP service, such as server_label A label used to identify the MCP service. server_description A description of the service. It helps the model understand its function and when to use it. server_url The URL of the MCP service endpoint. headers Request headers, used to carry information such as authentication (e.g., Example: Allows the model to call a developer-defined function. When the model determines that a tool needs to be called, the response returns an output item of type Properties type Must be set to name The name of the tool. Can only contain letters, digits, underscores ( description A description of the tool, which helps the model decide when and how to call it. parameters The parameter definition for the tool, which must be a valid JSON Schema object. If
Example: tool_choice Controls how the model selects and calls tools. This parameter supports two formats: string mode and object mode. String mode
Restricts the model to a specific set of tools for selection and calling. Properties mode
tools A list of tool definitions that the model is allowed to call. type The type of tool configuration. Fixed as parallel_tool_calls Specifies whether to enable parallel tool calling. For more information, see Parallel tool calling.
Valid values:
temperature
The sampling temperature, which controls the diversity of the generated text. Higher values make the output more random and diverse, while lower values make it more focused and deterministic. Value range: [0, 2) Both top_p
The probability threshold for top-p sampling, which controls the diversity of the generated text. Higher values make the output more random and diverse, while lower values make it more focused and deterministic. Value range: (0, 1.0] Both enable_thinking Enables or disables reasoning mode. When enabled, the model performs a reasoning step before it responds. The reasoning process is returned as an output item of type Valid values:
For default values for different models, see Supported models.
reasoning Controls the model's reasoning effort. The model performs a reasoning step before replying, and the reasoning process is returned through an output item of type For kimi-k3.1-pro (deployed by Alibaba Cloud Model Studio), Properties For kimi-k3.1-pro, use the supported levels and default value described above. The following applies to other models. effort
Default:
When only Supports 7 incremental levels:
For summary
Full thinking is returned by default. When enabled, raw thinking is no longer returned in plaintext: the model returns a summary for display and the encrypted full thinking for restoring reasoning history.
ocr_options OCR built-in task parameters. Only applicable to the When parsing PDF files, the value of
max_output_tokens For Limits the number of tokens in the generated output.
The minimum value for the models listed above is 16. When the generated token count reaches the configured limit, generation stops early and the status is text Configuration for the model's text output. The output can be plain text or structured JSON data. Properties format The format that the model must output. Defaults to One of the following: ResponseFormatText The default format. Outputs a text response. Properties type Fixed as ResponseFormatTextJSONSchemaConfig Outputs a JSON string that strictly conforms to the specified JSON Schema, giving you precise control over the output structure and field types. Supported by the qwen3.8 series, the deepseek-v4 series, the glm-5 series, and other models; the deepseek-v4.1 series will support it soon. With this type, the prompt does not need to contain the JSON keyword. Properties type Fixed as json_schema The JSON Schema configuration. Properties name The name of the schema. schema The JSON Schema object that describes the output structure. Use strict Whether to strictly follow the structure defined by ResponseFormatJSONObject Outputs a standard JSON-formatted string. Supported by the qwen3.8 series, the deepseek-v4 series, the deepseek-v4.1 series, the glm-5 series, and kimi-k3.1-pro (deployed on Alibaba Cloud Model Studio). With this type, explicitly instruct the model to output JSON in the prompt, for example "Please output in JSON format". Otherwise, an error is returned. Properties type Fixed as | Basic callStream outputMulti-turn conversationBuilt-in toolsFunction callingMultimodal tool resultsDocument understandingSession cacheTo enable Session caching, set Automatic implicit caching is described separately in Context cache. Session cache uses exact matching. The rules are as follows:
To check the number of tokens that hit the cache, read |
Response object (non-streaming output)id A unique identifier for this response, a UUID. This ID is valid for 7 days and can be used in the created_at The Unix timestamp (in seconds) for this request. object The object type, which is always status The status of the response generation. Valid values:
model The ID of the model used to generate the response. output An array of output items generated by the model. The type and order of elements in the array depend on the model's response. Array element properties type The output item type. Valid values:
id The unique identifier of the output item. All types of output items contain this field. role The role of the message is always status The status of the output item. Valid values: name The name of the tool or function. This parameter is present when For For arguments The parameters for the tool call, in a JSON string format. This parameter is present when
call_id The unique ID for the function call. This parameter is included only when content The array of message content. This parameter is present only if Array element properties type The content type. The value is fixed to text The text content generated by the model. annotations The array of text annotations. This is usually an empty array. encrypted_content
summary An array of reasoning summaries. This field is present only when action The information about the search action. This parameter is present only when Properties query The search query keywords. type The search type. The value is always sources A list of search sources. Each element contains the code The code generated and executed by the model. This exists only when outputs The code execution output array. This is present only when container_id The container identifier for the code interpreter. This parameter is present only when goal A description of the information to extract from the webpage. This parameter is available only when output The output of the tool call. The output is a string.
urls The list of URLs for the extracted web pages. This parameter is available only when server_label The label for the MCP service. This appears only when queries A list of queries for knowledge base retrieval. This parameter exists only when results An array of search results from the knowledge base. This parameter is present only when Array element properties file_id The file ID of the matched document. filename The file name of the matched document. score The relevance score of the match. The value ranges from 0 to 1. A larger value indicates higher relevance. text The content snippet from the matched document. tool_usage Tool usage statistics for this request, recorded separately from model token usage in Properties web_search Properties num_requests The number of billable searches. code_interpreter Properties num_requests The number of code interpreter executions. web_extractor Properties num_requests The number of web page content extraction requests. image_search Properties num_requests The number of image-to-image searches. web_search_image Properties num_requests The number of text-to-image searches. pdf_page_parser Properties num_requests The number of PDF pages parsed. prompt_cache_options Supported only by Properties mode
ttl
usage Information about the token consumption for this request. Qwen4 series, Kimi-K3.1 series, and subsequent new models use the new response structure below. Properties input_tokens The number of tokens in the input. Additional Notes output_tokens The number of tokens in the model's output. total_tokens The total number of tokens consumed is the sum of input_tokens_details A fine-grained classification of input tokens. Properties cached_tokens The number of tokens that hit the cache. For more information, see context caching. output_tokens_details A detailed breakdown of the output tokens. Properties reasoning_tokens The number of reasoning tokens. x_details An array of billing details for the request. This provides a more granular breakdown of multimodal tokens than the top-level Properties input_tokens The number of tokens in the input. Additional Notes output_tokens The number of tokens in the model's output. total_tokens The total number of tokens consumed is the sum of x_billing_type The value is fixed to image_tokens The number of tokens for image input. This field is returned when the input includes an image and is equivalent to input_tokens_details A breakdown of input tokens. Fields depend on the model and input modalities. For audio input, Properties text_tokens The number of tokens for text input. image_tokens The number of tokens for image input. audio_tokens The number of audio input tokens at output_tokens_details A granular breakdown of output tokens. This field has an additional Properties reasoning_tokens The number of tokens for the reasoning process. text_tokens The number of tokens for text output. This field is returned for multimodal inputs. plugins Statistics for built-in tool calls. This field is returned when a built-in tool such as Properties web_search Statistics for web search calls. Properties count The number of times web search was called in this response. input_tokens_details Cache details for input tokens. This field is returned when session cache is enabled. It may return an empty object if the input includes an image but results in a cache miss. Properties cached_tokens The number of tokens that hit the cache. cache_creation_input_tokens The number of tokens used to create a new cache in this request. cache_creation Details about cache creation. Properties ephemeral_5m_input_tokens The number of tokens used to create a new 5-minute ephemeral cache. cache_type The cache type. The value is fixed to x_tools Statistics on tool usage. This contains the number of times each built-in tool is called. Example: Properties (Qwen4, Kimi-K3.1) input_tokens Total input tokens, including cache reads, cache writes, and uncached input. input_tokens_details Input token details. Properties cache_write_tokens Tokens written to the cache. cache_write_tokens_details Cache write details grouped by TTL. Properties ttl_1h_tokens Tokens written to a 1-hour cache. ttl_5m_tokens Tokens written to a 5-minute cache. cached_tokens Tokens read from the cache. output_tokens Total output tokens. output_tokens_details Output token details. Properties reasoning_tokens Reasoning tokens. total_tokens The sum of input and output tokens. The new response structure does not return error An error object is returned when the model fails to generate a response. Otherwise, the value is tools Echos the full content of the tool_choice Echoes the value of the | The following response example uses |
Response chunk object (streaming output)Streaming output returns a series of JSON objects. Each object includes a type The event type identifier. Possible values include:
sequence_number The event sequence number, starting at 0 and incrementing with each event. Use this number to process events in the correct order. response The response object. Appears in the item An output item object. It appears in the Properties id A unique identifier for the output item (e.g., type The type of the output item. Possible values: role The message role, which is always status Generation status. In an content An array of message content. In the part The content part object. Appears in the Properties type The type of the content part, which is always text Text content. This is an empty string in the annotations An array of text annotations. Usually an empty array. logprobs Token log probabilities. This field currently always returns delta The incremental text segment. This field appears in the text The complete text content. This field appears in the item_id The unique identifier for the output item. Use this ID to correlate events that belong to the same item. output_index The index of the output item in the content_index The index of the content part in the | Streaming examples for the original response structure. |
FAQ
Q: How do I pass context for a multi-turn conversation?A: When making a new conversation request, pass the id from the model's previous successful response as the previous_response_id parameter.
A: The official OpenAI SDK may output extra fields defined by the OpenAI protocol. Our service does not support these fields, so they are typically null. Focus only on the fields described in this topic.