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:
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:
Replace
Q: How do I pass context for a multi-turn conversation?
A: When making a new conversation request, pass the
- 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.
- Singapore
- China (Beijing)
- US (Virginia)
- Germany (Frankfurt)
- China (Hong Kong)
- Japan (Tokyo)
The
base_url for the SDK call configuration is 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{WorkspaceId} with your actual workspace ID.
Request bodymodelstring (required)The ID of the model to use.
Supported models
International deployment scope qwen3.8-max, qwen3.8-flash, qwen3.7-max, qwen3.7-max-2026-05-20, qwen3.7-max-2026-06-08, qwen3-max, qwen3-max-2026-01-23, qwen3.7-plus, qwen3.7-plus-2026-05-26, qwen3.6-plus, qwen3.6-plus-2026-04-02, qwen3.5-plus, qwen3.5-plus-2026-04-20, qwen3.5-plus-2026-02-15, qwen3.7-flash, qwen3.7-flash-2026-07-15, qwen3.6-flash, qwen3.6-flash-2026-04-16, qwen3.5-flash, qwen3.5-flash-2026-02-23, qwen3.8-2.4t-a95b, qwen3.8-27b, qwen3.6-35b-a3b, qwen3.5-397b-a17b, qwen3.5-122b-a10b, qwen3.5-27b, qwen3.5-35b-a3b, qwen-plus, qwen-flash, qwen3-coder-plus, qwen3-coder-flash, qwen-plus-character, qwen-flash-character, deepseek-v4-pro, deepseek-v4-flash, deepseek-v4-flash-0731、glm-5.2string or array (required)The input for the model. The following formats are supported:
Array item types EasyInputMessage objectAn object with a role for the message author and content for the message payload.
Properties role string (required)The role of the message's author. Valid values: user, assistant, system, developer.content string or array (required)The message content. The content is a string if the input is plain text, or an array if the input is a structured content array. When the role is system or developer, the array element type is input_text. When the role is user, the array element type is input_text, input_image, or input_file. When the role is assistant, the array element type is output_text.The Responses API does not currently support video or audio input. To pass these data types, use the Chat Completions API or DashScope API.
Content array items type string (required)Specifies the content type. Valid values are input_text, input_image (user role only), input_file (user role only, supports PDF and images), and output_text (assistant role only).text stringThe text content. Required when type is input_text or output_text.image_url stringSupports a URL or Base64-encoded data. Required when type is input_image. For Base64, provide a complete Data URI, for example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUg....file_url stringThe public URL of the file. Required when type is input_file. Supports PDF files (up to 10 pages, 100 MB) and image files (up to 20 MB). Currently only supported by qwen3.5-ocr.string (optional)Fixed as message.object (optional)The model's output message. To continue a conversation, you can pass the message object from a previous response's output array back into the input. Unlike EasyInputMessage, this object includes the full output structure, with id, status, and structured content.
Properties type string (required)Fixed as message.id string (required)The unique identifier of the output message, from the previous response.role string (required)Fixed as assistant.status string (required)The message status. Valid values: in_progress, completed, incomplete.content array (required)An array of content, where elements are output_text objects.
Properties type string (required)Fixed as output_text.text string (required)The response text.annotations array (optional)Annotation information.object (optional)A structured instruction generated when the model decides to call an external tool.
Properties type string (required)Fixed as function_call.id string (optional)The unique identifier for the function call, from the previous response.name string (required)The name of the tool function.arguments string (required)The tool call arguments, in JSON string format.call_id string (required)The identifier for the tool call. This must match the call_id that is returned by the model.status string (optional)The status. Valid values: in_progress, completed, incomplete.object (optional)The output of a tool call. In the message list, this object must immediately follow its corresponding function_call message to prevent a request failure.
Properties type string (required)Fixed as function_call_output.id string (optional)The unique identifier for the function call output.call_id string (required)The tool call identifier must match the call_id returned by the model.output string (required)The execution result of the tool function.status string (optional)The status. Valid values: in_progress, completed, incomplete.object (optional)The model's reasoning process. You can pass the reasoning item from a previous response's output back into the input to continue this process in a subsequent turn.
Properties type string (required)Fixed as reasoning.id string (required)The unique identifier for the reasoning content, from the previous response.summary array (required)The reasoning summary content.
Properties type string (required)Fixed as summary_text.text string (required)The summary text.string (optional)The status. Valid values: in_progress, completed, incomplete.object (optional)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 string (required)Always web_search_call.id string (required)The unique identifier of the search call, from the previous response.status string (required)The search status. Valid values: in_progress, searching, completed, failed.action object (required)The search action details. Only the search type is supported.
Properties type string (required)The search type. Always search.queries array (optional)A list of search queries. Each element is a string.sources array (optional)A list of search result sources.
Properties type string (required)The source type. Always url.url string (required)The source URL.string (optional)It is inserted at the beginning of the context as a system instruction. When previous_response_id is used, the instructions specified in the previous turn are not passed to the current turn's context.previous_response_id string (optional)The unique ID of the previous response. A response's id is valid for 7 days. You can use this parameter to create multi-turn conversations. The server-side automatically retrieves and combines the input and output of that turn as the context. If you provide both the input message array and previous_response_id, the new messages in input are appended to the historical context. This parameter cannot be used with conversation.conversation string (optional)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 previous_response_id.stream boolean (optional) Defaults to falseEnables stream output. If set to true, the model streams the response in real time.store boolean (optional) Defaults to trueSpecifies whether to store the model response generated for this session.
array (optional)An array of tools the model can call when generating a response. Supports both built-in tools and custom function tools, which can be used together.For best results, enable the
Properties Web searchSearches the internet for up-to-date information. Related documentation: Web Search
Properties type string (required)Fixed as web_search.Example: [{"type": "web_search"}]web_search tool. For qwen3-max and qwen3-max-2026-01-23 models, reasoning mode must also be enabled. Related documentation: Web Extraction
Properties type string (required)Fixed as web_extractor.Example: [{"type": "web_search"}, {"type": "web_extractor"}]qwen3-max and qwen3-max-2026-01-23 models, reasoning mode must also be enabled. Related documentation: Code Interpreter
Properties type string (required)Fixed as code_interpreter.Example: [{"type": "code_interpreter"}]
Properties type string (required)Fixed as web_search_image.Example: [{"type": "web_search_image"}]
Properties type string (required)Fixed as image_search.Example: [{"type": "image_search"}]
Properties type string (required)Fixed as file_search.vector_store_ids array(required)The ID of the knowledge base to search. Currently, only one knowledge base ID can be provided.Example: [{"type": "file_search", "vector_store_ids": ["your_knowledge_base_id"]}]
Properties type string (required)Fixed as mcp.server_protocol string (required)The communication protocol with the MCP service, such as "sse".server_label string (required)A label used to identify the MCP service.server_description string (optional)A description of the service. It helps the model understand its function and when to use it.server_url string (required)The URL of the MCP service endpoint.headers object (optional)Request headers, used to carry information such as authentication (e.g., Authorization).Example:function_call. Related documentation: Function calling
Properties type string (required)Must be set to function.namestring(required)The name of the tool. Can only contain letters, digits, underscores (_), and hyphens (-), with a maximum length of 64 tokens.descriptionstring(required)A description of the tool, which helps the model decide when and how to call it.parameters object (optional)The parameter definition for the tool, which must be a valid JSON Schema object. If parameters is empty, the tool takes no arguments (e.g., a time query tool).
To improve tool-calling accuracy, we recommend defining Example:string or object (optional) Defaults to autoControls how the model selects and calls tools. This parameter supports two formats: string mode and object mode.String mode
Properties mode string (required)
array(required)A list of tool definitions that the model is allowed to call.string (required)The type of tool configuration. Fixed as allowed_tools.float(optional)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 temperature and top_p control the diversity of the generated text. We recommend using only one of these parameters at a time. For more information, see Overview.top_pfloat(optional)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 temperature and top_p control the diversity of the generated text. We recommend using only one of these parameters at a time. For more information, see Overview.enable_thinking boolean (optional)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 reasoning. When enabling reasoning mode, we recommend also enabling built-in tools to achieve the best results on complex tasks.Valid values:
This parameter is not a standard OpenAI parameter. In the Python SDK, pass it usingreasoning object (optional)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 reasoning.
Properties effort string (optional): The level of reasoning effort. Defaults to xhigh.Supports 7 incremental levels: none, minimal, low, medium, high, xhigh, and max. Lowering this value will accelerate the response speed and reduce inference Token consumption.
ocr_options object (optional)OCR built-in task parameters. Only applicable to the qwen3.5-ocr model. Use this parameter to call built-in OCR tasks (such as information extraction and text localization). Built-in task results are returned in the ocr_result field of the response.This parameter is not a standard OpenAI parameter. In the Python SDK, pass it usingmax_output_tokens integer (optional)
incomplete. |
Python |
Response object (non-streaming output)idstringA unique identifier for this response, a UUID. This ID is valid for 7 days and can be used in the previous_response_id parameter to create a multi-turn conversation.created_at integerThe Unix timestamp (in seconds) for this request.object stringThe object type, which is always response.status stringThe status of the response generation. Valid values:
stringThe ID of the model used to generate the response.output arrayAn 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 stringThe output item type. Valid values:
stringThe unique identifier of the output item. All types of output items contain this field.role stringThe role of the message is always assistant. This parameter is present only when type is message.status stringThe status of the output item. Valid values: completed and in_progress. This parameter is present when the type parameter is not set to reasoning.name stringThe name of the tool or function. This parameter is present when type is function_call, web_search_image_call, image_search_call, or mcp_call.For web_search_image_call and image_search_call, the values are fixed to "web_search_image" and "image_search", respectively.For mcp_call, the value is the name of the specific function called in the MCP service, such as amap-maps-maps_geo.arguments stringThe parameters for the tool call, in a JSON string format. This parameter is present when type is function_call, web_search_image_call, image_search_call, or mcp_call. Parse the string by using JSON.parse() before use. The content of arguments for different tool types is as follows:
stringThe unique ID for the function call. This parameter is included only when type is function_call. This ID must be included in the function call result to link the request to the response.content arrayThe array of message content. This parameter is present only if type is set to message.
Array element properties type stringThe content type. The value is fixed to output_text.text stringThe text content generated by the model.annotations arrayThe array of text annotations. This is usually an empty array.arrayAn array of reasoning summaries. This field is present only when type is reasoning. Each element contains the type field (value: summary_text) and the text field (the summary text).action objectThe information about the search action. This parameter is present only when type is web_search_call.
Properties query stringThe search query keywords.type stringThe search type. The value is always search.sources arrayA list of search sources. Each element contains the type and url fields.stringThe code generated and executed by the model. This exists only when type is code_interpreter_call.outputs arrayThe code execution output array. This is present only when type is code_interpreter_call. Each element has a type field (the value is logs) and a logs field (the code execution logs).container_id stringThe container identifier for the code interpreter. This parameter is present only when type is code_interpreter_call. This identifier associates multiple code executions within the same session.goal stringA description of the information to extract from the webpage. This parameter is available only when type is web_extractor_call.output stringThe output of the tool call. The output is a string.
arrayThe list of URLs for the extracted web pages. This parameter is available only when type is web_extractor_call.server_label stringThe label for the MCP service. This appears only when type is mcp_call. It shows which MCP service the call used.queries arrayA list of queries for knowledge base retrieval. This parameter exists only when type is file_search_call. The array contains strings. Each string is a search query generated by the model.results arrayAn array of search results from the knowledge base. This parameter is present only when type is file_search_call.
Array element properties file_id stringThe file ID of the matched document.filename stringThe file name of the matched document.score floatThe relevance score of the match. The value ranges from 0 to 1. A larger value indicates higher relevance.text stringThe content snippet from the matched document.objectInformation about the token consumption for this request.
Properties input_tokens integerThe number of tokens in the input. Additional Notesoutput_tokens integerThe number of tokens in the model's output.total_tokens integerThe total number of tokens consumed is the sum of input_tokens and output_tokens.input_tokens_details objectA fine-grained classification of input tokens.
Properties cached_tokens integerThe number of tokens that hit the cache. For more information, see context caching.objectA detailed breakdown of the output tokens.
Properties reasoning_tokens integerThe number of reasoning tokens.arrayAn array of billing details for the request. This provides a more granular breakdown of multimodal tokens than the top-level usage field.
Properties input_tokens integerThe number of tokens in the input. Additional Notesoutput_tokens integerThe number of tokens in the model's output.total_tokens integerThe total number of tokens consumed is the sum of input_tokens and output_tokens.x_billing_type stringThe value is fixed to response_api.image_tokens integerThe number of tokens for image input. This field is returned when the input includes an image and is equivalent to input_tokens_details.image_tokens.input_tokens_details objectA granular breakdown of input tokens. This field is returned for multimodal inputs. It currently distinguishes only between text_tokens and image_tokens. It does not provide a breakdown for video or audio tokens.
Properties text_tokens integerThe number of tokens for text input.image_tokens integerThe number of tokens for image input.objectA granular breakdown of output tokens. This field has an additional text_tokens field compared to the top-level output_tokens_details. The text_tokens field is returned for multimodal inputs.
Properties reasoning_tokens integerThe number of tokens for the reasoning process.text_tokens integerThe number of tokens for text output. This field is returned for multimodal inputs.objectStatistics for built-in tool calls. This field is returned when a built-in tool such as web_search is used. Its content is the same as the top-level x_tools field.
Properties web_search objectStatistics for web search calls.
Properties count integerThe number of times web search was called in this response.objectCache 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 integerThe number of tokens that hit the cache.cache_creation_input_tokens integerThe number of tokens used to create a new cache in this request.cache_creation objectDetails about cache creation.
Properties ephemeral_5m_input_tokens integerThe number of tokens used to create a new 5-minute ephemeral cache.stringThe cache type. The value is fixed to ephemeral.objectStatistics on tool usage. This contains the number of times each built-in tool is called.Example: {"web_search": {"count": 1}}objectAn error object is returned when the model fails to generate a response. Otherwise, the value is null.tools arrayEchos the full content of the tools parameter from the request, with the same structure as the tools parameter in the request body.tool_choice stringEchoes the value of the tool_choice parameter in the request. The valid values are auto, none, and required. |
Response chunk object (streaming output)Streaming output returns a series of JSON objects. Each object includes atype field to specify the event type and a sequence_number field to indicate the event order. The response.completed event marks the end of the stream.type stringThe event type identifier. Possible values include:
integerThe event sequence number, starting at 0 and incrementing with each event. Use this number to process events in the correct order.response objectThe response object. Appears in the response.created, response.in_progress, and response.completed events. In the response.completed event, it contains the complete response data (including output and usage), and its structure is identical to the non-streaming Response object.item objectAn output item object. It appears in the response.output_item.added and response.output_item.done events. In the added event, it is an initial skeleton where the content is an empty array. In the done event, it is a complete object.
Properties id stringA unique identifier for the output item (e.g., msg_xxx).type stringThe type of the output item. Possible values: message, reasoning, web_search_call, web_search_image_call (text-to-image search), image_search_call (image-to-image search), mcp_call (MCP call), file_search_call (knowledge base search).role stringThe message role, which is always assistant. Present only when type is message.status stringGeneration status. In an added event, the status is in_progress, and in a done event, it is completed.content arrayAn array of message content. In the added event, the array is empty []. In the done event, it contains complete content part objects whose structure is the same as that of the part object.objectThe content part object. Appears in the response.content_part.added and response.content_part.done events.
Properties type stringThe type of the content part, which is always output_text.text stringText content. This is an empty string in the added event and the complete text in the done event.annotations arrayAn array of text annotations. Usually an empty array.logprobs object | nullToken log probabilities. This field currently always returns null.stringThe incremental text segment. This field appears in the response.output_text.delta event and contains the newly added text segment. Concatenate all delta values to reconstruct the full text.text stringThe complete text content. This field appears in the response.output_text.done event. You can use it to validate the text reconstructed from the delta fragments.item_id stringThe unique identifier for the output item. Use this ID to correlate events that belong to the same item.output_index integerThe index of the output item in the output array.content_index integerThe index of the content part in the content array. |
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.
Q: Why are some fields in the response example not described in this topic?
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.