Skip to main content
OpenAI-compatible Responses

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_id from 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.effort parameter 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
Replace {WorkspaceId} with your actual workspace ID.
Alibaba 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.com to https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: from https://dashscope-intl.aliyuncs.com to https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
  • China (Hong Kong): from https://cn-hongkong.dashscope.aliyuncs.com to https://{WorkspaceId}.cn-hongkong.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.
The legacy URL path /api/v2/apps/protocols/compatible-mode/v1/responses for the OpenAI-compatible Responses API will be deprecated soon. Please migrate to the new path /compatible-mode/v1/responses as soon as possible.

Request body

model string (required)The ID of the model to use.
  • Singapore
  • US (Virginia)
  • Germany (Frankfurt)
  • China (Beijing)
  • Hong Kong (China)
  • Japan (Tokyo)
International deployment scopeqwen3.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-0731glm-5.2
input string or array (required)The input for the model. The following formats are supported:
  • string: Plain text, such as "Hello".
  • array: An array of messages, ordered by conversation turn.
EasyInputMessage objectAn object with a role for the message author and content for the message payload.
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.
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.
type string (optional)Fixed as message.
ResponseOutputMessage 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.
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.
type string (required)Fixed as output_text.text string (required)The response text.annotations array (optional)Annotation information.
Function call object (optional)A structured instruction generated when the model decides to call an external tool.
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.
Function call output 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.
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.
Reasoning 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.
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.
type string (required)Fixed as summary_text.text string (required)The summary text.
status string (optional)The status. Valid values: in_progress, completed, incomplete.
Web Search Call 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.
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.
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.
type string (required)The source type. Always url.url string (required)The source URL.
instructionsstring (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.
  • false: The response is not stored and cannot be referenced in subsequent calls via previous_response_id.
  • true: The response is stored. The current model response can be referenced by previous_response_id and subsequent API calls.
tools 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 code_interpreter, web_search, and web_extractor tools.
Web searchSearches the internet for up-to-date information. Related documentation: Web Search
type string (required)Fixed as web_search.Example: [{"type": "web_search"}]
Web extractorAccesses and extracts content from web pages. It must be used with the web_search tool. For qwen3-max and qwen3-max-2026-01-23 models, reasoning mode must also be enabled. Related documentation: Web Extraction
type string (required)Fixed as web_extractor.Example: [{"type": "web_search"}, {"type": "web_extractor"}]
Code interpreterExecutes code in a sandboxed environment to perform tasks like data analysis. For qwen3-max and qwen3-max-2026-01-23 models, reasoning mode must also be enabled. Related documentation: Code Interpreter
type string (required)Fixed as code_interpreter.Example: [{"type": "code_interpreter"}]
Web search imageSearches for images based on a text description. Related documentation: Text-to-Image Search
type string (required)Fixed as web_search_image.Example: [{"type": "web_search_image"}]
Image searchSearches for similar or related images based on an input image. The input must include the image's URL. Related documentation: Image-to-Image Search
type string (required)Fixed as image_search.Example: [{"type": "image_search"}]
File searchPerforms knowledge retrieval by searching a specified knowledge base. Related documentation: Knowledge Retrieval
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"]}]
MCP invocationCalls an external service through the Model Context Protocol (MCP). Related documentation: MCP
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:
mcp_tool = {
    "type": "mcp",
    "server_protocol": "sse",
    "server_label": "amap-maps",
    "server_description": "The AMap MCP Server provides a full suite of geographic information services, covering 15 core APIs. These include custom map generation, navigation, ride-hailing, geocoding, reverse geocoding, IP-based location, weather queries, and planning for cycling, walking, driving, and public transit routes, along with distance measurement and various search functions.",
    "server_url": "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/mcps/amap-maps/sse",
    "headers": {
        "Authorization": "Bearer <your-mcp-server-token>"
    }
}
Custom toolfunctionAllows 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 function_call. Related documentation: Function calling
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 parameters.
Example:
[{
  "type": "function",
  "name": "get_weather",
  "description": "Get weather information for a specified city",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "The name of the city"
      }
    },
    "required": ["city"]
  }
}]
tool_choice 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
  • auto: The model decides whether to call a tool.
  • none: Prevents the model from calling any tool.
  • required: Forces the model to call a tool. This is only available when the tools list contains exactly one tool.
