compatible Responses-Create a response

Call Qwen models using the OpenAI-compatible Responses API. This topic covers the input and output parameters, with API call examples. Advantages over the OpenAI Chat Completions API:

• Built-in tools : Includes web search, web scraping, a code interpreter, text-to-image search, image-to-image search, and knowledge base search, delivering superior results on complex tasks. For details, see tool calling.

• Flexible input: Pass a string directly or use chat-formatted message arrays.

• Simplified context management : Pass the previous_response_id from the last turn instead of manually constructing the entire message history array.

• Effortless context caching : Add a single request header to enable automatic server-side context caching for multi-turn conversations, reducing latency and cost with no code changes required. For details, see Session Cache.

Compatibility and limitations

This API is compatible with OpenAI to provide an easier migration path for developers, but it differs in its parameters, features, and behaviors.

Core principle: Only parameters explicitly listed in this document are processed. Any unlisted OpenAI parameters are ignored.

Key differences include:

• Unsupported parameters : Some OpenAI parameters are not supported, such as background (asynchronous execution). Only synchronous calls are supported.

• Reasoning effort control : Control the model's reasoning effort with the reasoning.effort parameter.

Singapore

SDK base_url: https://dashscope-intl.aliyuncs.com/compatible-mode/v1

HTTP endpoint: POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/responses

China (Beijing)

SDK base_url: https://dashscope.aliyuncs.com/compatible-mode/v1

HTTP endpoint: POST https://dashscope.aliyuncs.com/compatible-mode/v1/responses

US (Virginia)

SDK base_url: https://dashscope-us.aliyuncs.com/compatible-mode/v1

HTTP endpoint: POST https://dashscope-us.aliyuncs.com/compatible-mode/v1/responses

Germany (Frankfurt)

SDK base_url: https://{++WorkspaceId++}++.eu-central-1.maas.aliyuncs++.com/compatible-mode/v1

HTTP endpoint: POST https://++{WorkspaceId}.eu-central-1.maas.aliyuncs++.com/compatible-mode/v1/responses

Replace WorkspaceId with your Workspace ID. Important

The legacy URL path /api/v2/apps/protocols/compatible-mode/v1/responses is being deprecated. Migrate to the new path /compatible-mode/v1/responses as soon as possible.

## Request body

## Basic call

## Python

import os
from openai import OpenAI

client = OpenAI(
 # If the environment variable is not set, replace the line below with: api_key="sk-xxx"
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

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


print(response.output_text)

## Node.js

import OpenAI from "openai";

const openai = new OpenAI({
 // If the environment variable is not set, replace the line below with: apiKey: "sk-xxx"
 apiKey: process.env.DASHSCOPE_API_KEY,
 baseURL: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
});

async function main() {
 const response = await openai.responses.create({
 model: "qwen3.6-plus",
 input: "What can you do?"
 });

// Get model response
 console.log(response.output_text);
}

main();

## curl

curl -X POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/responses \\
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
 "model": "qwen3.6-plus",
 "input": "What can you do?"
}'

## Streaming output

## Python

import os
from openai import OpenAI

