BRASILTradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗
Compatibilidade e limitações
#Respostas OpenAI
API de respostas compatíveis
O caminho do URL herdado /api/v2/apps/protocols/compatible-mode/v1/responses não é mais mantido e sua funcionalidade não é mais garantida. Migrar para o novo caminho /compatible-mode/v1/responses o mais rápido possível.
Compatibilidade e limitações
Esta API é compatível com OpenAI, mas existem diferenças importantes em parâmetros, recursos e comportamentos.
As solicitações processam apenas os parâmetros listados neste documento. Quaisquer parâmetros OpenAI não mencionados serão ignorados.
Principais diferenças:
-
Parâmetros não suportados: alguns parâmetros não são suportados, como
background(somente síncrono). -
Controle de esforço de raciocínio: Use o
reasoning.effortparâmetro para controlar o esforço de raciocínio do modelo. Para obter detalhes de uso, consulte a descrição do parâmetro abaixo. -
Parâmetros adicionais: Suporta parâmetros extras além das especificações do OpenAI, como
enable_thinking(obsoleto, usereasoning.effortem vez disso). -
Cache de contexto sem esforço: habilite o cache automático do lado do servidor para conversas multivoltas com um único cabeçalho de solicitação. Consulte Cache de Sessão.
-
Limite de contexto: para reservar espaço para chamadas de ferramentas integradas e geração de raciocínio, o contexto máximo de entrada da API Responses é de aproximadamente 80% da janela de contexto do modelo (deixando um buffer de cerca de 20%). Qualquer excesso é automaticamente truncado sem gerar erro ou interromper a solicitação.
OpenAPI
openapi: 3.1.0
info:
title: Qwen OpenAI-compatible Responses API
description: Call Qwen models using the OpenAI-compatible Responses API. Supports built-in tools, multi-turn context management, and thinking mode.
version: 1.0.0
servers:
- url: https://maas.qwencloudapi.com
description: Singapore
security:
- BearerAuth: []
paths:
/compatible-mode/v1/responses:
post:
operationId: openaiResponses
summary: Create a response
description: Send input to a Qwen model and receive a generated response using the OpenAI-compatible Responses API. Supports built-in tools (web search, code interpreter, web scraping, image search, MCP, knowledge base search), multi-turn context management via `previous_response_id`, and thinking mode.
parameters:
- name: x-dashscope-session-cache
in: header
required: false
schema:
type: string
enum:
- enable
- disable
default: disable
description: |-
Controls [session cache](/developer-guides/text-generation/context-cache#session-cache) for multi-turn conversations using `previous_response_id`. When enabled, the server automatically caches conversation context to reduce latency and cost.
- `enable`: Enables session cache. Cache creation tokens are billed at 125% of the standard input price; cache hits at 10%. Cache is valid for 5 minutes (resets on hit). Minimum 1024 tokens for cache creation.
- `disable` (default): Disables session cache. Falls back to implicit cache if supported by the model.
**Caching behavior:**
- Session cache enabled:
- Model supports explicit cache: Uses explicit cache. For billing and constraints, see [Explicit cache](/developer-guides/text-generation/context-cache#explicit-cache).
- Model does not support explicit cache but supports implicit cache: Uses implicit cache. For billing and constraints, see [Implicit cache](/developer-guides/text-generation/context-cache#implicit-cache).
- Session cache not enabled: Same as normal API calls. Implicit cache is still automatically enabled for models that support it, but without the session cache benefits.
Pass via SDK: `default_headers` (Python) or `defaultHeaders` (Node.js).
To confirm whether the cache was hit, check `usage.input_tokens_details.cached_tokens` in the response. A value greater than 0 indicates a cache hit.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ResponsesRequest"
example:
model: qwen3.8-max
input: What can you do?
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: "#/components/schemas/ResponseObject"
example:
created_at: 1771165900
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
text/event-stream:
schema:
$ref: "#/components/schemas/ResponseChunk"
examples:
basic_call:
summary: Basic call
value:
response:
id: 428c90e9-9cd6-90a6-9726-c02b08ebexxx
created_at: 1769082930
object: response
status: queued
sequence_number: 0
type: response.created
web_scraping:
summary: Web scraping
value:
sequence_number: 2
item:
summary: []
type: reasoning
id: msg_5bd0c6df-19b8-4a04-bc00-8042a224exxx
output_index: 0
type: response.output_item.added
text_to_image_search:
summary: Text-to-image search
value:
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
image_search:
summary: Image search
value:
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
mcp:
summary: MCP
value:
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
knowledge_base_search:
summary: Knowledge base search
value:
sequence_number: 18
item:
id: msg_xxx
type: file_search_call
queries:
- Bailian X1 phone
- Bailian X1
status: in_progress
output_index: 1
type: response.output_item.added
"400":
description: Invalid request parameters
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
request_id: 0bf11b24-0c67-95da-bb15-f85dabcfdb7f
code: InvalidParameter
message: "[400] missing_required_parameter: Missing required parameter: 'model'."
"401":
description: Authentication failed
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
request_id: 5dc15bba-5586-9f64-980f-c36b679d9a65
code: InvalidApiKey
message: Invalid API-key provided.
"429":
description: Rate limit exceeded. This endpoint returns rate limit errors with HTTP 200 instead of 429. The response body is a ResponseObject where `status` is `"failed"` and the `error` field contains details. Check the `status` field in the response body rather than the HTTP status code.
content:
application/json:
schema:
$ref: "#/components/schemas/ResponseObject"
example:
created_at: 1775189716
error:
code: server_error
message: Operation model request rate limit exceeded, please try again later.
id: resp_e158ca4e-a71c-9a8b-aebe-169a650508d0
model: ""
object: response
output: []
parallel_tool_calls: false
status: failed
tool_choice: auto
tools: []
x-codeSamples:
- lang: python
label: Basic call
source: |-
import os
from openai import OpenAI
client = OpenAI(
# If environment variable is not set, replace with: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://maas.qwencloudapi.com/compatible-mode/v1",
)
response = client.responses.create(
model="qwen3.8-max",
input="What can you do?"
)
# Get model response
print(response.output_text)
- lang: javascript
label: Basic call
source: |-
import OpenAI from "openai";
const openai = new OpenAI({
// If environment variable is not set, replace with: apiKey: "sk-xxx"
apiKey: process.env.DASHSCOPE_API_KEY,
baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1"
});
async function main() {
const response = await openai.responses.create({
model: "qwen3.8-max",
input: "What can you do?"
});
// Get model response
console.log(response.output_text);
}
main();
- lang: curl
label: Basic call
source: |-
curl -X POST https://maas.qwencloudapi.com/compatible-mode/v1/responses \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.8-max",
"input": "What can you do?"
}'
- lang: python
label: Streaming
source: |-
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://maas.qwencloudapi.com/compatible-mode/v1",
)
stream = client.responses.create(
model="qwen3.8-max",
input="Please briefly introduce artificial intelligence.",
stream=True
)
print("Receiving stream output:")
for event in stream:
if event.type == 'response.output_text.delta':
print(event.delta, end='', flush=True)
elif event.type == 'response.completed':
print("\nStream completed")
print(f"Total tokens: {event.response.usage.total_tokens}")
- lang: javascript
label: Streaming
source: |-
import OpenAI from "openai";
const openai = new OpenAI({
apiKey: process.env.DASHSCOPE_API_KEY,
baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1"
});
async function main() {
const stream = await openai.responses.create({
model: "qwen3.8-max",
input: "Please briefly introduce artificial intelligence.",
stream: true
});
console.log("Receiving stream 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("\nStream completed");
console.log(`Total tokens: ${event.response.usage.total_tokens}`);
}
}
}
main();
- lang: curl
label: Streaming
source: |-
curl -X POST https://maas.qwencloudapi.com/compatible-mode/v1/responses \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
--no-buffer \
-d '{
"model": "qwen3.8-max",
"input": "Please briefly introduce artificial intelligence.",
"stream": true
}'
- lang: python
label: Multi-turn
source: |-
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://maas.qwencloudapi.com/compatible-mode/v1",
)
# First turn
response1 = client.responses.create(
model="qwen3.8-max",
input="My name is Alice, please remember it."
)
print(f"First reply: {response1.output_text}")
# Second turn - use previous_response_id to link context
response2 = client.responses.create(
model="qwen3.8-max",
input="Do you remember my name?",
previous_response_id=response1.id
)
print(f"Second reply: {response2.output_text}")
- lang: javascript
label: Multi-turn
source: |-
import OpenAI from "openai";
const openai = new OpenAI({
apiKey: process.env.DASHSCOPE_API_KEY,
baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1"
});
async function main() {
const response1 = await openai.responses.create({
model: "qwen3.8-max",
input: "My name is Alice, please remember it."
});
console.log(`First reply: ${response1.output_text}`);
const response2 = await openai.responses.create({
model: "qwen3.8-max",
input: "Do you remember my name?",
previous_response_id: response1.id
});
console.log(`Second reply: ${response2.output_text}`);
}
main();
- lang: curl
label: Multi-turn
source: |-
# First turn
curl -X POST https://maas.qwencloudapi.com/compatible-mode/v1/responses \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.8-max",
"input": "My name is Alice, please remember it."
}'
# Second turn - use the id from the first response as previous_response_id
curl -X POST https://maas.qwencloudapi.com/compatible-mode/v1/responses \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.8-max",
"input": "Do you remember my name?",
"previous_response_id": "resp_id_from_first_turn"
}'
- lang: python
label: Thinking
source: |-
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://maas.qwencloudapi.com/compatible-mode/v1",
)
response = client.responses.create(
model="qwen3.8-max",
input="Which is larger, 9.9 or 9.11?",
reasoning={"effort": "medium"}
)
for item in response.output:
if item.type == "reasoning":
print("=== Thinking ===")
for summary in item.summary:
print(summary.text)
elif item.type == "message":
print("\n=== Answer ===")
print(item.content[0].text)
print(f"\nThinking tokens: {response.usage.output_tokens_details.reasoning_tokens}")
- lang: javascript
label: Thinking
source: |-
import OpenAI from "openai";
const openai = new OpenAI({
apiKey: process.env.DASHSCOPE_API_KEY,
baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1"
});
async function main() {
const response = await openai.responses.create({
model: "qwen3.8-max",
input: "Which is larger, 9.9 or 9.11?",
reasoning: { effort: "medium" }
});
for (const item of response.output) {
if (item.type === "reasoning") {
console.log("=== Thinking ===");
for (const summary of item.summary) {
console.log(summary.text);
}
} else if (item.type === "message") {
console.log("\n=== Answer ===");
console.log(item.content[0].text);
}
}
console.log(`\nThinking tokens: ${response.usage.output_tokens_details.reasoning_tokens}`);
}
main();
- lang: curl
label: Thinking
source: |-
curl -X POST https://maas.qwencloudapi.com/compatible-mode/v1/responses \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.8-max",
"input": "Which is larger, 9.9 or 9.11?",
"reasoning": {"effort": "medium"}
}'
- lang: python
label: Built-in tools
source: |-
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://maas.qwencloudapi.com/compatible-mode/v1",
)
response = client.responses.create(
model="qwen3.8-max",
input="Search for today's weather in Hangzhou",
tools=[
{"type": "web_search"},
{"type": "code_interpreter"},
{"type": "web_extractor"}
],
reasoning={"effort": "medium"}
)
print(response.output_text)
- lang: javascript
label: Built-in tools
source: |-
import OpenAI from "openai";
const openai = new OpenAI({
apiKey: process.env.DASHSCOPE_API_KEY,
baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1"
});
async function main() {
const response = await openai.responses.create({
model: "qwen3.8-max",
input: "Search for today's weather in Hangzhou",
tools: [
{ type: "web_search" },
{ type: "code_interpreter" },
{ type: "web_extractor" }
],
reasoning: { effort: "medium" }
});
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 === "message") {
console.log(`Reply: ${item.content[0].text}`);
}
}
}
main();
- lang: curl
label: Built-in tools
source: |-
curl -X POST https://maas.qwencloudapi.com/compatible-mode/v1/responses \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.8-max",
"input": "Search for today's weather in Hangzhou",
"tools": [
{"type": "web_search"},
{"type": "code_interpreter"},
{"type": "web_extractor"}
],
"reasoning": {"effort": "medium"}
}'
- lang: python
label: Session cache
source: |-
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://maas.qwencloudapi.com/compatible-mode/v1",
default_headers={"x-dashscope-session-cache": "enable"}
)
# Long text to trigger caching (must exceed 1024 tokens)
long_context = "Artificial intelligence is a major branch of computer science. " * 80
response1 = client.responses.create(
model="qwen3.8-max",
input=long_context + "\n\nBriefly introduce the Random Forest algorithm."
)
print(f"First reply: {response1.output_text}")
# Second turn - cache is handled automatically by the server
response2 = client.responses.create(
model="qwen3.8-max",
input="How does it differ from GBDT?",
previous_response_id=response1.id
)
print(f"Second reply: {response2.output_text}")
print(f"Cached tokens: {response2.usage.input_tokens_details.cached_tokens}")
- lang: javascript
label: Session cache
source: |-
import OpenAI from "openai";
const openai = new OpenAI({
apiKey: process.env.DASHSCOPE_API_KEY,
baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1",
defaultHeaders: { "x-dashscope-session-cache": "enable" }
});
const longContext = "Artificial intelligence is a major branch of computer science. ".repeat(80);
async function main() {
const response1 = await openai.responses.create({
model: "qwen3.8-max",
input: longContext + "\n\nBriefly introduce the Random Forest algorithm."
});
console.log(`First reply: ${response1.output_text}`);
const response2 = await openai.responses.create({
model: "qwen3.8-max",
input: "How does it differ from GBDT?",
previous_response_id: response1.id
});
console.log(`Second reply: ${response2.output_text}`);
console.log(`Cached tokens: ${response2.usage.input_tokens_details.cached_tokens}`);
}
main();
- lang: curl
label: Session cache
source: |-
# First turn (input must exceed 1024 tokens to trigger caching)
curl -X POST https://maas.qwencloudapi.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.8-max",
"input": "Artificial intelligence is a major branch of computer science... (repeat to exceed 1024 tokens)\n\nBriefly introduce the Random Forest algorithm."
}'
# Second turn - use previous_response_id
curl -X POST https://maas.qwencloudapi.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.8-max",
"input": "How does it differ from GBDT?",
"previous_response_id": "resp_id_from_first_turn"
}'
- lang: python
label: Function calling
source: |-
from openai import OpenAI
import json
import os
import random
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://maas.qwencloudapi.com/compatible-mode/v1",
)
tools = [
{
"type": "function",
"name": "get_current_weather",
"description": "Useful for getting the weather in a specific city.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city or district, such as Beijing or Hangzhou.",
}
},
"required": ["location"],
},
}
]
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}."
def get_response(input_data):
response = client.responses.create(
model="qwen3.8-max",
input=input_data,
tools=tools,
)
return response
conversation = [{"role": "user", "content": "What's the weather like in Beijing?"}]
response = get_response(conversation)
function_calls = [item for item in response.output if item.type == "function_call"]
if not function_calls:
print(f"Final response: {response.output_text}")
else:
while function_calls:
for fc in function_calls:
arguments = json.loads(fc.arguments)
print(f"Calling tool [{fc.name}] with arguments: {arguments}")
tool_result = get_current_weather(arguments)
print(f"Tool returned: {tool_result}")
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,
})
response = get_response(conversation)
function_calls = [item for item in response.output if item.type == "function_call"]
print(f"Final response: {response.output_text}")
- lang: javascript
label: Function calling
source: |-
import OpenAI from "openai";
const openai = new OpenAI({
apiKey: process.env.DASHSCOPE_API_KEY,
baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1",
});
const tools = [
{
type: "function",
name: "get_current_weather",
description: "Useful for getting the weather in a specific city.",
parameters: {
type: "object",
properties: {
location: {
type: "string",
description: "The city or district, such as Beijing or Hangzhou.",
},
},
required: ["location"],
},
},
];
const getCurrentWeather = (args) => {
const weatherConditions = ["sunny", "cloudy", "rainy"];
const randomWeather = weatherConditions[Math.floor(Math.random() * weatherConditions.length)];
return `Today in ${args.location} it is ${randomWeather}.`;
};
const getResponse = async (inputData) => {
return await openai.responses.create({
model: "qwen3.8-max",
input: inputData,
tools: tools,
});
};
async function main() {
const conversation = [{ role: "user", content: "What's the weather like in Beijing?" }];
let response = await getResponse(conversation);
let functionCalls = response.output.filter(item => item.type === "function_call");
if (functionCalls.length === 0) {
console.log(`Final response: ${response.output_text}`);
} else {
while (functionCalls.length > 0) {
for (const fc of functionCalls) {
const args = JSON.parse(fc.arguments);
console.log(`Calling tool [${fc.name}] with arguments:`, args);
const toolResult = getCurrentWeather(args);
console.log(`Tool returned: ${toolResult}`);
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 });
}
response = await getResponse(conversation);
functionCalls = response.output.filter(item => item.type === "function_call");
}
console.log(`Final response: ${response.output_text}`);
}
}
main().catch(console.error);
- lang: python
label: Document understanding
source: |-
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://maas.qwencloudapi.com/compatible-mode/v1",
)
response = client.responses.create(
model="qwen3.5-ocr",
input=[
{
"role": "user",
"content": [
{
"type": "input_file",
"file_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf",
},
{
"type": "input_text",
"text": "Read all the text in the file.",
},
],
}
],
extra_body={
"ocr_options": {}
},
)
print(response.output_text)
- lang: javascript
label: Document understanding
source: |-
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.DASHSCOPE_API_KEY,
baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1",
});
async function main() {
const response = await client.responses.create({
model: "qwen3.5-ocr",
input: [{
role: "user",
content: [{
type: "input_file",
file_url: "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf"
}]
}],
ocr_options: {}
});
console.log(response.output_text);
}
main();
- lang: curl
label: Document understanding
source: |-
curl -X POST https://maas.qwencloudapi.com/compatible-mode/v1/responses \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.5-ocr",
"input": [
{
"role": "user",
"content": [
{
"type": "input_file",
"file_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf"
},
{
"type": "input_text",
"text": "Read all the text in the file."
}
]
}
],
"ocr_options": {}
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: DashScope API key.
schemas:
ResponsesRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: |-
The model name. Supported models include qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash, qwen3.7-max, qwen3.7-max-2026-06-08, qwen3.7-max-2026-05-20, qwen3.7-max-2026-05-17, qwen3.7-max-preview, qwen3.7-max, qwen3.7-max, qwen3.7-plus, qwen3.7-plus-2026-05-26, qwen3.6-plus, qwen3.6-plus-2026-04-02, qwen3.8-2.4t-a95b, qwen3.8-27b, qwen3.8-omni-flash, qwen3.6-35b-a3b, 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.5-397b-a17b, qwen3.5-122b-a10b, qwen3.5-27b, qwen3.5-35b-a3b, deepseek-v4.1-flash, deepseek-v4-pro-0813, deepseek-v4-pro, deepseek-v4-flash-0731, deepseek-v4-flash-0731, glm-5.3, glm-5.2, and kimi-k3.
Other Alibaba Cloud Model Studio text generation models not listed above only support basic compatibility. Agent capabilities (such as built-in tools) are limited.
input:
oneOf:
- title: Plain text
type: string
description: Plain text input, for example "Hello".
- title: Message array
type: array
description: An array of messages in conversation order.
items:
$ref: "#/components/schemas/InputMessage"
description: The input content for the model. Supports a plain text string or an array of messages in conversation order.
instructions:
type: string
description: A system instruction inserted at the beginning of the context. When `previous_response_id` is used, the instructions specified in the previous turn are not carried over to the current context.
previous_response_id:
type: string
description: The unique ID of the previous response. The current response id is valid for 7 days. You can use this parameter to create a multi-turn conversation. The server automatically retrieves and combines the input and output of that turn as context. If both an input message array and `previous_response_id` are provided, the new messages in input are appended to the historical context. Cannot be used together with `conversation`. For usage examples, see the [Multi-turn conversations guide](/developer-guides/text-generation/multi-turn).
conversation:
type: string
description: The conversation to which the current response belongs. Historical items in the conversation are automatically passed as context to the current request. The input and output of the current request are also automatically added to the conversation after the response completes. Cannot be used together with `previous_response_id`.
stream:
type: boolean
default: false
description: Specifies whether to enable streaming output. If this parameter is set to `true`, the model response data is streamed back to the client in real time.
store:
type: boolean
default: true
description: |-
Specifies whether to store the model response generated for this session.
- `true`: The response is stored. The current model response can be referenced by `previous_response_id` and subsequent API calls.
- `false`: The response is not stored and cannot be referenced in subsequent calls via `previous_response_id`.
tools:
type: array
description: |-
A list of tools the model can use. Supported tool types: `web_search`, `code_interpreter`, `web_extractor`, `web_search_image`, `image_search`, `file_search`, `mcp`, `function`.
For `qwen3.8-omni-flash`, the only supported built-in tool is `web_search`. Custom `function` tools are also supported.
**Built-in tools** use `{"type": "<tool_name>"}` format. For example: `{"type": "web_search"}`.
**MCP tools** use the following format:
```JSON
{
"tipo": "mcp",
"server_protocol": "sse",
"server_label": "mapas-amap",
"server_description": "Servidor AMAP MCP...",
"URL_do_servidor": "https://maas.qwencloudapi.com/api/v1/mcps/amap-maps/sse",
"cabeçalhos": {
"Autorização": "Portador $DASHSCOPE_API_KEY"
}
}
```
**Function tools** use the following format:
```JSON
[{
"tipo": "função",
"nome": "get_weather",
"description": "Obter informações meteorológicas para uma cidade específica",
"parâmetros": {
"tipo": "objeto",
"propriedades": {
"cidade": {
"tipo": "string",
"descrição": "O nome da cidade"
}
},
"obrigatório": ["cidade"]
}
}]
``` For usage examples, see the [Function calling guide](/developer-guides/text-generation/function-calling) and the [Web search guide](/developer-guides/text-generation/web-search).
items:
type: object
required:
- type
properties:
type:
type: string
enum:
- web_search
- code_interpreter
- web_extractor
- web_search_image
- image_search
- file_search
- mcp
- function
description: The tool type.
vector_store_ids:
type: array
items:
type: string
description: The knowledge base IDs to search. Required when `type` is `file_search`. **Currently only one knowledge base ID is supported**.
server_protocol:
type: string
description: The communication protocol with the MCP service, such as `"sse"`. Required when `type` is `mcp`.
server_label:
type: string
description: The service label that identifies the MCP service. Required when `type` is `mcp`.
server_description:
type: string
description: A description of the service to help the model understand its functionality. Optional when `type` is `mcp`.
server_url:
type: string
description: The URL of the MCP service endpoint. Required when `type` is `mcp`.
headers:
type: object
description: Request headers for authentication and other information. Optional when `type` is `mcp`.
additionalProperties:
type: string
name:
type: string
description: The tool name. Only letters, digits, underscores, and hyphens allowed, max 64 tokens. Required when `type` is `function`.
description:
type: string
description: A description of the tool to help the model determine when and how to use it. Required when `type` is `function`.
parameters:
type: object
description: The parameter description of the tool, must be a valid JSON Schema. Optional when `type` is `function`. Empty means the tool has no parameters.
tool_choice:
description: |-
Controls how the model selects and calls tools. Supports string format and object format.
**String format:**
- `auto`: The model automatically decides whether to call a tool.
- `none`: Prevents the model from calling any tool.
- `required`: Forces the model to call a tool. Available only when there is a single tool in the tools list.
**Object format:** Specifies the range of available tools for the model. The model can select and call tools only from the predefined list.
oneOf:
- type: string
enum:
- auto
- none
- required
default: auto
- type: object
properties:
mode:
type: string
enum:
- auto
- required
description: "`auto`: The model automatically decides whether to call a tool. `required`: Forces the model to call a tool."
tools:
type: array
description: 'A list of tool definitions that the model is allowed to call. Example: `[{"type": "function", "name": "get_weather"}]`'
items:
type: object
properties:
type:
type: string
description: The type of the tool.
name:
type: string
description: The name of the tool.
type:
type: string
enum:
- allowed_tools
description: The type of allowed tool configuration. The value must be `allowed_tools`.
temperature:
type: number
description: "The sampling temperature that controls the diversity of the generated text. A higher temperature results in more diverse text. A lower temperature results in more deterministic text. Value range: [0, 2). Both `temperature` and `top_p` control the diversity of the generated text. We recommend that you set only one of them."
top_p:
type: number
description: "The probability threshold for nucleus sampling that controls the diversity of the generated text. A higher `top_p` value results in more diverse text. A lower `top_p` value results in more deterministic text. Value range: (0, 1.0]. Both `temperature` and `top_p` control the diversity of the generated text. We recommend that you set only one of them."
enable_thinking:
type: boolean
description: |-
Specifies whether to enable thinking mode. If set to `true`, the model thinks before replying. The thinking content is returned through an output item of the `reasoning` type. Reasoning tokens are counted in `output_tokens_details.reasoning_tokens` and are billed as reasoning tokens. When thinking mode is enabled, we recommend enabling the built-in tools to achieve the best model performance on complex tasks.
**This is not a standard OpenAI parameter.** The Python SDK passes it using `extra_body={"enable_thinking": True}`. The Node.js SDK and curl use `enable_thinking: true` directly as a top-level parameter. We recommend using `reasoning.effort` instead, as `enable_thinking` will be deprecated.
reasoning:
type: object
description: 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`. `reasoning.effort` takes precedence over `enable_thinking`. We recommend using `reasoning.effort`, as `enable_thinking` will be deprecated.
properties:
effort:
type: string
default: xhigh
enum:
- none
- minimal
- low
- medium
- high
- xhigh
- max
description: |-
The level of reasoning effort.
Supports 7 incremental levels: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Lowering this value accelerates the response and reduces inference token consumption.
- **Qwen3.8 series**: default `xhigh`, supports `none`, `low`, `medium`, `xhigh`; `minimal` maps to `low`, `high` and `max` map to `xhigh`.
- **`deepseek-v4-flash-0731`, `deepseek-v4-pro-0813`**: default `high`, supports `none`, `low`, `high`, `max`; `minimal` maps to `low`, `medium` maps to `high`, `xhigh` maps to `max`.
- **`deepseek-v4.1-flash`**: default `high`, supports `none`, `low`, `high`, `max`; `minimal` maps to `low`, `medium` and `xhigh` map to `high`, passing `ultra` returns an error.
- **`glm-5.3`**: default `max`, supports `low`, `high`, `max`; `minimal` maps to `low`, `medium` maps to `high`, `xhigh` maps to `max`.
- **`glm-5.2`, `deepseek-v4-pro`, `deepseek-v4-flash-0731`**: default `high`, supports `none`, `high`, `max`; `minimal`, `low`, and `medium` map to `high`, `xhigh` maps to `max`.
For `glm-5.3`, we recommend using `max`.
max_output_tokens:
type: integer
minimum: 16
description: |-
The maximum number of output tokens. Minimum value is 16.
- **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.
If the model output exceeds this value, generation stops early and the status is `incomplete`.
ocr_options:
type: object
description: |-
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 is not a standard OpenAI parameter.** The Python SDK passes it using `extra_body={"ocr_options": {...}}`. The Node.js SDK and curl use `ocr_options` directly as a top-level parameter.
InputMessage:
oneOf:
- $ref: "#/components/schemas/SystemMessage"
- $ref: "#/components/schemas/DeveloperMessage"
- $ref: "#/components/schemas/UserMessage"
- $ref: "#/components/schemas/AssistantMessage"
- $ref: "#/components/schemas/ResponseOutputMessage"
- $ref: "#/components/schemas/FunctionCallInput"
- $ref: "#/components/schemas/FunctionCallOutputInput"
- $ref: "#/components/schemas/ReasoningInput"
- $ref: "#/components/schemas/WebSearchCallInput"
SystemMessage:
title: System message
type: object
description: A system message that sets the behavior and role of the model.
required:
- role
- content
properties:
role:
type: string
enum:
- system
description: The role of the message. The value must be `system`.
content:
oneOf:
- type: string
description: Plain text content.
- type: array
description: An array of content parts.
items:
type: object
required:
- type
properties:
type:
type: string
enum:
- input_text
description: The content type. Fixed as `input_text`.
text:
type: string
description: The text content.
description: The message content. Supports a string or an array of content parts.
type:
type: string
enum:
- message
description: Fixed as `message`. Optional field.
DeveloperMessage:
title: Developer message
type: object
description: A developer message that provides system-level instructions.
required:
- role
- content
properties:
role:
type: string
enum:
- developer
description: The role of the message. The value must be `developer`.
content:
oneOf:
- type: string
description: Plain text content.
- type: array
description: An array of content parts.
items:
type: object
required:
- type
properties:
type:
type: string
enum:
- input_text
description: The content type. Fixed as `input_text`.
text:
type: string
description: The text content.
description: The message content. Supports a string or an array of content parts.
type:
type: string
enum:
- message
description: Fixed as `message`. Optional field.
UserMessage:
title: User message
type: object
description: A user message that passes questions, instructions, or context to the model.
required:
- role
- content
properties:
role:
type: string
enum:
- user
description: The role of the message. The value must be `user`.
content:
oneOf:
- type: string
description: Plain text content.
- type: array
description: An array of content parts for multimodal input. `qwen3.8-omni-flash` also supports `input_audio` and `input_video`.
items:
type: object
required:
- type
properties:
type:
type: string
enum:
- input_text
- input_image
- input_file
- output_text
- input_audio
- input_video
description: The content type. `input_text` for text input, `input_image` for image input (user role only), `input_file` for file input (user role only, supports PDF and images), `output_text` for assistant replies (assistant role only). For `qwen3.8-omni-flash` user messages, `input_audio` and `input_video` are also supported.
text:
type: string
description: The text content. Required when `type` is `input_text` or `output_text`.
image_url:
type: string
description: "Supports 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,iVBORw0K...`."
file_url:
type: string
description: The public URL of the file. Required when `type` is `input_file`. Supports PDF files (max 10 pages, 100 MB) and image files (max 20 MB). Currently only `qwen3.5-ocr` supports this type.
format:
type: string
description: "The audio format. Required when `type` is `input_audio`. For example: `wav` or `mp3`."
audio_url:
type: string
description: The audio URL. Use either `audio_url` or `data` for `input_audio` type. Do not provide both.
data:
type: string
description: A complete data URI containing a MIME type prefix and Base64-encoded audio, such as `data:audio/wav;base64,UklGR...`. Use either `data` or `audio_url` for `input_audio` type. Do not provide both.
video_url:
type: string
description: The video URL. Required when `type` is `input_video`.
fps:
type: number
description: An optional parameter of type `number` that specifies how many frames to sample per second. For example, `2` samples 2 frames per second. Do not pass it as a string.
description: The content of the message. The data type is string if the input contains only text. It is an array if the input contains images, files, or if explicit caching is enabled.
type:
type: string
enum:
- message
description: Fixed as `message`. Optional field.
AssistantMessage:
title: Assistant message
type: object
description: An assistant message that conveys the model's previous replies.
required:
- role
- content
properties:
role:
type: string
enum:
- assistant
description: The role of the message. The value must be `assistant`.
content:
oneOf:
- type: string
description: Plain text content.
- type: array
description: An array of content parts.
items:
type: object
required:
- type
properties:
type:
type: string
enum:
- output_text
description: The content type. Fixed as `output_text`.
text:
type: string
description: The reply text.
description: The message content. Supports a string or an array of content parts.
type:
type: string
enum:
- message
description: Fixed as `message`. Optional field.
WebSearchCallInput:
title: Web search call
type: object
description: 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.
required:
- type
- id
- status
- action
properties:
type:
type: string
const: web_search_call
description: Always `web_search_call`.
id:
type: string
description: The unique identifier of the search call, from the previous response.
status:
type: string
enum:
- in_progress
- searching
- completed
- failed
description: The search status.
action:
type: object
description: The search action details. Only the `search` type is supported.
required:
- type
properties:
type:
type: string
const: search
description: The search type. Always `search`.
queries:
type: array
items:
type: string
description: A list of search queries.
sources:
type: array
description: A list of search result sources.
items:
type: object
required:
- type
- url
properties:
type:
type: string
const: url
description: The source type. Always `url`.
url:
type: string
description: The source URL.
ResponseObject:
type: object
description: Response object (non-streaming output).
properties:
id:
type: string
description: The unique ID for this response. It is valid for 7 days. You can use this parameter in the `previous_response_id` parameter to create a multi-turn conversation.
created_at:
type: number
description: The Unix timestamp in seconds for this request.
object:
type: string
enum:
- response
description: The object type. The value is `response`.
status:
type: string
enum:
- completed
- failed
- in_progress
- cancelled
- queued
- incomplete
description: The status of the response generation.
model:
type: string
description: The ID of the model that is used to generate the response.
output:
type: array
description: An array of output items generated by the model. The type and order of elements in the array depend on the model's response.
items:
$ref: "#/components/schemas/OutputItem"
parallel_tool_calls:
type: boolean
description: Whether parallel tool calls are enabled.
tool_choice:
type: string
description: The value of the `tool_choice` parameter from the echo request. Valid values are `auto`, `none`, and `required`.
tools:
type: array
description: The complete content of the tools parameter from the echo request. The structure is the same as the tools parameter in the request body.
items:
type: object
error:
type: object
nullable: true
description: The error object that is returned when the model fails to generate a response. This field is `null` on success.
properties:
code:
type: string
description: The error code.
message:
type: string
description: A human-readable error message.
usage:
$ref: "#/components/schemas/Usage"
OutputItem:
type: object
description: An output item generated by the model.
properties:
type:
type: string
enum:
- message
- reasoning
- function_call
- web_search_call
- code_interpreter_call
- web_extractor_call
- web_search_image_call
- image_search_call
- mcp_call
- file_search_call
description: |-
The type of the output item.
- `message`: Contains the final reply content generated by the model.
- `reasoning`: Returned when thinking mode (`enable_thinking: true`) is enabled. Reasoning tokens are counted in `output_tokens_details.reasoning_tokens` and are billed as reasoning tokens.
- `function_call`: Returned when a user-defined function tool is used. You need to handle the function call and return the result.
- `web_search_call`: Returned when the `web_search` tool is used.
- `code_interpreter_call`: Returned when the `code_interpreter` tool is used.
- `web_extractor_call`: Returned when the `web_extractor` tool is used. It must be used with the `web_search` tool.
- `web_search_image_call`: Returned when the `web_search_image` tool is used. It contains a list of searched images.
- `image_search_call`: Returned when the `image_search` tool is used. It contains a list of similar images.
- `mcp_call`: Returned when the `mcp` tool is used. It contains the result of the MCP service call.
- `file_search_call`: Returned when the `file_search` tool is used. It contains the search query and results from the knowledge base.
id:
type: string
description: The unique identifier for the output item. This field is included in all types of output items.
role:
type: string
enum:
- assistant
description: The role of the message. The value is `assistant`. This field exists only when the type is `message`.
status:
type: string
enum:
- completed
- in_progress
description: The status of the output item.
name:
type: string
description: The tool or function name. This field exists when the 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 as `web_search_image` and `image_search`, respectively. For `mcp_call`, the value is the specific function name called in the MCP service, such as `amap-maps-maps_geo`.
arguments:
type: string
description: |-
The arguments for the tool call, in JSON string format. This field exists when the type is `function_call`, `web_search_image_call`, `image_search_call`, or `mcp_call`. You need to parse it using `JSON.parse()` before use.
**Arguments content by tool type:**
- `web_search_image_call`: `{"queries": ["search term 1", "search term 2"]}`, where queries is a list of search terms auto-generated by the model.
- `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, with a range of 0-1000.
- `function_call`: An argument object generated according to the schema of the user-defined function parameters.
- `mcp_call`: An argument object for the function called in the MCP service.
call_id:
type: string
description: The unique identifier for the function call. This field exists only when the type is `function_call`. When returning the function call result, you must use this ID to associate the request with the response.
content:
type: array
description: An array of message content. This field exists only when the type is `message`.
items:
type: object
properties:
type:
type: string
enum:
- output_text
description: The content type. The value is `output_text`.
text:
type: string
description: The text content that is generated by the model.
annotations:
type: array
description: An array of text annotations. This is usually an empty array.
items:
type: object
summary:
type: array
description: An array of reasoning summaries. This field exists only when the type is `reasoning`. Each element contains a `type` field with a value of `summary_text` and a `text` field that contains the summary text.
items:
type: object
properties:
type:
type: string
enum:
- summary_text
text:
type: string
action:
type: object
description: The search action information. This field exists only when the type is `web_search_call`.
properties:
query:
type: string
description: The search query keyword.
type:
type: string
enum:
- search
description: The search type. The value is `search`.
sources:
type: array
description: A list of search sources. Each element contains a `type` field and a `url` field.
items:
type: object
properties:
type:
type: string
url:
type: string
code:
type: string
description: The code that is generated and executed by the model. This field exists only when the type is `code_interpreter_call`.
outputs:
type: array
description: An array of code execution outputs. This field exists only when the type is `code_interpreter_call`. Each element contains a `type` field with a value of `logs` and a `logs` field that contains the code execution log.
items:
type: object
properties:
type:
type: string
enum:
- logs
logs:
type: string
container_id:
type: string
description: The identifier for the code interpreter container. This field exists only when the type is `code_interpreter_call`. It is used to associate multiple code executions within the same session.
goal:
type: string
description: A description of the extraction goal that explains what information needs to be extracted from the web page. This field exists only when the type is `web_extractor_call`.
output:
type: string
description: |-
The output result of the tool call, in string format.
- When type is `web_extractor_call`, this is the summary of the extracted web content.
- When type is `web_search_image_call` or `image_search_call`, this is a JSON string containing an array of image search results. Each element contains a `title` field (image title), a `url` field (image URL), and an `index` field (sequence number).
- When type is `mcp_call`, this is the JSON string result returned by the MCP service.
urls:
type: array
description: A list of URLs of the extracted web pages. This field exists only when the type is `web_extractor_call`.
items:
type: string
server_label:
type: string
description: The MCP service label. This field exists only when the type is `mcp_call`. It identifies the MCP service used for this call.
queries:
type: array
description: The list of queries used for knowledge base retrieval. This field exists only when the type is `file_search_call`. Array elements are strings representing search queries generated by the model.
items:
type: string
results:
type: array
description: An array of knowledge base retrieval results. This field exists only when the type is `file_search_call`.
items:
type: object
properties:
file_id:
type: string
description: The file ID of the matching document.
filename:
type: string
description: The filename of the matching document.
score:
type: number
description: The relevance score of the match, ranging from 0 to 1. A higher value indicates greater relevance.
text:
type: string
description: A snippet of the matched document content.
ResponseChunk:
type: object
description: Response chunk object (streaming output). Streaming output returns a series of JSON objects. Each object includes a `type` field to identify the event type and a `sequence_number` field to indicate the event order. The `response.completed` event marks the end of the stream.
properties:
type:
type: string
enum:
- response.created
- response.in_progress
- response.output_item.added
- response.content_part.added
- response.output_text.delta
- response.output_text.done
- response.content_part.done
- response.output_item.done
- response.reasoning_text.delta
- response.reasoning_text.done
- response.web_search_call.in_progress
- response.web_search_call.searching
- response.web_search_call.completed
- response.code_interpreter_call.in_progress
- response.code_interpreter_call.interpreting
- response.code_interpreter_call.completed
- response.mcp_call.in_progress
- response.mcp_call_arguments.delta
- response.mcp_call_arguments.done
- response.mcp_call.completed
- response.custom_tool_call_input.delta
- response.custom_tool_call_input.done
- response.file_search_call.in_progress
- response.file_search_call.searching
- response.file_search_call.completed
- response.completed
- response.incomplete
description: |-
The event type identifier.
- `response.created`: Triggered when the response is created. The status is `queued`.
- `response.in_progress`: Triggered when response processing begins. The status changes to `in_progress`.
- `response.output_item.added`: Triggered when a new output item is added to the output array. If the `item.type` is `web_extractor_call`, this indicates that the web extractor tool call has started.
- `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 for incremental text generation. This event is triggered multiple times, 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 a content block is complete.
- `response.output_item.done`: Triggered when an output item is completely generated. If the `item.type` is `web_extractor_call`, this indicates that the web extractor tool call is complete.
- `response.reasoning_text.delta`: (If thinking mode is enabled) Incremental text for the reasoning content.
- `response.reasoning_text.done`: (If thinking mode is enabled) The reasoning content is complete.
- `response.web_search_call.in_progress` / `searching` / `completed`: (If using `web_search` tool) Search status change events.
- `response.code_interpreter_call.in_progress` / `interpreting` / `completed`: (If using `code_interpreter` tool) Code execution status change events.
- `response.mcp_call.in_progress`: (If using `mcp` tool) The MCP service call has started.
- `response.mcp_call_arguments.delta` / `response.mcp_call_arguments.done`: (If using `mcp` tool) Incremental and completion events for MCP call arguments.
- `response.mcp_call.completed`: (If using `mcp` tool) MCP service call completed.
- `response.custom_tool_call_input.delta` / `response.custom_tool_call_input.done`: (If using a custom tool) Incremental and completion events for the tool input.
- `response.file_search_call.in_progress` / `searching` / `completed`: (If using `file_search` tool) Knowledge base search status change events.
- `response.completed`: Triggered when response generation is complete. The response object contains the complete response, including usage information. This event marks the end of the stream.
- `response.incomplete`: Triggered when the response ends early due to a limit such as `max_output_tokens`.
**Note:** If you use the `web_extractor` tool, there is no dedicated event type identifier. The web extractor tool call is communicated through the general `response.output_item.added` and `response.output_item.done` events, identified by the `item.type` field which has a value of `web_extractor_call`.
**Note:** If you use the `web_search_image` or `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 completion) events.
sequence_number:
type: integer
description: The event serial number. It starts from 0 and increments. You can use it to ensure that the client processes events in the correct order.
response:
type: object
description: The response object. It appears in the `response.created`, `response.in_progress`, `response.completed`, and `response.incomplete` events. In the `response.completed` and `response.incomplete` events, it contains the complete response data, including output and usage. Its structure is consistent with the response object of a non-streaming response.
item:
type: object
description: The output item object. It appears in the `response.output_item.added` and `response.output_item.done` events. In an added event, it is an initial skeleton where the content is an empty array. In a done event, it is a complete object.
properties:
id:
type: string
description: The unique identifier for the output item, such as `msg_xxx`.
type:
type: string
enum:
- message
- reasoning
- web_search_call
- web_search_image_call
- image_search_call
- mcp_call
- file_search_call
description: The type of the output item.
role:
type: string
enum:
- assistant
description: The role of the message. The value is `assistant`. This field exists only when the type is `message`.
status:
type: string
enum:
- in_progress
- completed
description: The generation status. In an added event, the status is `in_progress`. In a done event, the status is `completed`.
content:
type: array
description: An array of message content. In an added event, it is an empty array `[]`. In a done event, it contains complete content block objects that have the same structure as the `part` object.
items:
type: object
part:
type: object
description: The content block object. It appears in the `response.content_part.added` and `response.content_part.done` events.
properties:
type:
type: string
enum:
- output_text
description: The content block type. The value is `output_text`.
text:
type: string
description: The text content. In an added event, it is an empty string. In a done event, it is the complete text.
annotations:
type: array
description: An array of text annotations. This is usually an empty array.
items:
type: object
logprobs:
type: object
nullable: true
description: The log probability information for tokens. Currently, this is `null`.
delta:
type: string
description: The incremental text content. It appears in the `response.output_text.delta` event and contains the new text fragment. The client should concatenate all delta fragments to obtain the complete text.
text:
type: string
description: The complete text content. It appears in the `response.output_text.done` event and contains the complete text of the content block. You can use it to verify the concatenated delta result.
item_id:
type: string
description: The unique identifier for the output item. It is used to associate related events for the same output item.
output_index:
type: integer
description: The index position of the output item in the output array.
content_index:
type: integer
description: The index position of the content block in the content array.
Usage:
type: object
description: The token consumption information for this request.
properties:
input_tokens:
type: integer
description: The number of input tokens.
output_tokens:
type: integer
description: The number of tokens that are output by the model.
total_tokens:
type: integer
description: The total number of tokens consumed. This is the sum of `input_tokens` and `output_tokens`.
input_tokens_details:
type: object
description: The fine-grained categorization of input tokens.
properties:
cached_tokens:
type: integer
description: The number of tokens that hit the cache.
output_tokens_details:
type: object
description: The fine-grained categorization of output tokens.
properties:
reasoning_tokens:
type: integer
description: The number of tokens in the thinking process.
x_details:
type: array
description: Detailed token breakdown by billing type.
items:
type: object
properties:
input_tokens:
type: integer
description: The number of input tokens.
output_tokens:
type: integer
description: The number of tokens output by the model.
total_tokens:
type: integer
description: The total number of tokens consumed, the sum of input_tokens and output_tokens.
x_billing_type:
type: string
description: Fixed as `response_api`.
image_tokens:
type: integer
description: The number of image input tokens. Returned when image input is included, equivalent to `input_tokens_details.image_tokens`.
input_tokens_details:
type: object
description: Fine-grained classification and cache details of input tokens. Returned for multimodal input or when Session cache is enabled.
properties:
text_tokens:
type: integer
description: The number of text input tokens.
image_tokens:
type: integer
description: The number of image input tokens.
cached_tokens:
type: integer
description: The number of cache-hit tokens.
cache_creation_input_tokens:
type: integer
description: The number of tokens for which a new cache entry was created in this request.
cache_creation:
type: object
description: Cache creation details.
properties:
ephemeral_5m_input_tokens:
type: integer
description: The number of tokens created for the 5-minute ephemeral cache.
cache_type:
type: string
description: The cache type. Fixed as `ephemeral`.
output_tokens_details:
type: object
description: Fine-grained classification of output tokens. Returned for multimodal input.
properties:
reasoning_tokens:
type: integer
description: The number of reasoning process tokens.
text_tokens:
type: integer
description: The number of text output tokens. Returned for multimodal input.
plugins:
type: object
description: Built-in tool call statistics. Returned when built-in tools (such as `web_search`) are used, same as the top-level `x_tools` field.
properties:
web_search:
type: object
description: Web search call statistics.
properties:
count:
type: integer
description: The number of web search calls in this response.
x_tools:
type: object
description: 'Statistical information about tool usage. If built-in tools are used, this field includes the number of calls for each tool. Example: `{"web_search": {"count": 1}}`'
ErrorResponse:
type: object
properties:
request_id:
type: string
description: The unique request ID for tracing and debugging.
code:
type: string
description: The error code.
message:
type: string
description: A human-readable error message.
ResponseOutputMessage:
title: Response output message
type: object
description: A model output message object. You can pass the message items from a previous response's output directly back into input for multi-turn conversations.
required:
- type
- id
- role
- status
- content
properties:
type:
type: string
enum:
- message
description: Fixed as `message`.
id:
type: string
description: The unique identifier of the output message, from the previous response.
role:
type: string
enum:
- assistant
description: Fixed as `assistant`.
status:
type: string
enum:
- in_progress
- completed
- incomplete
description: The message status.
content:
type: array
description: Content array with output_text type elements.
items:
type: object
required:
- type
- text
properties:
type:
type: string
enum:
- output_text
description: Fixed as `output_text`.
text:
type: string
description: The reply text.
annotations:
type: array
description: Annotation information.
items:
type: object
FunctionCallInput:
title: Function call
type: object
description: A structured instruction generated when the model decides to call an external tool. You can pass function_call items from a previous response's output back into input.
required:
- type
- name
- arguments
- call_id
properties:
type:
type: string
enum:
- function_call
description: Fixed as `function_call`.
id:
type: string
description: The unique identifier of the function call, from the previous response.
name:
type: string
description: The tool function name.
arguments:
type: string
description: The tool call arguments in JSON string format.
call_id:
type: string
description: The identifier of the tool call. Must match the `call_id` returned by the model.
status:
type: string
enum:
- in_progress
- completed
- incomplete
description: The status.
FunctionCallOutputInput:
title: Function call output
type: object
description: The output result of a tool call. Must immediately follow the corresponding `function_call` message in the message list.
required:
- type
- call_id
- output
properties:
type:
type: string
enum:
- function_call_output
description: Fixed as `function_call_output`.
id:
type: string
description: The unique identifier of the function call output.
call_id:
type: string
description: The identifier of the tool call. Must match the `call_id` returned by the model.
output:
type: string
description: The execution result of the tool function.
status:
type: string
enum:
- in_progress
- completed
- incomplete
description: The status.
ReasoningInput:
title: Reasoning
type: object
description: The model's reasoning content. You can pass reasoning items from a previous response's output back into input for multi-turn conversations.
required:
- type
- id
- summary
properties:
type:
type: string
enum:
- reasoning
description: Fixed as `reasoning`.
id:
type: string
description: The unique identifier of the reasoning content, from the previous response.
summary:
type: array
description: The reasoning summary content.
items:
type: object
required:
- type
- text
properties:
type:
type: string
enum:
- summary_text
description: Fixed as `summary_text`.
text:
type: string
description: The summary text.
status:
type: string
enum:
- in_progress
- completed
- incomplete
description: The status.