Object modeRestricts the model to a specific set of tools for selection and calling.
mode string (required)
  • auto: The model automatically decides whether to call a tool from the provided list.
  • required: Forces the model to call a tool from the provided list. This is only available when the tools list contains exactly one tool.
tools array(required)A list of tool definitions that the model is allowed to call.
[
  { "type": "function", "name": "get_weather" }
]
typestring (required)The type of tool configuration. Fixed as allowed_tools.
temperaturefloat(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:
  • true: Enables reasoning mode.
  • false: Disables reasoning mode.
For default values for different models, see Supported models.
This parameter is not a standard OpenAI parameter. In the Python SDK, pass it using extra_body={"enable_thinking": True}. In the Node.js SDK and curl, use enable_thinking: true as a top-level parameter. We recommend using reasoning.effort instead, as enable_thinking will be deprecated.
reasoning 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.
effort string (optional): The level of reasoning effort. Defaults to xhigh.Supports 7 incremental levels: noneminimallowmediumhighxhigh, and max. Lowering this value will accelerate the response speed and reduce inference Token consumption.
xhigh and max levels are only supported in the China (Beijing)and Singapore.
reasoning.effort takes precedence over enable_thinking. We recommend using reasoning.effort, as enable_thinking will be deprecated.
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 using extra_body={"ocr_options": {...}}. In the Node.js SDK and curl, use ocr_options as a top-level parameter.
max_output_tokens integer (optional)
  • Qwen3.8 series: the maximum total number of tokens in both the model’s response content and chain-of-thought content combined.
  • Other models: the maximum number of tokens in the model’s response content.
The minimum value is 16. If the model output exceeds this value, generation stops early and the status is incomplete.
  • Basic call
  • Stream output
  • Multi-turn conversation
  • Built-in tools
  • Function calling
  • Document understanding
  • Session cache
Python
import os
from openai import OpenAI

client = OpenAI(
    # If the environment variable is not set, replace with: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

response = client.responses.create(
    model="qwen3.8-max",
    input="What can you do?"
)

# Get the model's response
print(response.output_text)

Response object (non-streaming output)

id stringA 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:
  • completed: Generation completed.
  • failed: Generation failed.
  • in_progress: Generation in progress.
  • cancelled: Generation cancelled.
  • queued: Request queued.
  • incomplete: Generation incomplete.
model 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.
type stringThe output item type. Valid values:
  • message: A message item that contains the model's final response content.
  • reasoning: The reasoning type. This parameter is returned when reasoning.effort is set to a value other than none or when reasoning mode is enabled. The reasoning tokens are counted in output_tokens_details.reasoning_tokens and billed as reasoning tokens.
  • function_call: The function call type. This is returned when a custom function tool is used. Handle the function call and return the result.
  • web_search_call: The search call type. This is returned when the web_search tool is used.
  • code_interpreter_call: A code execution type that is returned when the code_interpreter tool is used.
  • web_extractor_call: The web extraction type. This is returned when the web_extractor tool is used. It must be used with the web_search tool.
  • web_search_image_call: The call type for a text-to-image search. This is returned when you use the web_search_image tool. It contains a list of the found images.
  • image_search_call: The call type for an image-to-image search. This is returned when the image_search tool is used. It contains a list of similar images.
  • mcp_call: The MCP call type. This is returned when you use the mcp tool. It contains the result of the MCP service call.
  • file_search_call: The call type for a knowledge base search, which is returned when you use the file_search tool. It contains the retrieval query and results for the knowledge base.
id 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:
  • web_search_image_call: {"queries": ["Search Keyword 1", "Search Keyword 2"]}, where queries is a list of search keywords automatically generated by the model based on user input.
  • image_search_call: {"img_idx": 0, "bbox": [0, 0, 1000, 1000]}, where img_idx is the index of the input image (starting from 0), and bbox is the bounding box coordinates [x1, y1, x2, y2] for the search area. The coordinate values range from 0 to 1000.
  • function_call: A parameter object generated from the user-defined function parameter schema.
  • mcp_call: The parameter object for the called function in the MCP service.
call_id 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.
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.
summary 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.
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.
code 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.
  • If type is web_extractor_call, this is a summary of the content extracted from the web page.
  • If type is web_search_image_call or image_search_call, this is a JSON string that contains an array of image search results. Each element includes the title, url, and index fields.
  • If type is mcp_call, this is the JSON string result returned by the MCP service.
urls 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.
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.
usage objectInformation about the token consumption for this request.
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.
cached_tokens integerThe number of tokens that hit the cache. For more information, see context caching.
output_tokens_details objectA detailed breakdown of the output tokens.
reasoning_tokens integerThe number of reasoning tokens.
x_details arrayAn array of billing details for the request. This provides a more granular breakdown of multimodal tokens than the top-level usage field.
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.
text_tokens integerThe number of tokens for text input.image_tokens integerThe number of tokens for image input.
output_tokens_details 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.
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.
plugins 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.
web_search objectStatistics for web search calls.
count integerThe number of times web search was called in this response.
prompt_tokens_details 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.
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.
ephemeral_5m_input_tokens integerThe number of tokens used to create a new 5-minute ephemeral cache.
cache_type stringThe cache type. The value is fixed to ephemeral.
x_tools objectStatistics on tool usage. This contains the number of times each built-in tool is called.Example: {"web_search": {"count": 1}}
error 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.
{
    "created_at": 1771165900.0,
    "id": "f75c28fb-4064-48ed-90da-4d2cc4362xxx",
    "model": "qwen3.8-max",
    "object": "response",
    "output": [
        {
            "content": [
                {
                    "annotations": [],
                    "text": "Hello! I am Qwen3.5, a large language model developed by Alibaba Cloud with knowledge up to 2026, designed to assist you with complex reasoning, creative tasks, and multilingual conversations.",
                    "type": "output_text"
                }
            ],
            "id": "msg_89ad23e6-f128-4d4c-b7a1-a786e7880xxx",
            "role": "assistant",
            "status": "completed",
            "type": "message"
        }
    ],
    "parallel_tool_calls": false,
    "status": "completed",
    "tool_choice": "auto",
    "tools": [],
    "usage": {
        "input_tokens": 57,
        "input_tokens_details": {
            "cached_tokens": 0
        },
        "output_tokens": 44,
        "output_tokens_details": {
            "reasoning_tokens": 0
        },
        "total_tokens": 101,
        "x_details": [
            {
                "input_tokens": 57,
                "output_tokens": 44,
                "total_tokens": 101,
                "x_billing_type": "response_api"
            }
        ]
    }
}

Response chunk object (streaming output)

Streaming output returns a series of JSON objects. Each object includes a type 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:
  • response.created: The response is created, with a status of queued.
  • response.in_progress: The response starts processing, and the status changes to in_progress.
  • response.output_item.added: A new output item (e.g., a message or a web_extractor_call) is added to the output array. When item.type is web_extractor_call, this indicates the start of a web extraction tool call.
  • response.content_part.added: A new content part is added to the content array of an output item.
  • response.output_text.delta: An incremental text segment is generated. This event is triggered multiple times, and the delta field contains the new text segment.
  • response.output_text.done: Text generation for a content part is complete. The text field contains the full text.
  • response.content_part.done: A content part is complete. The part object contains the complete content part.
  • response.output_item.done: An output item is complete. The item object contains the complete output item. When item.type is web_extractor_call, this indicates the completion of a web extraction tool call.
  • response.reasoning_text.delta: (In reasoning mode) Provides an incremental update to the reasoning summary. The delta field contains the new segment.
  • response.reasoning_text.done: (In reasoning mode) The reasoning summary is complete. The text field contains the full summary.
  • response.custom_tool_call_input.delta: Provides an incremental update to the custom tool call input. The delta field contains the newly generated segment.
  • response.custom_tool_call_input.done: The custom tool call input is complete. The input field contains the full input.
  • response.web_search_call.in_progress / searching / completed: An event that indicates a change in the search status when the web_search tool is used.
  • response.code_interpreter_call.in_progress / interpreting / completed: An event for a change in the code execution status (when using the code_interpreter tool).
  • Note: The web_extractor tool does not have a dedicated event type identifier. Its tool calls are passed through the general response.output_item.added and response.output_item.done events and are identified by the item.type field with a value of web_extractor_call.
  • response.mcp_call_arguments.delta / response.mcp_call_arguments.done: These events provide the delta and completion status for MCP call arguments.
  • response.mcp_call.in_progress: The MCP service call is in progress.
  • response.mcp_call.completed: The MCP service call is complete.
  • response.file_search_call.in_progress / searching / completed: Status change events for a knowledge base search (when you use the file_search tool).
  • Note: When using the web_search_image and image_search tools, there are no dedicated intermediate state events. Tool calls are communicated through the response.output_item.added (call start) and response.output_item.done (call complete) events.
  • response.completed: The response generation is complete. The response object contains the full response, including usage. This event marks the end of the stream.
  • response.incomplete: The response ended early due to limits such as max_output_tokens.
sequence_number 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.
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.
part objectThe content part object. Appears in the response.content_part.added and response.content_part.done events.
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.
delta 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.
// response.created: The response is created and queued.
{"response":{"id":"428c90e9-9cd6-90a6-9726-c02b08ebexxx","created_at":1769082930,"object":"response","status":"queued",...},"sequence_number":0,"type":"response.created"}

// response.in_progress: Processing begins.
{"response":{"id":"428c90e9-9cd6-90a6-9726-c02b08ebexxx","status":"in_progress",...},"sequence_number":1,"type":"response.in_progress"}

// response.output_item.added: A new output item is added.
{"item":{"id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","content":[],"role":"assistant","status":"in_progress","type":"message"},"output_index":0,"sequence_number":2,"type":"response.output_item.added"}

// response.content_part.added: A new content part is added.
{"content_index":0,"item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","output_index":0,"part":{"annotations":[],"text":"","type":"output_text","logprobs":null},"sequence_number":3,"type":"response.content_part.added"}

// response.output_text.delta: Incremental text (can be triggered multiple times).
{"content_index":0,"delta":"Artificial Intelligence","item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","logprobs":[],"output_index":0,"sequence_number":4,"type":"response.output_text.delta"}
{"content_index":0,"delta":" (AI) refers to the technology","item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","logprobs":[],"output_index":0,"sequence_number":6,"type":"response.output_text.delta"}

// response.output_text.done: Text generation for a content part is complete.
{"content_index":0,"item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","logprobs":[],"output_index":0,"sequence_number":53,"text":"Artificial Intelligence (AI) refers to the technology and science that enables computer systems to simulate human intelligent behaviors...","type":"response.output_text.done"}

// response.content_part.done: The content part is complete.
{"content_index":0,"item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","output_index":0,"part":{"annotations":[],"text":"...full text...","type":"output_text","logprobs":null},"sequence_number":54,"type":"response.content_part.done"}

// response.output_item.done: The output item is complete.
{"item":{"id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","content":[{"annotations":[],"text":"...full text...","type":"output_text","logprobs":null}],"role":"assistant","status":"completed","type":"message"},"output_index":0,"sequence_number":55,"type":"response.output_item.done"}

// response.completed: The response is complete (includes full response and usage).
{"response":{"id":"428c90e9-9cd6-90a6-9726-c02b08ebexxx","created_at":1769082930,"model":"qwen3.7-max","object":"response","output":[...],"status":"completed","usage":{"input_tokens":37,"output_tokens":243,"total_tokens":280,...}},"sequence_number":56,"type":"response.completed"}

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.