client = OpenAI(
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

stream = client.responses.create(
 model="qwen3.6-plus",
 input="Please briefly introduce artificial intelligence.",
 stream=True
)

print("Receiving streaming output:")
for event in stream:
 if event.type == 'response.output_text.delta':
 print(event.delta, end='', flush=True)
 elif event.type == 'response.completed':
 print("\\nStreaming completed")
 print(f"Total tokens: {event.response.usage.total_tokens}")

## Node.js

import OpenAI from "openai";

const openai = new OpenAI({
 apiKey: process.env.DASHSCOPE_API_KEY,
 baseURL: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
});

async function main() {
 const stream = await openai.responses.create({
 model: "qwen3.6-plus",
 input: "Please briefly introduce artificial intelligence.",
 stream: true
 });

console.log("Receiving streaming output:");
 for await (const event of stream) {
 if (event.type === 'response.output_text.delta') {
 process.stdout.write(event.delta);
 } else if (event.type === 'response.completed') {
 console.log("\\nStreaming completed");
 console.log(\`Total tokens: ${event.response.usage.total_tokens}\`);
 }
 }
}

main();

## curl

curl -X POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/responses \\
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \\
-H "Content-Type: application/json" \\
--no-buffer \\
-d '{
 "model": "qwen3.6-plus",
 "input": "Please briefly introduce artificial intelligence.",
 "stream": true
}'

## Multi-turn conversation

## Python

import os
from openai import OpenAI

client = OpenAI(
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

# First turn
response1 = client.responses.create(
 model="qwen3.6-plus",
 input="My name is John, please remember it."
)
print(f"First response: {response1.output_text}")

# Second turn - use previous_response_id to link context. The response ID is valid for 7 days.
response2 = client.responses.create(
 model="qwen3.6-plus",
 input="Do you remember my name?",
 previous_response_id=response1.id
)
print(f"Second response: {response2.output_text}")

## Node.js

import OpenAI from "openai";

const openai = new OpenAI({
 apiKey: process.env.DASHSCOPE_API_KEY,
 baseURL: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
});

async function main() {
 // First turn
 const response1 = await openai.responses.create({
 model: "qwen3.6-plus",
 input: "My name is John, please remember it."
 });
 console.log(\`First response: ${response1.output_text}\`);

// Second turn - use previous_response_id to link context. The response ID is valid for 7 days.
 const response2 = await openai.responses.create({
 model: "qwen3.6-plus",
 input: "Do you remember my name?",
 previous_response_id: response1.id
 });
 console.log(\`Second response: ${response2.output_text}\`);
}

main();

## Built-in tools

## Python

import os
from openai import OpenAI

client = OpenAI(
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

response = client.responses.create(
 model="qwen3.6-plus",
 input="Find the Alibaba Cloud website and extract key information",
 # For best results, enable the built-in tools
 tools=\[
 {"type": "web_search"},
 {"type": "code_interpreter"},
 {"type": "web_extractor"}
 \],
)

# Uncomment the line below to see the intermediate output
# print(response.output)
print(response.output_text)

## Node.js

import OpenAI from "openai";

const openai = new OpenAI({
 apiKey: process.env.DASHSCOPE_API_KEY,
 baseURL: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
});

async function main() {
 const response = await openai.responses.create({
 model: "qwen3.6-plus",
 input: "Find the Alibaba Cloud website and extract key information",
 tools: \[
 { type: "web_search" },
 { type: "code_interpreter" },
 { type: "web_extractor" }
 \]
 });

for (const item of response.output) {
 if (item.type === "reasoning") {
 console.log("Model is thinking...");
 } else if (item.type === "web_search_call") {
 console.log(\`Search query: ${item.action.query}\`);
 } else if (item.type === "web_extractor_call") {
 console.log("Extracting web content...");
 } else if (item.type === "message") {
 console.log(\`Response: ${item.content\[0\].text}\`);
 }
 }
}

main();

## curl

curl -X POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/responses \\
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
 "model": "qwen3.6-plus",
 "input": "Find the Alibaba Cloud website and extract key information",
 "tools": \[
 {
 "type": "web_search"
 },
 {
 "type": "code_interpreter"
 },
 {
 "type": "web_extractor"
 }
 \]
}'

## Custom function call

## Python

from openai import OpenAI
import json
import os
import random

# Initialize client
client = OpenAI(
 # If the environment variable is not set, replace the line below with: api_key="sk-xxx"
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
# Simulate user question
USER_QUESTION = "What's the weather like in Beijing?"
# Define tool list
tools = \[
 {
 "type": "function",
 "name": "get_current_weather",
 "description": "Useful for querying the weather of a specified city.",
 "parameters": {
 "type": "object",
 "properties": {
 "location": {
 "type": "string",
 "description": "City or district, e.g. Beijing, Hangzhou, etc.",
 }
 },
 "required": \["location"\],
 },
 }
\]

# Simulate weather query tool
def get_current_weather(arguments):
 weather_conditions = \["sunny", "cloudy", "rainy"\]
 random_weather = random.choice(weather_conditions)
 location = arguments\["location"\]
 return f"Today in {location} it is {random_weather}."

# Wrapper for model response
def get_response(input_data):
 response = client.responses.create(
 model="qwen3.6-plus",
 input=input_data,
 tools=tools,
 )
 return response

# Maintain conversation context
conversation = \[{"role": "user", "content": USER_QUESTION}\]

response = get_response(conversation)
function_calls = \[item for item in response.output if item.type == "function_call"\]
# If no tool calls are needed, output content directly
if not function_calls:
 print(f"Final response: {response.output_text}")
else:
 # Enter tool call loop
 while function_calls:
 for fc in function_calls:
 func_name = fc.name
 arguments = json.loads(fc.arguments)
 print(f"Calling tool \[{func_name}\], arguments: {arguments}")
 # Execute tool
 tool_result = get_current_weather(arguments)
 print(f"Tool returned: {tool_result}")
 # Append tool call and result as pairs to context
 conversation.append(
 {
 "type": "function_call",
 "name": fc.name,
 "arguments": fc.arguments,
 "call_id": fc.call_id,
 }
 )
 conversation.append(
 {
 "type": "function_call_output",
 "call_id": fc.call_id,
 "output": tool_result,
 }
 )
 # Call model again with full context
 response = get_response(conversation)
 function_calls = \[
 item for item in response.output if item.type == "function_call"
 \]
 print(f"Final response: {response.output_text}")

## Node.js

import OpenAI from "openai";

// Initialize client
const openai = new OpenAI({
 // If the environment variable is not set, replace the line below with: apiKey: "sk-xxx"
 apiKey: process.env.DASHSCOPE_API_KEY,
 baseURL:
 "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
});

// Define tool list
const tools = \[
 {
 type: "function",
 name: "get_current_weather",
 description: "Useful for querying the weather of a specified city.",
 parameters: {
 type: "object",
 properties: {
 location: {
 type: "string",
 description: "City or district, e.g. Beijing, Hangzhou, etc.",
 },
 },
 required: \["location"\],
 },
 },
\];

// Simulate weather query tool
const getCurrentWeather = (args) =\> {
 const weatherConditions = \["sunny", "cloudy", "rainy"\];
 const randomWeather =
 weatherConditions\[Math.floor(Math.random() * weatherConditions.length)\];
 const location = args.location;
 return \`Today in ${location} it is ${randomWeather}.\`;
};

// Wrapper for model response
const getResponse = async (inputData) =\> {
 const response = await openai.responses.create({
 model: "qwen3.6-plus",
 input: inputData,
 tools: tools,
 });
 return response;
};

const main = async () =\> {
 const userQuestion = "What's the weather like in Beijing?";

// Maintain conversation context
 const conversation = \[{ role: "user", content: userQuestion }\];

let response = await getResponse(conversation);
 let functionCalls = response.output.filter(
 (item) =\> item.type === "function_call"
 );
 // If no tool calls are needed, output content directly
 if (functionCalls.length === 0) {
 console.log(\`Final response: ${response.output_text}\`);
 } else {
 // Enter tool call loop
 while (functionCalls.length \> 0) {
 for (const fc of functionCalls) {
 const funcName = fc.name;
 const args = JSON.parse(fc.arguments);
 console.log(\`Calling tool \[${funcName}\], arguments:\`, args);
 // Execute tool
 const toolResult = getCurrentWeather(args);
 console.log(\`Tool returned: ${toolResult}\`);
 // Append tool call and result as pairs to context
 conversation.push({
 type: "function_call",
 name: fc.name,
 arguments: fc.arguments,
 call_id: fc.call_id,
 });
 conversation.push({
 type: "function_call_output",
 call_id: fc.call_id,
 output: toolResult,
 });
 }
 // Call model again with full context
 response = await getResponse(conversation);
 functionCalls = response.output.filter(
 (item) =\> item.type === "function_call"
 );
 }
 console.log(\`Final response: ${response.output_text}\`);
 }
};

// Start program
main().catch(console.error);

## Session Cache

## Python

import os
from openai import OpenAI

client = OpenAI(
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
 # Enable Session cache via default_headers
 default_headers={"x-dashscope-session-cache": "enable"}
)

# Build a long context exceeding 1024 tokens to trigger cache creation.
# (If under 1024 tokens, the cache will be created when the cumulative context across turns exceeds 1024 tokens.)
long_context = "Artificial intelligence is an important branch of computer science, dedicated to researching and developing theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. " * 50

# First turn
response1 = client.responses.create(
 model="qwen3.6-plus",
 input=long_context + "\\n\\nBased on the background above, briefly introduce the random forest algorithm in machine learning.",
)
print(f"First reply: {response1.output_text}")

# Second turn: link context via previous_response_id; the server handles caching automatically
response2 = client.responses.create(
 model="qwen3.6-plus",
 input="What are the main differences between it and GBDT?",
 previous_response_id=response1.id,
)
print(f"Second reply: {response2.output_text}")

# Inspect cache hit
usage = response2.usage
print(f"Input tokens: {usage.input_tokens}")
print(f"Cached tokens: {usage.input_tokens_details.cached_tokens}")

## Node.js

import OpenAI from "openai";

const openai = new OpenAI({
 apiKey: process.env.DASHSCOPE_API_KEY,
 baseURL: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
 // Enable Session cache via defaultHeaders
 defaultHeaders: {"x-dashscope-session-cache": "enable"}
});

// Build a long context exceeding 1024 tokens to trigger cache creation.
// (If under 1024 tokens, the cache will be created when the cumulative context across turns exceeds 1024 tokens.)
const longContext = "Artificial intelligence is an important branch of computer science, dedicated to researching and developing theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. ".repeat(50);

async function main() {
 // First turn
 const response1 = await openai.responses.create({
 model: "qwen3.6-plus",
 input: longContext + "\\n\\nBased on the background above, briefly introduce the random forest algorithm in machine learning, including basic principles and use cases."
 });
 console.log(\`First reply: ${response1.output_text}\`);

// Second turn: link context via previous_response_id; the server handles caching automatically
 const response2 = await openai.responses.create({
 model: "qwen3.6-plus",
 input: "What are the main differences between it and GBDT?",
 previous_response_id: response1.id
 });
 console.log(\`Second reply: ${response2.output_text}\`);

// Inspect cache hit
 console.log(\`Input tokens: ${response2.usage.input_tokens}\`);
 console.log(\`Cached tokens: ${response2.usage.input_tokens_details.cached_tokens}\`);
}

main();

## curl

# First turn
# The long text is repeated 50 times to ensure it exceeds 1024 tokens and triggers cache creation
curl -X POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/responses \\
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \\
-H "Content-Type: application/json" \\
-H "x-dashscope-session-cache: enable" \\
-d '{
 "model": "qwen3.6-plus",
 "input": "Artificial intelligence is an important..."
}'

# Second turn - use the id from the first turn as previous_response_id
curl -X POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/responses \\
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \\
-H "Content-Type: application/json" \\
-H "x-dashscope-session-cache: enable" \\
-d '{
 "model": "qwen3.6-plus",
 "input": "What are the main differences between it and GBDT?",
 "previous_response_id": "id returned from the first turn"
}'

model *string* (Required) The model to use for the request. Supported models

## International

qwen3-max, qwen3-max-2026-01-23, 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.6-flash, qwen3.6-flash-2026-04-16, qwen3.5-flash, qwen3.5-flash-2026-02-23, 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, and qwen3-coder-flash.

## Global

US (Virginia): 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.6-flash, qwen3.6-flash-2026-04-16, qwen3.5-flash, qwen3.5-flash-2026-02-23, qwen3.6-35b-a3b, qwen3.5-122b-a10b, qwen3.5-27b, and qwen3.5-35b-a3b.

• Germany (Frankfurt): qwen3.5-397b-a17b, qwen3.5-122b-a10b, qwen3.5-35b-a3b, and qwen3.5-27b.

## Chinese mainland

qwen3-max, qwen3-max-2026-01-23, 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.6-flash, qwen3.6-flash-2026-04-16, qwen3.5-flash, qwen3.5-flash-2026-02-23, 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, and qwen3-coder-flash.

input *string or array* (Required) The model input, which supports the following formats:

• string: plain text, such as "hello".
• array: A message array, arranged in conversational order.

array item types

EasyInputMessage *object* A message with role and content properties. Properties

role *string* (Required) Valid values: user, assistant, system, or developer.

content *string or array* (Required) The message content. The value 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 or input_image. When the role is assistant, the array element type is output_text. ** To use video or audio input, which the Responses API does not support, use the Chat Completions API or DashScope API instead. <b>content array elements**

type *string* (Required) Optional values: input_text (text input), input_image (image input, user role only), output_text (assistant response, assistant role only).

text *string* Text content. Required when type is input_text or output_text.

image_url *string* The public URL of the image. This parameter is required when type is input_image.

type *string* (Optional) Set to message.

ResponseOutputMessage *object* (Optional) The model's output message object. You can pass the message item from the previous response's output back into input for multi-turn conversations. It differs from EasyInputMessage by carrying the complete output structure, including id, status, and structured content. Properties

type *string* (Required) Fixed to message.

id *string* (Required) The unique identifier of the output message, from the previous response.

role *string* (Required) Fixed to assistant.

status *string* (Required) The status of the message. Valid values are in_progress, completed, or incomplete.

content *array* (Required) A content array where elements are output_text objects. Properties

type *string* (Required) Fixed to 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. Properties

type *string* (Required) Set to 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 of the tool call, which must match the call_id returned by the model.

status *string* (Optional) The status. Valid values are in_progress, completed, or incomplete.

function_call_output *object* (Optional) The output of tool calling must immediately follow the corresponding function_call message in the message list, or an error is returned. Properties

type *string* (Required) The value is always function_call_output.

id *string* (Optional) The unique identifier of the function call output.

call_id *string* (Required) The identifier for the tool calling, which must match the call_id returned by the model.

output *string* (Required) The execution result of the tool function.

status *string* (Optional) Valid values: in_progress, completed, or incomplete.

Reasoning *object* (Optional) The model's internal reasoning process. You can pass the reasoning item from the previous response's output back into the input to carry over the reasoning context in multi-turn conversations. Properties

type *string* (Required) Set to reasoning.

id *string* (Required) The unique identifier of the reasoning content, from the previous response.

summary *array* (Required) The reasoning summary. Properties

type *string* (Required) Fixed to summary_text.

text *string* (Required) The summary text.

status *string* (Optional) The status. The value can be in_progress, completed, or incomplete.

**instructions ***string* (Optional) Inserted at the start of the context as a system instruction. When you use previous_response_id, the instructions from the previous turn are not carried over.

previous_response_id *string* (Optional) The unique ID of the previous response. A response id is valid for 7 days. Use this parameter to create a multi-turn conversation. The service automatically retrieves the conversation history associated with this ID and uses it as context. If you provide both the input message array and previous_response_id, the new messages in input are appended to the existing conversation history. This parameter cannot be used together with the conversation parameter.

conversation *string* (Optional) The conversation to which the current response belongs (see Conversations API). The history of the conversation is automatically passed as context to the current request, and the input and output of the request are also automatically added to the conversation after the response is complete. Cannot be used with previous_response_id.

stream *boolean* (Optional) Defaults to false. When set to true, the model response is streamed to the client in real time.

store *boolean* (Optional). Default: true. Specifies whether to store the model response. Stored responses can be referenced in subsequent API calls.

• false: The conversation content is not stored and cannot be used by previous_response_id or subsequent API calls.
• true: Stores the current model response, which can be used by previous_response_id and subsequent APIs.

tools *array* (Optional) An array of tools the model can use. You can include built-in tools, custom functions, or a mix of both. ** For the best responses, we recommend enabling the code_interpreter, web_search, and web_extractor tools. <b>Properties**

web_search Searches the web for up-to-date information. See Web search. Properties

type *string* (Required) Fixed to web_search. Example: \[{"type": "web_search"}\]

web_extractor Accesses and extracts web page content. Must be used with the web_search tool. The qwen3-max and qwen3-max-2026-01-23 models also require thinking mode to be enabled. See web scraping. Properties

type *string* (Required) The value is fixed to web_extractor. Usage example: \[{"type": "web_search"}, {"type": "web_extractor"}\]

code_interpreter Executes code, returns results, and supports data analysis. For the qwen3-max and qwen3-max-2026-01-23 models, you must also enable thinking mode. See Code Interpreter. Propertiestype *string* (Required) Fixed to code_interpreter. Usage example: \[{"type": "code_interpreter"}\]

web_search_image Searches for images based on a text description. See Text-to-image search. Propertiestype *string* (Required) Set to web_search_image. Usage example: \[{"type": "web_search_image"}\]

image_search Searches for similar or related images based on an input image URL. See Image search. Propertiestype *string* (Required) Fixed to image_search. Example: \[{"type": "image_search"}\]

file_search Searches an uploaded or associated knowledge base. See Knowledge retrieval. Properties

type *string* (Required) Set to file_search.

vector_store_ids *array** *(Required) The ID of the knowledge base to search. Currently, only one ID is supported per call. Example: \[{"type": "file_search", "vector_store_ids": \["your_knowledge_base_id"\]}\]

MCP call Calls external services via the Model Context Protocol (MCP). Properties

type *string* (Required) Fixed to mcp.

server_protocol *string* (Required) The communication protocol with the MCP service, such as "sse".

server_label *string* (Required) The service label used to identify the MCP service.

server_description *string* (Optional) A description of the service that helps the model understand its function and use cases.

server_url *string* (Required) The URL of the MCP service endpoint.

headers *object* (Optional) Request headers for authentication, such as Authorization. Example:

mcp_tool = {
 "type": "mcp",
 "server_protocol": "sse",
 "server_label": "amap-maps",
 "server_description": "The AMAP MCP Server covers 15 core APIs and provides full-scenario geographic information services, including custom map generation, navigation, ride-hailing, geocoding, reverse geocoding, IP-based location, weather queries, route planning (cycling, walking, driving, public transit), distance measurement, and keyword, nearby, and detail searches.",
 "server_url": "https://dashscope.aliyuncs.com/api/v1/mcps/amap-maps/sse",
 "headers": {
 "Authorization": "Bearer <your-mcp-server-token>"
 }
}

Custom tool function Allows the model to call functions that you define. When the model determines that it needs to call a tool, the response returns an output of the function_call type. See Function Calling. Properties

type *string* (Required) Must be set to function.

**name **string* *(Required) The name of the tool. It can be up to 64 tokens long and can contain only letters, numbers, underscores (_), and hyphens (-).

**description **string* *(Required) A description of the tool that helps the model decide when and how to call it.

parameters *object* (Optional) The parameter description for a tool must be a valid JSON Schema. If the parameters parameter is empty, the tool has no input parameters. ** To improve the accuracy of tool calling, we recommend passing in 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"\]
 }
}\]

<b>tool_choice** *string or object* (Optional). Default: auto. Controls how the model selects and calls tools. This parameter supports two formats: string mode and object mode. String mode

• auto: The model automatically decides whether to call a tool.
• none: Prevents the model from calling any tools.
• required: Forces the model to call the tool (available only when the tools list contains only one tool).

Object mode Sets a specific scope of tools for the model, allowing it to select and call only from this predefined list. Properties

mode *string* (Required)

• auto: The model automatically decides whether to call a tool.
• required: Forces the model to call a tool (only available when there is only one tool in the tools list).

tools *array*(Required) A list of tool definitions from which the model is allowed to choose.

\[
 { "type": "function", "name": "get_weather" }
\]

**type ***string* (Required) The allowed tool configuration type is fixed to allowed_tools.

**temperature **float* (Optional) * The sampling temperature, which controls the diversity of the generated text. Higher values (e.g., 0.8) make the output more random, while lower values (e.g., 0.2) make it more focused and deterministic. Range: [0, 2) We recommend altering temperature or top_p, but not both. See Text generation model overview.

**top_p **float* *(Optional) The probability threshold for nucleus sampling, which controls the diversity of the generated text. A higher top_p value results in more diverse text. A lower value produces more deterministic text. Range: (0, 1.0] We recommend altering temperature or top_p, but not both. See Text generation model overview.

enable_thinking *boolean* (Optional) Specifies whether to enable thinking mode. When this mode is enabled, the model thinks before it responds, and its reasoning is returned through an output item of the reasoning type. When you use thinking mode, we recommend that you also enable built-in tools to achieve the best model performance for complex tasks. Valid values:

• true
• false For default values for different models, see Supported models. ** This parameter is not a standard OpenAI parameter. In the Python SDK, pass this parameter by using extra_body={"enable_thinking": True}. In the Node.js SDK and with curl, use enable_thinking: true as a top-level parameter. We recommend using reasoning.effort instead because enable_thinking will be deprecated.

<b>reasoning** *object* (Optional) Controls the reasoning effort of the model. The model thinks before responding, and the reasoning is returned through an output item of the reasoning type. Properties

effort *string* (optional): The reasoning effort level. The default value is medium.

• none: Disables thinking and responds directly.
• minimal: Minimal thinking, fastest response
• low: Minimal thinking, prioritizing quick responses.
• medium (default): Moderate thinking, balancing speed with depth of thought.
• high: In-depth thinking with a focus on handling complex and specialized problems.

** reasoning.effort has a higher priority than enable_thinking. We recommend that you prioritize using reasoning.effort because enable_thinking will be deprecated.

## Response object (non-streaming output)

{
 "created_at": 1771165900.0,
 "id": "f75c28fb-4064-48ed-90da-4d2cc4362xxx",
 "model": "qwen3.6-plus",
 "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"
 }
 \]
 }
}

<b>id** *string* A unique identifier for this response, provided as a UUID-formatted string that is valid for 7 days. It can be used in the previous_response_id parameter to create a multi-turn conversation.

created_at *integer* The Unix timestamp (in seconds) for this request.

object *string* The object type. The value is fixed as response.

status *string* The status of the response generation. Possible values:

• completed
• failed
• in_progress
• cancelled
• queued
• incomplete

model *string* The ID of the model used to generate the response.

output *array* 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 *string* The type of the output item. Possible values:

• message: The content of the final response generated by the model.
• reasoning: The reasoning type. This parameter is returned when reasoning.effort is set to a value other than none or when thinking mode is enabled. Reasoning tokens are included in output_tokens_details.reasoning_tokens and are billed as reasoning tokens.
• function_call: The function call type that is returned when a custom function tool is used. You must handle the function call and return the result.
• web_search_call: The search call type that is returned when the web_search tool is used.
• code_interpreter_call: A code execution type. Returned when the code_interpreter tool is used.
• web_extractor_call: The web extractor type returned when you use the web_extractor tool. This type must be used with the web_search tool.
• web_search_image_call: A text-to-image search call type, which is returned when the web_search_image tool is used. It contains a list of the retrieved images.
• image_search_call: The call type for image-to-image search, which is returned when the image_search tool is used. It contains a list of retrieved similar images.
• mcp_call: The MCP call type, which is returned when you use the mcp tool. It contains the call result of the MCP service.
• file_search_call: The type for a knowledge base search call, which is returned when the file_search tool is used. It contains the retrieval query and results for the knowledge base.

id *string* A unique identifier for the output item. This field appears in all types of output items.

role *string* The message role is fixed as assistant. This parameter exists only when type is message.

status *string* The status of the output item. Possible values: completed (Completed) or in_progress (In progress). This field is present when the type is not reasoning.

name *string* The name of the tool or function. This field 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 *string* The parameters for the tool call, which are provided as a JSON string when type is function_call, web_search_image_call, image_search_call, or mcp_call. You must parse the string by using JSON.parse(). The content of arguments for different tool types:

• web_search_image_call: {"queries": \["search keyword 1", "search keyword 2"\]}, where queries is a list of search keywords that is 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 specifies the bounding box coordinates [x1, y1, x2, y2] of the search area. The coordinate values are in the range of 0 to 1000.
• function_call: The parameter object generated based on the user-defined function parameter schema.
• mcp_call: The parameter object for a function called in the MCP service.

call_id *string* The unique identifier of the function call. This parameter is present only when type is function_call. When you return the function call result, you need to use this ID to associate the request with the response.

content *array* An array of message content. This field is present only when type is message. Array element properties

type *string* The content type. The value is fixed to output_text.

text *string* The text content generated by the model.

annotations *array* An array of text annotations. This is usually an empty array.

summary *array* An array of reasoning summaries. This field is present only when the value of type is reasoning. Each element contains the type field (with the value summary_text) and the text field (the summary text).

action *object* Information about the search action. This field is present only when type is web_search_call. Properties

query *string* The search query.

type *string* The search type is fixed to search.

sources *array* A list of search sources. Each element contains type and url fields.

code *string* The code generated and executed by the model. This is present only when type is code_interpreter_call.

outputs *array* An array of code execution outputs. This is present only when type is code_interpreter_call. Each element contains a type field (with the value logs) and a logs field (the code execution logs).

container_id *string* The identifier of the Code Interpreter container. This field is present only when type is code_interpreter_call. It is used to associate multiple code executions in the same conversation.

goal *string* The description of the extraction target, which specifies the information to be extracted from the webpage. This parameter is present only when type is web_extractor_call.

output *string* The result of the tool call, as a string.

• The content summary of the web extraction when type is web_extractor_call.
• When type is web_search_image_call or image_search_call, the value is a JSON string that contains an array of image search results. Each element contains the title (image title), url (image URL), and index (sequence number) fields.
• The JSON string result returned by the MCP service when type is mcp_call.

urls *array* The list of extracted webpage URLs. This field is present only when type is web_extractor_call.

server_label *string* The MCP service tag. This tag is present only when type is mcp_call. It identifies the MCP service used for this call.

queries *array* A list of queries used for knowledge base retrieval. This field is present only when type is file_search_call. The array elements are strings that represent the search queries generated by the model.

results *array* An array of the knowledge base search results. This field is present only when type is file_search_call. Array element properties

file_id *string* The file ID of the matching document.

filename *string* The filename of the matching document.

score *float* The relevance score of the match, ranging from 0 to 1. A higher value indicates greater relevance.

text *string* A snippet of the matched document content.

usage *object* An object containing token usage information for the request. Properties

input_tokens *integer* The number of tokens in the input.

output_tokens *integer* The number of tokens in the model's output.

total_tokens *integer* The total number of tokens consumed, equal to the sum of input_tokens and output_tokens.

input_tokens_details *object* A fine-grained breakdown of input tokens. Properties

cached_tokens *integer* The number of tokens that hit the context cache. See Context Cache.

output_tokens_details *object* A fine-grained breakdown of output tokens. Properties

reasoning_tokens *integer* The number of tokens used for reasoning.

x_details *array* An array of billing details for this request. Provides finer-grained multimodal token breakdown than the top-level usage field. Properties

input_tokens *integer* The number of tokens in the input.

output_tokens *integer* The number of tokens in the model's output.

total_tokens *integer* The total number of tokens consumed, equal to the sum of input_tokens and output_tokens.

x_billing_type *string* Set to response_api.

image_tokens *integer* The number of input image tokens. Returned when image input is included; equivalent to input_tokens_details.image_tokens.

input_tokens_details *object* Granular breakdown of input tokens. Returned for multimodal input. Currently distinguishes only text_tokens and image_tokens; video and audio token breakdowns are not returned. Properties

text_tokens *integer* The number of input text tokens.

image_tokens *integer* The number of input image tokens.

output_tokens_details *object* Granular breakdown of output tokens. Includes an additional text_tokens field (returned for multimodal input) compared to the top-level output_tokens_details. Properties

reasoning_tokens *integer* The number of reasoning tokens.

text_tokens *integer* The number of output text tokens. Returned for multimodal input.

plugins *object* Built-in tool call statistics. Returned when a built-in tool (such as web_search) is used. The content is the same as the top-level x_tools field. Properties

web_search *object* Web search call statistics. Properties

count *integer* The number of web search calls in this response.

prompt_tokens_details *object* Cache details for input tokens. Returned when session cache is enabled; may be an empty object when image input is included but no cache is hit. Properties

cached_tokens *integer* The number of tokens that hit the cache.

cache_creation_input_tokens *integer* The number of tokens for which a new cache entry was created in this request.

cache_creation *object* Cache creation details. Properties

ephemeral_5m_input_tokens *integer* The number of tokens for which a new 5-minute ephemeral cache entry was created.

cache_type *string* Cache type. Set to ephemeral.

x_tools *object* Tool usage statistics. When built-in tools are used, this object includes the call count for each tool. Example: {"web_search": {"count": 1}​}

error *object* The error object returned when the model fails to generate a response. The value is null on success.

tools *array* Echoes the full content of the tools parameter from the request. The structure is the same as the tools parameter in the request body.

tool_choice *string* Echoes the value of the tool_choice parameter in the request. The enumerated values are auto, none, or required.

## Response chunk object (streaming output)

## Basic call

// response.created - Response created
{"response":{"id":"428c90e9-9cd6-90a6-9726-c02b08ebexxx","created_at":1769082930,"object":"response","status":"queued",...},"sequence_number":0,"type":"response.created"}

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

// response.output_item.added - New output item 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 - New content block 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 (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 and science","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 completed
{"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 simulates human intelligent behavior by computer systems...","type":"response.output_text.done"}

// response.content_part.done - Content block completed
{"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 - Output item completed
{"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 - Response completed (includes full response and usage)
{"response":{"id":"428c90e9-9cd6-90a6-9726-c02b08ebexxx","created_at":1769082930,"model":"qwen3-max-2026-01-23","object":"response","output":\[...\],"status":"completed","usage":{"input_tokens":37,"output_tokens":243,"total_tokens":280,...}​},"sequence_number":56,"type":"response.completed"}

## Web scraping

id:1
event:response.created
:HTTP_STATUS/200
data:{"sequence_number":0,"type":"response.created","response":{"output":\[\],"parallel_tool_calls":false,"created_at":1769435906,"tool_choice":"auto","model":"","id":"863df8d9-cb29-4239-a54f-3e15a2427xxx","tools":\[\],"object":"response","status":"queued"}​}

id:2
event:response.in_progress
:HTTP_STATUS/200
data:{"sequence_number":1,"type":"response.in_progress","response":{"output":\[\],"parallel_tool_calls":false,"created_at":1769435906,"tool_choice":"auto","model":"","id":"863df8d9-cb29-4239-a54f-3e15a2427xxx","tools":\[\],"object":"response","status":"in_progress"}​}

id:3
event:response.output_item.added
:HTTP_STATUS/200
data:{"sequence_number":2,"item":{"summary":\[\],"type":"reasoning","id":"msg_5bd0c6df-19b8-4a04-bc00-8042a224exxx"},"output_index":0,"type":"response.output_item.added"}

id:4
event:response.reasoning_summary_text.delta
:HTTP_STATUS/200
data:{"delta":"The user wants me to:\\n1. Search for the Alibaba Cloud official website.\\n2. Extract key information from the homepage.\\n\\nI need to first search for the URL of the Alibaba Cloud website, then use the web_extractor tool to access the website and extract key information.","sequence_number":3,"output_index":0,"type":"response.reasoning_summary_text.delta","item_id":"msg_5bd0c6df-19b8-4a04-bc00-8042a224exxx","summary_index":0}

id:14
event:response.reasoning_summary_text.done
:HTTP_STATUS/200
data:{"sequence_number":13,"text":"The user wants me to:\\n1. Search for the Alibaba Cloud official website.\\n2. Extract key information from the homepage.\\n\\nI need to first search for the URL of the Alibaba Cloud website, then use the web_extractor tool to access the website and extract key information.","output_index":0,"type":"response.reasoning_summary_text.done","item_id":"msg_5bd0c6df-19b8-4a04-bc00-8042a224exxx","summary_index":0}

id:15
event:response.output_item.done
:HTTP_STATUS/200
data:{"sequence_number":14,"item":{"summary":\[{"type":"summary_text","text":"The user wants me to:\\n1. Search for the Alibaba Cloud official website.\\n2. Extract key information from the homepage.\\n\\nI need to first search for the URL of the Alibaba Cloud website, then use the web_extractor tool to access the website and extract key information."}\],"type":"reasoning","id":"msg_5bd0c6df-19b8-4a04-bc00-8042a224exxx"},"output_index":1,"type":"response.output_item.done"}

id:16
event:response.output_item.added
:HTTP_STATUS/200
data:{"sequence_number":15,"item":{"action":{"type":"search","query":"Web search"},"id":"msg_a8a686b1-0a57-40e1-bb55-049a89cd4xxx","type":"web_search_call","status":"in_progress"},"output_index":1,"type":"response.output_item.added"}

id:17
event:response.web_search_call.in_progress
:HTTP_STATUS/200
data:{"sequence_number":16,"output_index":1,"type":"response.web_search_call.in_progress","item_id":"msg_a8a686b1-0a57-40e1-bb55-049a89cd4xxx"}

id:19
event:response.web_search_call.completed
:HTTP_STATUS/200
data:{"sequence_number":18,"output_index":1,"type":"response.web_search_call.completed","item_id":"msg_a8a686b1-0a57-40e1-bb55-049a89cd4xxx"}

id:20
event:response.output_item.done
:HTTP_STATUS/200
data:{"sequence_number":19,"item":{"action":{"sources":\[{"type":"url","url":"https://cn.aliyun.com/"},{"type":"url","url":"https://www.aliyun.com/"}\],"type":"search","query":"Web search"},"id":"msg_a8a686b1-0a57-40e1-bb55-049a89cd4xxx","type":"web_search_call","status":"completed"},"output_index":1,"type":"response.output_item.done"}

id:33
event:response.output_item.added
:HTTP_STATUS/200
data:{"sequence_number":32,"item":{"urls":\["https://cn.aliyun.com/"\],"goal":"Extract key information from the Alibaba Cloud homepage, including: company positioning/profile, core products and services, main business sections, special features/solutions, latest news/events, free trial/promotional information, navigation menu structure, etc.","id":"msg_8c2cf651-48a5-460c-aa7a-bea5b09b4xxx","type":"web_extractor_call","status":"in_progress"},"output_index":3,"type":"response.output_item.added"}

id:34
event:response.output_item.done
:HTTP_STATUS/200
data:{"sequence_number":33,"item":{"output":"The useful information in https://cn.aliyun.com/ for user goal Extract key information from the Alibaba Cloud homepage, including: company positioning/profile, core products and services, main business sections, special features/solutions, latest news/events, free trial/promotional information, navigation menu structure, etc. as follows: \\n\\nEvidence in page: \\n## Tongyi large model, the first choice for enterprises to embrace the AI era\\n\\n## A complete product system to create a cloud of technological innovation for enterprises\\n\\nAll cloud products## Relying on the coordinated development of large models and cloud computing to make AI within reach\\n\\nAll AI solutions\\n\\nSummary: \\nAlibaba Cloud positions itself as a leading enterprise AI solution provider centered around the Tongyi large model...","urls":\["https://cn.aliyun.com/"\],"goal":"Extract key information from the Alibaba Cloud homepage, including: company positioning/profile, core products and services, main business sections, special features/solutions, latest news/events, free trial/promotional information, navigation menu structure, etc.","id":"msg_8c2cf651-48a5-460c-aa7a-bea5b09b4xxx","type":"web_extractor_call","status":"completed"},"output_index":3,"type":"response.output_item.done"}

id:50
event:response.output_item.added
:HTTP_STATUS/200
data:{"sequence_number":50,"item":{"content":\[{"type":"text","text":""}\],"type":"message","id":"msg_final","role":"assistant"},"output_index":5,"type":"response.output_item.added"}

id:51
event:response.output_text.delta
:HTTP_STATUS/200
data:{"delta":"I have found the Alibaba Cloud official website and extracted the key information from the homepage:\\n\\n","sequence_number":51,"output_index":5,"type":"response.output_text.delta"}

id:60
event:response.completed
:HTTP_STATUS/200
data:{"type":"response.completed","response":{"id":"863df8d9-cb29-4239-a54f-3e15a2427xxx","status":"completed","usage":{"input_tokens":45,"output_tokens":320,"total_tokens":365}​}}

## Text-to-image search

// 1. response.created - Response created
id:1
event:response.created
data:{"sequence_number":0,"type":"response.created","response":{"output":\[\],"status":"queued",...}​}

// 2. response.in_progress - Response in progress
id:2
event:response.in_progress
data:{"sequence_number":1,"type":"response.in_progress","response":{"status":"in_progress",...}​}

// 3. response.output_item.added - Reasoning starts
id:3
event:response.output_item.added
data:{"sequence_number":2,"item":{"summary":\[\],"type":"reasoning","id":"msg_xxx"},"output_index":0,"type":"response.output_item.added"}

// 4. response.reasoning_summary_text.delta - Reasoning summary delta
id:4
event:response.reasoning_summary_text.delta
data:{"delta":"The user wants to find a picture of a cat. I need to use the web_search_image tool to search...","sequence_number":3,"output_index":0,"type":"response.reasoning_summary_text.delta","item_id":"msg_xxx","summary_index":0}

// 5. response.reasoning_summary_text.done - Reasoning summary done
id:10
event:response.reasoning_summary_text.done
data:{"sequence_number":9,"text":"The user wants to find a picture of a cat. I need to use the web_search_image tool to search for cat pictures.","output_index":0,"type":"response.reasoning_summary_text.done","item_id":"msg_xxx","summary_index":0}

// 6. response.output_item.done - Reasoning item done
id:11
event:response.output_item.done
data:{"sequence_number":10,"item":{"summary":\[{"type":"summary_text","text":"..."}\],"type":"reasoning","id":"msg_xxx"},"output_index":0,"type":"response.output_item.done"}

// 7. response.output_item.added - Text-to-image search tool call starts (status: in_progress, with name and arguments)
id:12
event:response.output_item.added
data:{"sequence_number":11,"item":{"name":"web_search_image","arguments":"{\\"queries\\": \[\\"cat picture\\", \\"cute cat\\"\]}","id":"msg_xxx","type":"web_search_image_call","status":"in_progress"},"output_index":1,"type":"response.output_item.added"}

// 8. response.output_item.done - Text-to-image search tool call done (with full output search results)
id:13
event:response.output_item.done
data:{"sequence_number":12,"item":{"name":"web_search_image","output":"\[{\\"title\\": \\"Cute kitten...\\", \\"url\\": \\"https://example.com/cat.jpg\\", \\"index\\": 1}, ...\]","arguments":"{\\"queries\\": \[\\"cat picture\\", \\"cute cat\\"\]}","id":"msg_xxx","type":"web_search_image_call","status":"completed"},"output_index":1,"type":"response.output_item.done"}

// 9-12. Second round of reasoning + final message output (same as basic call)
// response.output_item.added (reasoning) → reasoning_summary_text.delta/done → response.output_item.done (reasoning)
// response.output_item.added (message) → response.content_part.added → response.output_text.delta → response.output_text.done → response.content_part.done → response.output_item.done (message)

// 13. response.completed - Response completed
id:118
event:response.completed
data:{"sequence_number":117,"type":"response.completed","response":{"output":\[...\],"status":"completed","usage":{"input_tokens":7895,"output_tokens":318,"total_tokens":8213,"x_tools":{"web_search_image":{"count":1}​}}​}}

## Image-to-image search

// 1-6. Reasoning phase (same as text-to-image search)

// 7. response.output_item.added - Image-to-image search tool call starts
// Note: arguments includes img_idx (image index) and bbox (bounding box for the search area)
id:29
event:response.output_item.added
data:{"sequence_number":29,"item":{"name":"image_search","arguments":"{\\"img_idx\\": 0, \\"bbox\\": \[0, 0, 1000, 1000\]}","id":"msg_xxx","type":"image_search_call","status":"in_progress"},"output_index":1,"type":"response.output_item.added"}

// 8. response.output_item.done - Image-to-image search tool call completed
id:30
event:response.output_item.done
data:{"sequence_number":30,"item":{"name":"image_search","output":"\[{\\"title\\": \\"Ink wash mountain background...\\", \\"url\\": \\"https://example.com/landscape.jpg\\", \\"index\\": 1}, ...\]","arguments":"{\\"img_idx\\": 0, \\"bbox\\": \[0, 0, 1000, 1000\]}","id":"msg_xxx","type":"image_search_call","status":"completed"},"output_index":1,"type":"response.output_item.done"}

// 9-12. Second round of reasoning + final message output (same as basic call)

// 13. response.completed
id:408
event:response.completed
data:{"sequence_number":407,"type":"response.completed","response":{"output":\[...\],"status":"completed","usage":{"input_tokens":8371,"output_tokens":417,"total_tokens":8788,"x_tools":{"image_search":{"count":1}​}}​}}

## MCP

// 1-6. Reasoning phase (same as other tools)

// 7. response.mcp_call_arguments.delta - MCP arguments delta (MCP-specific event)
id:27
event:response.mcp_call_arguments.delta
data:{"delta":"{\\"city\\": \\"Beijing\\"}","sequence_number":26,"output_index":1,"type":"response.mcp_call_arguments.delta","item_id":"msg_xxx"}

// 8. response.mcp_call_arguments.done - MCP arguments done (MCP-specific event)
id:28
event:response.mcp_call_arguments.done
data:{"sequence_number":27,"arguments":"{\\"city\\": \\"Beijing\\"}","output_index":1,"type":"response.mcp_call_arguments.done","item_id":"msg_xxx"}

// 9. response.output_item.added - MCP tool call starts (with name, server_label, and arguments)
id:29
event:response.output_item.added
data:{"sequence_number":28,"item":{"name":"amap-maps-maps_weather","server_label":"MCP Server","arguments":"{\\"city\\": \\"Beijing\\"}","id":"msg_xxx","type":"mcp_call","status":"in_progress"},"output_index":1,"type":"response.output_item.added"}

// 10. response.mcp_call.completed - MCP call completed (MCP-specific event)
id:30
event:response.mcp_call.completed
data:{"sequence_number":29,"output_index":1,"type":"response.mcp_call.completed","item_id":"msg_xxx"}

// 11. response.output_item.done - MCP output item completed (with full output)
id:31
event:response.output_item.done
data:{"sequence_number":30,"item":{"output":"{\\"city\\":\\"Beijing\\",\\"forecasts\\":\[...\]}","name":"amap-maps-maps_weather","server_label":"MCP Server","arguments":"{\\"city\\": \\"Beijing\\"}","id":"msg_xxx","type":"mcp_call","status":"completed"},"output_index":1,"type":"response.output_item.done"}

// 12-15. Second round of reasoning + final message output

// 16. response.completed
id:172
event:response.completed
data:{"sequence_number":171,"type":"response.completed","response":{"output":\[...\],"status":"completed","usage":{"input_tokens":5019,"output_tokens":539,"total_tokens":5558}​}}

## Knowledge base search

// 1-6. Reasoning phase (same as other tools)

// 7. response.output_item.added - Knowledge base search starts (with queries, no results)
id:19
event:response.output_item.added
data:{"sequence_number":18,"item":{"id":"msg_xxx","type":"file_search_call","queries":\["Alibaba Cloud Model Studio X1 phone","Alibaba Cloud Model Studio X1 phone","Model Studio X1"\],"status":"in_progress"},"output_index":1,"type":"response.output_item.added"}

// 8. response.file_search_call.in_progress - Search in progress (file_search-specific event)
id:20
event:response.file_search_call.in_progress
data:{"sequence_number":19,"output_index":1,"type":"response.file_search_call.in_progress","item_id":"msg_xxx"}

// 9. response.file_search_call.searching - Searching (file_search-specific event)
id:21
event:response.file_search_call.searching
data:{"sequence_number":20,"output_index":1,"type":"response.file_search_call.searching","item_id":"msg_xxx"}

// 10. response.file_search_call.completed - Search completed (file_search-specific event)
id:22
event:response.file_search_call.completed
data:{"sequence_number":21,"output_index":1,"type":"response.file_search_call.completed","item_id":"msg_xxx"}

// 11. response.output_item.done - Output item completed (with queries + results)
id:23
event:response.output_item.done
data:{"sequence_number":22,"item":{"id":"msg_xxx","type":"file_search_call","queries":\["Alibaba Cloud Model Studio X1 phone","Alibaba Cloud Model Studio X1 phone","Model Studio X1"\],"results":\[{"score":0.7519,"filename":"Introduction to Alibaba Cloud Model Studio series phones","text":"Alibaba Cloud Model Studio X1 --- Enjoy an ultimate visual experience...","file_id":"file_xxx"}\],"status":"completed"},"output_index":1,"type":"response.output_item.done"}

// 12-15. Second round of reasoning + final message output

// 16. response.completed
id:146
event:response.completed
data:{"sequence_number":145,"type":"response.completed","response":{"output":\[...\],"status":"completed","usage":{"input_tokens":1576,"output_tokens":722,"total_tokens":2298,"x_tools":{"file_search":{"count":1}​}}​}}

The streaming output returns a series of JSON objects. Each object contains a type field to identify the event type and a sequence_number field to identify the event order. The response.completed event marks the end of the stream.

type *string* The event type identifier. Valid values:

• response.created: Triggered when the response is created, and the status is queued.
• response.in_progress: Triggered when the response starts processing, and the status becomes in_progress.
• response.output_item.added: Triggered when a new output item (such as message or web_extractor_call) is added to the output array. When item.type is web_extractor_call, this indicates that the Web extractor tool calling starts.
• response.content_part.added: Triggered when a new content block is added to the content array of an output item.
• response.output_text.delta: Triggered multiple times when incremental text is generated, and the delta field contains the new text fragment.
• response.output_text.done: Triggered when text generation is complete. The text field contains the complete text.
• response.content_part.done: Triggered when the content block is complete. The part object contains the complete content block.
• response.output_item.done: Triggered when the generation of an output item is complete. The item object contains the complete output item. When item.type is web_extractor_call, it indicates that the web extractor tool call is complete.
• response.reasoning_summary_text.delta: (When thinking mode is enabled) The incremental text for the reasoning summary. The delta field contains the new summary fragment.
• response.reasoning_summary_text.done: (When thinking mode is enabled) The reasoning summary is complete, and the text field contains the complete summary.
• response.web_search_call.in_progress / searching / completed: (When using the web_search tool) Events indicating a change in the search status.
• response.code_interpreter_call.in_progress / interpreting / completed: (When using the code_interpreter tool) Events indicating a change in the code execution status.
• Note: When you use the web_extractor tool, there is no dedicated event type identifier. Web extractor tool calls are passed through the generic response.output_item.added and response.output_item.done events. You can identify these calls by the item.type field, which has a value of web_extractor_call.
• response.mcp_call_arguments.delta / response.mcp_call_arguments.done: (When using the mcp tool) Incremental and completion events for MCP call arguments.
• response.mcp_call.completed: (When using the mcp tool) Indicates that the MCP service call is complete.
• response.file_search_call.in_progress / searching / completed: (When using the file_search tool) Events indicating a change in the knowledge base search status.
• Note: When you use the web_search_image and image_search tools, there are no dedicated intermediate state events. The tool call is communicated through the response.output_item.added (call start) and response.output_item.done (call completion) events.
• response.completed: Triggered when the response generation is complete. The response object contains the full response, including usage. This event marks the end of the stream.

sequence_number *integer* The sequence number for an event, starting from 0 and incrementing with each event. Use this number to process events in the correct order.

response *object* Response object. Appears in the response.created, response.in_progress, and response.completed events. In the response.completed event, this object contains the complete response data, including output and usage, and its structure is the same as the Response object for a non-streaming response.

item *object* The 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 (content is an empty array), and in the done event, it is a complete object. Properties

id *string* The unique identifier of the output item, such as msg_xxx.

type *string* The type of the output item. Valid values: message, reasoning, web_search_call, web_search_image_call, image_search_call, mcp_call, and file_search_call.

role *string* The role of the message, which is always assistant. This field exists only when item.type is message.

status *string* Generation status. In an added event, the status is in_progress, and in a done event, it is completed.

content *array* An array of message content. In the added event, the array is empty \[\], while in the done event, it contains complete content block objects with the same structure as part objects.

part *object* The content block object. It appears in the response.content_part.added and response.content_part.done events. Properties

type *string* The type of the content block, which is always output_text.

text *string* The text content. The value is an empty string in the added event and the complete text in the done event.

annotations *array* An array of text annotations. This is usually an empty array.

logprobs *object \| null* The log probability information for the token. This value is always null.

delta *string* Incremental text. This appears in the response.output_text.delta event and contains the newly added text fragment. You should concatenate all delta fragments to obtain the complete text.

text *string* The complete text content. It appears in the response.output_text.done event, contains the full text of the content block, and can be used to verify the concatenation result of delta.

item_id *string* The unique identifier of the output item. It associates events belonging to the same output item.

output_index *integer* The index of the output item in the output array.

content_index *integer* The index of the content block in the content array.

summary_index *integer* The index of an item in the summary array. It appears in the response.reasoning_summary_text.delta and response.reasoning_summary_text.done events.

FAQ

Q: How do I pass context for a multi-turn conversation?

A: To start a new turn, pass the id from the previous model response as the previous_response_id parameter in your new request.

Q: Why are some fields in the response examples not described in this document?

A: If you use the official OpenAI SDK, it may output additional fields based on its internal model structure. These fields are part of the OpenAI protocol but are not currently supported by our service, so their value is null. You can safely ignore them and focus only on the fields described in this document.