> ## Documentation Index > Fetch the complete documentation index at: https://docs.qwencloud.com/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI chat > Compatible Chat API `qwen4-max-preview` ([Token Plan only](/token-plan/overview)) is available through Token Plan only. Use a Token Plan API key and Base URL. The pay-as-you-go examples below continue to use existing models. ## OpenAPI ````yaml post /compatible-mode/v1/chat/completions openapi: 3.1.0 info: title: Qwen OpenAI-compatible Chat API description: Call Qwen models using the OpenAI-compatible Chat API. Supports text and multimodal models, streaming, tool calls, and structured output. version: 1.0.0 servers: - url: https://ap-southeast-1.maas.qwencloudapi.com description: Singapore (ap-southeast-1). API keys are region-specific. - url: https://cn-beijing.maas.qwencloudapi.com description: China North 2 (Beijing) (cn-beijing). API keys are region-specific. - url: https://eu-central-1.maas.qwencloudapi.com description: Germany (Frankfurt) (eu-central-1). API keys are region-specific. - url: https://cn-hongkong.maas.qwencloudapi.com description: China (Hong Kong) (cn-hongkong). API keys are region-specific. - url: https://ap-northeast-1.maas.qwencloudapi.com description: Japan (Tokyo) (ap-northeast-1). API keys are region-specific. - url: https://us-east-1.maas.qwencloudapi.com description: US (Virginia) (us-east-1). API keys are region-specific. security: - BearerAuth: [] paths: /compatible-mode/v1/chat/completions: post: operationId: openaiChatCompletions summary: Chat completions description: Send messages to a Qwen model and receive a generated reply using the OpenAI-compatible API. Supports multi-turn chat, streaming, tool calls, structured output, thinking mode, and multimodal input (images, video, audio). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ChatCompletionRequest" example: model: qwen3.8-max messages: - role: system content: You are a helpful assistant. - role: user content: Who are you? responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ChatCompletion" example: choices: - message: role: assistant content: I am a large-scale language model developed by Alibaba Cloud. My name is Qwen. finish_reason: stop index: 0 logprobs: null object: chat.completion usage: prompt_tokens: 3019 completion_tokens: 104 total_tokens: 3123 prompt_tokens_details: cached_tokens: 2048 created: 1735120033 system_fingerprint: null model: qwen3.8-max id: chatcmpl-6ada9ed2-7f33-9de2-8bb0-78bd4035025a text/event-stream: schema: $ref: "#/components/schemas/ChatCompletionChunk" example: id: chatcmpl-9b4f5e3a-5b7d-4c8e-a1f2-3d6e7f8a9b0c choices: - delta: content: "" function_call: null refusal: null role: assistant tool_calls: null finish_reason: null index: 0 logprobs: null created: 1735120033 model: qwen3.8-max system_fingerprint: null object: chat.completion.chunk usage: null "400": description: Invalid request parameters content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: message: you must provide a model parameter. type: invalid_request_error param: null code: null "401": description: Authentication failed content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: message: Incorrect API key provided. type: invalid_request_error param: null code: invalid_api_key "429": description: Rate limit exceeded content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: message: You have exceeded your current request limit. type: limit_requests param: null code: limit_requests x-codeSamples: - lang: python label: Text input source: |- import os from openai import OpenAI client = OpenAI( # If the environment variable is not set, replace the following line with:api_key="sk-xxx" api_key=os.getenv("DASHSCOPE_API_KEY"), # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL. # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions base_url="https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1", ) completion = client.chat.completions.create( model="qwen3.8-max", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Who are you?"}, ], # extra_body={"enable_thinking": False}, ) print(completion.model_dump_json()) - lang: java label: Text input source: |- // This code uses OpenAI SDK version 2.6.0 import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.chat.completions.ChatCompletion; import com.openai.models.chat.completions.ChatCompletionCreateParams; public class Main { public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.builder() .apiKey(System.getenv("DASHSCOPE_API_KEY")) // Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL. // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions .baseUrl("https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1") .build(); ChatCompletionCreateParams params = ChatCompletionCreateParams.builder() .addUserMessage("Who are you?") .model("qwen3.8-max") .build(); try { ChatCompletion chatCompletion = client.chat().completions().create(params); System.out.println(chatCompletion); } catch (Exception e) { System.err.println("Error occurred: " + e.getMessage()); e.printStackTrace(); } } } - lang: javascript label: Text input source: |- import OpenAI from "openai"; const openai = new OpenAI( { // If the environment variable is not set, replace the following line with:apiKey: "sk-xxx", apiKey:process.env.DASHSCOPE_API_KEY, // Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL. // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions baseURL: "https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1" } ); async function main() { const completion = await openai.chat.completions.create({ model: "qwen3.8-max", messages: [ { role: "system", content: "You are a helpful assistant." }, { role: "user", content: "Who are you?" } ], }); console.log(JSON.stringify(completion)) } main(); - lang: go label: Text input source: |- package main import ( "context" "os" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey(os.Getenv("DASHSCOPE_API_KEY")), // defaults to os.LookupEnv("OPENAI_API_KEY") // Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL. // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions option.WithBaseURL("https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/"), ) chatCompletion, err := client.Chat.Completions.New( context.TODO(), openai.ChatCompletionNewParams{ Messages:openai.F( []openai.ChatCompletionMessageParamUnion{ openai.UserMessage("Who are you?"), }, ), Model:openai.F("qwen3.8-max"), }, ) if err != nil { panic(err.Error()) } println(chatCompletion.Choices[0].Message.Content) } - lang: csharp label: Text input source: |- using System.Net.Http.Headers; using System.Text; class Program { private static readonly HttpClient httpClient = new HttpClient(); static async Task Main(string[] args) { // If the environment variable is not set, replace the following line with:string? apiKey = "sk-xxx"; string? apiKey = Environment.GetEnvironmentVariable("DASHSCOPE_API_KEY"); if (string.IsNullOrEmpty(apiKey)) { Console.WriteLine("API Key is not set. Make sure the 'DASHSCOPE_API_KEY' environment variable is set."); return; } // Set the request URL and content // Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL. // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions string url = "https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/chat/completions"; string jsonContent = @"{ ""model"": ""qwen3.8-max"", ""messages"": [ { ""role"": ""system"", ""content"": ""You are a helpful assistant."" }, { ""role"": ""user"", ""content"": ""Who are you?"" } ] }"; // Send the request and get the response string result = await SendPostRequestAsync(url, jsonContent, apiKey); // Print the result Console.WriteLine(result); } private static async Task SendPostRequestAsync(string url, string jsonContent, string apiKey) { using (var content = new StringContent(jsonContent, Encoding.UTF8, "application/json")) { // Set the request headers httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey); httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json")); // Send the request and get the response HttpResponseMessage response = await httpClient.PostAsync(url, content); // Handle the response if (response.IsSuccessStatusCode) { return await response.Content.ReadAsStringAsync(); } else { return $"Request failed: {response.StatusCode}"; } } } } - lang: php label: Text input source: |- "qwen3.8-max", "messages" => [ [ "role" => "system", "content" => "You are a helpful assistant." ], [ "role" => "user", "content" => "Who are you?" ] ] ]; // Initialize a cURL session $ch = curl_init(); // Set cURL options curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); // Execute the cURL session $response = curl_exec($ch); // Check for errors if (curl_errno($ch)) { echo 'Curl error: ' . curl_error($ch); } // Close the cURL resource curl_close($ch); // Print the response echo $response; ?> - lang: curl label: Text input source: |- # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL. # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions curl -X POST https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/chat/completions \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H "Content-Type:application/json" \ -d '{ "model": "qwen3.8-max", "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "Who are you?" } ] }' - lang: python label: Streaming source: |- import os from openai import OpenAI client = OpenAI( # If the environment variable is not set, replace the following line with:api_key="sk-xxx" api_key=os.getenv("DASHSCOPE_API_KEY"), # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL. # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions base_url="https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1", ) completion = client.chat.completions.create( model="qwen3.8-max", messages=[{'role': 'system', 'content': 'You are a helpful assistant.'}, {'role': 'user', 'content': 'Who are you?'},], stream=True, stream_options={"include_usage": True} ) for chunk in completion:print(chunk.model_dump_json()) - lang: javascript label: Streaming source: |- import OpenAI from "openai"; const openai = new OpenAI( { apiKey:process.env.DASHSCOPE_API_KEY, // Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL. // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions baseURL: "https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1" } ); async function main() { const completion = await openai.chat.completions.create({ model: "qwen3.8-max", messages: [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Who are you?"} ], stream:true, }); for await (const chunk of completion) { console.log(JSON.stringify(chunk)); } } main(); - lang: curl label: Streaming source: |- # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL. # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions curl --location "https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/chat/completions" \ --header "Authorization: Bearer $DASHSCOPE_API_KEY" \ --header "Content-Type:application/json" \ --data '{ "model": "qwen3.8-max", "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "Who are you?" } ], "stream":true }' - lang: python label: Image input source: |- import os from openai import OpenAI client = OpenAI( # If the environment variable is not set, replace the following line with:api_key="sk-xxx" api_key=os.getenv("DASHSCOPE_API_KEY"), # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL. # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions base_url="https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1", ) completion = client.chat.completions.create( model="qwen3.8-max", messages=[ { "role": "user", "content": [ {"type": "image_url", "image_url": {"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"}}, {"type": "text", "text": "Describe what you see in this image"}, ], } ], ) print(completion.model_dump_json()) - lang: javascript label: Image input source: |- import OpenAI from "openai"; const openai = new OpenAI({ // If the environment variable is not set, replace the following line with:apiKey: "sk-xxx", apiKey:process.env.DASHSCOPE_API_KEY, // Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL. // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions baseURL: "https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1" }); async function main() { const completion = await openai.chat.completions.create({ model: "qwen3.8-max", messages: [ { role: "user", content: [ { type: "image_url", image_url: { url: "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg" } }, { type: "text", text: "Describe what you see in this image" }, ] } ], }); console.log(JSON.stringify(completion)); } main(); - lang: curl label: Image input source: |- # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL. # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions curl -X POST https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/chat/completions \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H "Content-Type:application/json" \ -d '{ "model": "qwen3.8-max", "messages": [ { "role": "user", "content": [ { "type": "image_url", "image_url": {"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"} }, { "type": "text", "text": "Describe what you see in this image" } ] } ] }' - lang: python label: Video input source: |- import os from openai import OpenAI client = OpenAI( # If the environment variable is not set, replace the following line with:api_key="sk-xxx" api_key=os.getenv("DASHSCOPE_API_KEY"), # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL. # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions base_url="https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1", ) # This example passes a list of images as video input. See the visual understanding guide for passing video files completion = client.chat.completions.create( model="qwen3.8-max", messages=[ { "role": "user", "content": [ { "type": "video", "video": [ "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/xzsgiz/football1.jpg", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/tdescd/football2.jpg", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/zefdja/football3.jpg", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/aedbqh/football4.jpg" ] }, {"type": "text", "text": "Describe the specific process in this video"}, ], } ], ) print(completion.model_dump_json()) - lang: javascript label: Video input source: |- import OpenAI from "openai"; const openai = new OpenAI({ // If the environment variable is not set, replace the following line with:apiKey: "sk-xxx", apiKey:process.env.DASHSCOPE_API_KEY, // Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL. // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions baseURL: "https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1" }); async function main() { const completion = await openai.chat.completions.create({ model: "qwen3.8-max", messages: [ { role: "user", content: [ { type: "video", video: [ "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/xzsgiz/football1.jpg", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/tdescd/football2.jpg", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/zefdja/football3.jpg", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/aedbqh/football4.jpg" ] }, { type: "text", text: "Describe the specific process in this video" }, ] } ], }); console.log(JSON.stringify(completion)); } main(); - lang: curl label: Video input source: |- # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL. # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions curl -X POST https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/chat/completions \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H "Content-Type:application/json" \ -d '{ "model": "qwen3.8-max", "messages": [ { "role": "user", "content": [ { "type": "video", "video": [ "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/xzsgiz/football1.jpg", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/tdescd/football2.jpg", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/zefdja/football3.jpg", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/aedbqh/football4.jpg" ] }, { "type": "text", "text": "Describe the specific process in this video" } ] } ] }' - lang: python label: Tool calling source: |- import os from openai import OpenAI client = OpenAI( # If the environment variable is not set, replace the following line with:api_key="sk-xxx" api_key=os.getenv("DASHSCOPE_API_KEY"), # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL. # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions base_url="https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1", ) tools = [ # Tool 1:get the current time { "type": "function", "function": { "name": "get_current_time", "description": "Useful when you want to know the current time.", # Getting the current time needs no input parameters, so parameters is an empty dictionary "parameters": {} } }, # Tool 2:get the weather for a specified city { "type": "function", "function": { "name": "get_current_weather", "description": "Useful when you want to query the weather of a specified city.", "parameters": { "type": "object", "properties": { # A location must be provided to query the weather, so the parameter is set to location "location": { "type": "string", "description": "A city or district, such as Beijing, Hangzhou, or Yuhang District." } }, "required": ["location"] } } } ] messages = [{"role": "user", "content": "What's the weather like in Hangzhou?"}] completion = client.chat.completions.create( model="qwen3.8-max", messages=messages, tools=tools, ) print(completion.model_dump_json()) - lang: javascript label: Tool calling source: |- import OpenAI from "openai"; const openai = new OpenAI({ // If the environment variable is not set, replace the following line with:apiKey: "sk-xxx", apiKey:process.env.DASHSCOPE_API_KEY, // Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL. // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions baseURL: "https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1" }); const messages = [{ "role": "user", "content": "What's the weather like in Hangzhou?" }]; const tools = [ // Tool 1:get the current time { "type": "function", "function": { "name": "get_current_time", "description": "Useful when you want to know the current time.", // Getting the current time needs no input parameters, so parameters is empty "parameters": {} } }, // Tool 2:get the weather for a specified city { "type": "function", "function": { "name": "get_current_weather", "description": "Useful when you want to query the weather of a specified city.", "parameters": { "type": "object", "properties": { // A location must be provided to query the weather, so the parameter is set to location "location": { "type": "string", "description": "A city or district, such as Beijing, Hangzhou, or Yuhang District." } }, "required": ["location"] } } } ]; async function main() { const completion = await openai.chat.completions.create({ model: "qwen3.8-max", messages:messages, tools:tools, }); console.log(JSON.stringify(completion)); } main(); - lang: curl label: Tool calling source: |- # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL. # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions curl -X POST https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/chat/completions \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H "Content-Type:application/json" \ -d '{ "model": "qwen3.8-max", "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "What's the weather like in Hangzhou?" } ], "tools": [ { "type": "function", "function": { "name": "get_current_time", "description": "Useful when you want to know the current time.", "parameters": {} } }, { "type": "function", "function": { "name": "get_current_weather", "description": "Useful when you want to query the weather of a specified city.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "A city or district, such as Beijing, Hangzhou, or Yuhang District." } }, "required": ["location"] } } } ] }' - lang: python label: Asynchronous invocation source: |- import os import asyncio import platform from openai import AsyncOpenAI client = AsyncOpenAI( # If the environment variable is not set, replace the following line with:api_key="sk-xxx" api_key=os.getenv("DASHSCOPE_API_KEY"), # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL. # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions base_url="https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1", ) async def main():completion = await client.chat.completions.create( model="qwen3.8-max", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Who are you?"}, ], ) print(completion.model_dump_json()) if platform.system() == "Windows":asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy()) asyncio.run(main()) components: securitySchemes: BearerAuth: type: http scheme: bearer description: DashScope API key. schemas: ChatCompletionRequest: type: object required: - model - messages properties: model: type: string description: |- The name of the model to use. Supported models include Qwen large language models (commercial and open source), Qwen-VL, Qwen-Coder, Qwen-Omni, and Qwen-Math. For specific model names and billing information, see [Text Generation - Qwen](/developer-guides/getting-started/text-generation-models). `qwen4-max-preview` ([Token Plan only](/token-plan/overview)) is available through Token Plan only, not pay-as-you-go. messages: type: array description: The conversation history for the model, listed in chronological order. items: $ref: "#/components/schemas/Message" stream: type: boolean default: false description: Enables streaming output mode. When `true`, the model generates and sends output incrementally. A data block (chunk) is returned as soon as part of the content is generated. You can read these chunks in real time to assemble the full reply. Set this to `true` to improve the reading experience and reduce the risk of timeouts. stream_options: type: object description: Configuration options for streaming output. This parameter is effective only when `stream` is set to `true`. properties: include_usage: type: boolean default: false description: Specifies whether to include token consumption information in the last data block of the response. modalities: type: array items: type: string default: - text description: 'Specifies the modalities of the output data. This parameter applies only to Qwen-Omni models. Valid values: `["text","audio"]` (applies to models that support audio output) or `["text"]`. `qwen3.8-omni-flash` produces text only.' audio: type: object description: The voice and format of the output audio. This parameter applies to Qwen-Omni models that support audio output and requires the `modalities` parameter to `["text","audio"]`. properties: voice: type: string description: The voice used for the output audio. For more information, see [Voice list](/developer-guides/speech/omni-voice-list). format: type: string description: The format of the output audio. Only `wav` is supported. required: - voice - format temperature: type: number description: |- The sampling temperature controls the diversity of the generated text. Higher values increase diversity, while lower values make the output more deterministic. The value must be greater than or equal to 0 and less than 2. Both `temperature` and `top_p` control the diversity of the generated text. Set only one of them. For Qwen3.8-Omni-Flash, the default is `0.6` in thinking mode and `0.7` in non-thinking mode. Do not modify the default temperature value for QVQ models. `qwen4-max-preview`: In thinking mode, the default is 0.6 for visual input and 1.0 for text input; values below 0.6 are automatically adjusted to 0.6. In non-thinking mode, the default is 0.7. top_p: type: number description: |- `qwen4-max-preview` in non-thinking mode defaults to 0.8. The probability threshold for nucleus sampling. A higher `top_p` value produces more diverse text. A lower `top_p` value produces more deterministic text. Value range: (0, 1.0]. Both `temperature` and `top_p` control the diversity of the generated text. Set only one of them. For Qwen3.8-Omni-Flash, the default is `0.95` in thinking mode and `0.8` in non-thinking mode. Do not modify the default `top_p` value for QVQ models. `qwen4-max-preview` defaults to 0.95 in thinking mode. top_k: type: integer description: |- Specifies the number of candidate tokens to use for sampling during generation. A larger value produces more random output, whereas a smaller value produces more deterministic output. If set to `null` or a value greater than 100, the `top_k` strategy is disabled and only `top_p` takes effect. The value must be an integer greater than or equal to 0. **Default `top_k` values:** - QVQ series: 10 - QwQ series: 40 - Qwen3-Omni-Flash series: 50 - All other models: 20 You must not change the default `top_k` value for QVQ models. **This is not a standard OpenAI parameter.** When using the Python SDK, include it in `extra_body`: `extra_body={"top_k":xxx}`. repetition_penalty: type: number description: |- The repetition penalty for consecutive sequences during model generation. Increasing repetition_penalty can reduce repetition in the model's output. A value of 1.0 means no penalty. There is no strict value range, as long as it is greater than 0. For Qwen3.8-Omni-Flash, the default is `1.05` in both thinking and non-thinking modes. This parameter is not a standard OpenAI parameter. When you call using the Python SDK, place it in the `extra_body` object. Configuration: `extra_body={"repetition_penalty": xxx}`. Do not modify the default `repetition_penalty` value for QVQ models. The default for `qwen4-max-preview` is 1.0. presence_penalty: type: number description: |- Controls how strongly the model avoids repeating content. Valid values: -2.0 to 2.0. Positive values reduce repetition. Negative values increase it. For creative writing or brainstorming, increase this value. For technical documents or formal text, decrease this value. **Default `presence_penalty` values:** - the following models in non-thinking mode (`qwen4-max-preview`, `qwen3.8-max`, `qwen3.8-max-0902`, `qwen3.8-flash`, `qwen3.8-2.4t-a95b`, `qwen3.8-27b`), Qwen3.7 (non-thinking mode), Qwen3.6 (non-thinking mode), Qwen3.5-Omni, Qwen3.5 (non-thinking mode), Qwen3 (non-thinking mode), Qwen3-Instruct series, qwen3-0.6b/1.7b/4b (thinking mode), QVQ series, qwen-max, qwen-max-latest, qwen2.5-vl series, Qwen3-VL (non-thinking): 1.5 - qwen-plus/qwen-plus-latest/2025-04-28 (thinking mode), qwen-turbo-2025-04-28 (thinking mode): 0.5 - Qwen3.8-Omni-Flash: 0.0 in thinking mode and 1.5 in non-thinking mode - All other models: 0.0 - MiniMax series (supplied by Alibaba Cloud): MiniMax-M2.5: 0.0 **How it works:** When the parameter value is positive, the model penalizes tokens that already appear in the generated text. The penalty does not depend on how many times a token appears. This reduces the likelihood of those tokens reappearing, which decreases repetition and increases lexical diversity. Do not modify the default `presence_penalty` value for QVQ models. response_format: type: object description: |- The format of the response content. Defaults to `{"type": "text"}`. Valid values: - `{"type": "text"}`:Returns a plain text response. - `{"type": "json_object"}`:Returns a JSON string that conforms to standard JSON syntax. - `{"type": "json_schema", "json_schema": {...}}`:Returns a JSON string that conforms to a custom schema. If you specify `{"type": "json_object"}`, explicitly instruct the model to output JSON in the prompt, such as by adding "Please output in JSON format." Otherwise, an error occurs. For supported models, see Structured output. properties: type: type: string enum: - text - json_object - json_schema description: The format type. `text` returns plain text. `json_object` returns a JSON string that conforms to standard JSON syntax. `json_schema` returns a JSON string that conforms to a custom schema. json_schema: type: object description: Defines the configuration for structured output. Required when `type` is `json_schema`. properties: name: type: string description: A unique name for the schema. Can contain only letters, numbers, underscores, and hyphens. Maximum 64 characters. description: type: string description: A description of the schema's purpose. This helps the model understand the semantic context of the output. schema: type: object description: An object that conforms to the JSON Schema standard defining the output data structure. strict: type: boolean default: false description: Specifies whether the model must strictly follow all schema constraints. `true` (recommended) ensures full compliance. `false` may result in output that does not conform to the specification. required: - name required: - type max_tokens: type: integer description: |- `qwen4-max-preview`: `max_tokens` is equivalent to `max_completion_tokens` and limits the combined thinking and final answer tokens. **Deprecated.** Use `max_completion_tokens` for new integrations. The meaning of this parameter varies by model: - `deepseek-v4.1-flash`, `deepseek-v4.1-flash-1017`, `deepseek-v4-pro`, `deepseek-v4-pro-0813`, `deepseek-v4-flash-0731`: The maximum number of tokens for the sum of the model's answer and chain-of-thought content. If the model's output exceeds this value, generation stops early, and the returned `finish_reason` is `length`. - `glm-5.3`: `max_tokens` is the maximum number of tokens for the sum of the model's answer and chain-of-thought content. If the model's output exceeds this value, generation stops early and the returned `finish_reason` is `length`. glm-5.3 ignores the `thinking_budget` parameter. - `glm-5.2`: When `thinking_budget` is not passed, `max_tokens` is the maximum number of tokens for the sum of the model's answer and chain-of-thought content, and if the model's output exceeds this value, generation stops early with the returned `finish_reason` being `length`. When `thinking_budget` is passed, `max_tokens` is the maximum number of tokens for the model's answer only, and the chain-of-thought token count is controlled separately by `thinking_budget`. - Other models: The maximum number of tokens for the model's answer. If the generated content exceeds this value, generation stops early, and the returned `finish_reason` is `length`. For GLM models, the default and maximum values are as follows. For other models, the default and maximum values are both the model's maximum output length. - Alibaba Cloud (glm-5.3, glm-5.2, glm-5.2-fast-preview, glm-5.1, glm-5): default 65536, maximum 131072 - ZHIPU AI (ZHIPU/GLM-5.3, ZHIPU/GLM-5.2): default 65536, maximum 131072 deprecated: true max_completion_tokens: type: integer description: |- The maximum number of tokens in this response, including chain-of-thought tokens. Generation stops when this limit is reached, and `finish_reason` is set to `length`. For GLM models, see the description in the `max_tokens` parameter. For other models, the default and maximum values are the model's maximum output length. **Difference from `max_tokens`:** `max_completion_tokens` always limits the complete model output (chain-of-thought + answer). The scope that `max_tokens` limits varies by model and the `thinking_budget` setting, as described above. For reasoning models, `max_completion_tokens` is recommended. **Supported models:** - Qwen-Max: Qwen3.7-Max and later - Qwen-Plus: Qwen3.5-Plus and later - Qwen-Flash: Qwen3.5-Flash and later - Kimi: kimi-k2.5 and later - GLM: The Alibaba Cloud-supplied and ZHIPU AI-supplied models listed in the `max_tokens` parameter - MiniMax: MiniMax-M2.5 and later - DeepSeek: deepseek-v4-pro, and later Except for the ZHIPU AI-supplied GLM models listed above, the models above do not include other third-party direct-supply models. The actual number of output tokens may differ from the configured value by up to 10 tokens. vl_high_resolution_images: type: boolean default: false description: |- Increases the maximum pixel limit for input images to the pixel value corresponding to 16384 tokens. When `true`, a fixed-resolution strategy is used and the `max_pixels` setting is ignored. If an image exceeds the pixel limit, its total pixel count is downscaled to meet the limit. **Pixel limits when `vl_high_resolution_images` is `true`:** - qwen4-max-preview, qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash, qwen3.8-2.4t-a95b, qwen3.8-27b, qwen3.8-omni-flash, Qwen3.7 series, Qwen3.6 series, Qwen3.5 series, Qwen3-VL series: 16,777,216 (each token corresponds to 32×32 pixels, i.e., 16,384×32×32) - QVQ series and other Qwen2.5-VL series models: 12,845,056 (each token corresponds to 28×28 pixels, i.e., 16,384×28×28) If `vl_high_resolution_images` is `false`, the actual pixel limit is determined by `max_pixels`. **This is not a standard OpenAI parameter.** When using the Python SDK, include it in `extra_body`: `extra_body={"vl_high_resolution_images":xxx}`. n: type: integer default: 1 description: The number of responses to generate. Must be an integer in the range of 1-4. This is useful for scenarios that require multiple candidate responses, such as creative writing or ad copy. `n=0` is equivalent to `n=1`. Supported only by Qwen3 (non-thinking mode) models. If you pass the `tools` parameter, set `n` to 1. Increasing `n` increases output token consumption but does not affect input token consumption. enable_thinking: type: boolean description: |- For kimi-k3.1-pro (deployed on QwenCloud), the default is `true`. You can set it to `false` to disable thinking, but keeping it enabled is strongly recommended because disabling it significantly degrades output quality. Enables the thinking mode for hybrid thinking models. This mode is available for the Qwen4.0, Qwen3.8, Qwen3.7, Qwen3.6, Qwen3.5, Qwen3, Qwen3.8-Omni-Flash, Qwen3-Omni-Flash, and Qwen3-VL models, as well as the DeepSeek-V4.1-Flash, DeepSeek-V4-Pro/V4-Flash series, DeepSeek-V3.2-exp/V3.1 series, Kimi-K2.7-code (thinking model only), Kimi-K2.6/K2.5 series, and GLM series. qwen4-max-preview, qwen3.8-max and qwen3.8-max-0902 enable thinking mode by default. When enabled, the thinking content is returned in the `reasoning_content` field. The DeepSeek-V4 series enables thinking by default. You can adjust the inference intensity with the `reasoning_effort` parameter. Default values differ by model. For supported models and their default `enable_thinking` values, see the Model List. **This is not a standard OpenAI parameter.** When using the Python SDK, place it in `extra_body`: `extra_body={"enable_thinking":xxx}`. If you call over HTTP directly (for example, with curl) instead of using the OpenAI SDK, do not use `extra_body`. Simply place `enable_thinking` at the top level of the request body (`body`), alongside parameters such as `model` and `messages`, for example `"enable_thinking":true`. thinking_budget: type: integer description: |- The maximum number of tokens for the thinking process. Applies to `qwen4-max-preview`, `qwen3.8-max`, `qwen3.8-max-0902`, `qwen3.8-flash`, `qwen3.8-2.4t-a95b`, `qwen3.8-27b`, as well as Qwen3.7, Qwen3.6, Qwen3.5, Qwen3-VL, Qwen3, GLM, and Kimi models, except kimi-k3.1-pro and kimi-k3, which do not support this parameter. For these models, the default value is the model's maximum chain-of-thought length. For more information, see the Model List. **This is not a standard OpenAI parameter.** When using the Python SDK, place it in `extra_body`: `extra_body={"thinking_budget":xxx}`. preserve_thinking: type: boolean default: false description: |- kimi-k3.1-pro and kimi-k3 (deployed on QwenCloud) retain historical `reasoning_content` supplied by the client by default. We recommend returning historical assistant messages and their complete `reasoning_content` in `messages`. Specifies whether to append the `reasoning_content` from assistant messages in the conversation history to the model input. This is suitable for scenarios where the model needs to refer to the historical thinking process. To reference reasoning from a previous turn, include it in the historical assistant message's `reasoning_content` field in `messages`. See [Pass the thinking process](/developer-guides/text-generation/thinking#preserve-thinking-in-multi-turn). Currently supported by qwen4-max-preview (enabled by default), qwen3.8-max (enabled by default), qwen3.8-max-0902 (enabled by default), qwen3.8-flash, qwen3.8-omni-flash (enabled by default), qwen3.7-max, qwen3.7-max-2026-05-20 and subsequent snapshots, qwen3.7-plus, qwen3.7-plus-2026-05-26, qwen3.6-plus, qwen3.6-plus-2026-04-02, qwen3.7-flash, qwen3.7-flash-2026-07-15, qwen3.6-flash, qwen3.6-flash-2026-04-16, kimi-k2.6 (deployed on QwenCloud), kimi-k2.7-code (deployed on QwenCloud, enabled by default), kimi/kimi-k2.7-code-highspeed (supplied by Moonshot AI, enabled by default), and kimi/kimi-k2.7-code (supplied by Moonshot AI, enabled by default). - For the supported `qwen4-max-preview`, `qwen3.8-max`, `qwen3.8-max-0902`, `qwen3.8-flash`, Qwen3.7, Qwen3.6, and Kimi models listed above, enabling this parameter when historical messages lack `reasoning_content` does not cause an error. - When enabled, the `reasoning_content` from the historical conversation is included in the input token count and is billed. **Important (qwen3.8-max):** When using qwen3.8-max, preserve_thinking defaults to true. You must send back all historical reasoning_content in the reasoning_content field. **Do NOT concatenate reasoning_content into the content field.** Doing so may degrade model performance. **This is not a standard OpenAI parameter.** When using the Python SDK, place it in `extra_body`: `extra_body={"preserve_thinking": True}`. **Qwen4-Max-Preview:** `preserve_thinking` defaults to `true`. Return all historical `reasoning_content` in its original field. Do not concatenate it into `content`. reasoning_effort: type: string description: |- Controls model reasoning effort. **kimi-k3.1-pro (deployed on QwenCloud)** (default: `max`): Options: `max` (deep reasoning), `high` (enhanced reasoning), `medium` (moderate reasoning), and `low` (light reasoning). **`qwen4-max-preview`, `qwen3.8-max`, `qwen3.8-max-0902`, `qwen3.8-flash`, `qwen3.8-2.4t-a95b`, `qwen3.8-27b`:** Options: `low`, `medium`, `xhigh`. Default: `xhigh`. Cannot be set together with thinking_budget — setting both will cause an error. The two parameters support automatic conversion:when thinking_budget is not set, reasoning_effort maps to thinking_budget (`low`→4096, `medium`→16384, `xhigh`→262144); when reasoning_effort is not set, thinking_budget maps back to reasoning_effort (0–4096→`low`, 4097–16384→`medium`, 16385–262144→`xhigh`); when neither is set, defaults are thinking_budget=131072, reasoning_effort=`xhigh`. OpenAI standard value mapping: `max` is mapped to xhigh, `high` is mapped to xhigh, `minimal` is mapped to low, and `none` is mapped to enable_thinking=False. Setting values other than the above valid values and mapped values will cause an error. **DeepSeek-V4 and GLM series:** Options: `high` (intensive reasoning), `max` (maximum reasoning). low and medium map to high, xhigh maps to max. Applies to glm-5.2, glm-5.1, glm-5, deepseek-v4-pro. **glm-5.3, ZHIPU/GLM-5.3, kimi-k3 (supplied by Alibaba Cloud):** Default value: `max`. Valid values: `max` (default, deep reasoning), `high` (enhanced reasoning), `low` (light reasoning). The glm-5.3 series models always perform thinking. `enable_thinking` supports only `true`, and passing `false` causes the API request to fail. kimi-k3 supports passing `false` to disable thinking. **deepseek-v4-flash-0731 and deepseek-v4-pro-0813:** Default value: `high`. Valid values: `max` (maximum-intensity inference), `high` (default, standard inference), `low` (low-intensity inference). For compatibility, `medium` is mapped to high, and `xhigh` is mapped to high. **deepseek-v4.1-flash, deepseek-v4.1-flash-1017:** Default value: `high`. Valid values: `max` (maximum-intensity inference), `high` (default, high-intensity inference), `low` (low-intensity inference). `minimal` is mapped to `low`, `medium` and `xhigh` are mapped to `high`, and `ultra` is mapped to `max`. **kimi/kimi-k3 (supplied by Moonshot AI):** Default value: `max`; only `max` is supported. **Qwen3.8-Omni-Flash:** `qwen3.8-omni-flash` has thinking enabled by default, with `reasoning_effort` defaulting to `xhigh`. In Chat Completions, `reasoning_effort` accepts `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`; do not set it together with `thinking_budget`. Choose `low`, `medium`, or `xhigh` for the thinking effort. For compatibility, `minimal` maps to `low`, `high` and `max` map to `xhigh`, and `none` disables thinking. default: high clear_thinking: type: boolean default: false description: |- Controls whether the `reasoning_content` (thinking process) from previous turns in a multi-turn conversation is used as context input for the model. Supported only by the GLM series models glm-5.3, glm-5.2, glm-5.1, and glm-5. The default value is `true` for glm-5.3 and `false` for the other models. - `true`:Ignores the `reasoning_content` from previous turns and uses only visible text, tool calls, results, and other non-inference content as context input. This can reduce the context length and cost. - `false` (default): Retains the `reasoning_content` from previous turns and provides it to the model along with the context. If you want to enable Preserved Thinking, you must pass the historical `reasoning_content` completely, unmodified, and in the original order within messages. **This is not a standard OpenAI parameter.** When using the Python SDK, place it in `extra_body`: `extra_body={"clear_thinking": True}`. tool_stream: type: boolean default: false description: |- Only takes effect when `stream=true`. Controls streaming behavior for complex tool arguments. Ordinary tool arguments (all parameter types are string) are streamed as long as `stream=true` is enabled; `tool_stream` has no effect on them. Complex tools are those whose definitions include parameters of type array or object. **Supported Qwen models:** - qwen-max series:text modality of the qwen4-max-preview, qwen3.8-max and qwen3.7-max series - qwen-plus series:text modality of the qwen3.7-plus and qwen3.6-plus series, and all modalities of the qwen3.5-plus series - qwen-flash series:all modalities of the qwen3.8-flash, qwen3.7-flash, qwen3.6-flash and qwen3.5-flash series **Qwen usage:** - `tool_stream=false`:Complex tool arguments are returned all at once (default). More accurate for complex formats. - `tool_stream=true`:Complex tool arguments are streamed. Avoids timeout risk for complex formats. **Supported GLM models:** glm-5.1. **GLM usage:** - `tool_stream=false`:Tool arguments are returned all at once (default). More accurate for complex formats. - `tool_stream=true`:Tool arguments are streamed. Avoids timeout risk for complex formats. **This is not a standard OpenAI parameter.** When using the Python SDK, include it in `extra_body`: `extra_body={"tool_stream":true}`. enable_code_interpreter: type: boolean default: false description: |- Specifies whether to enable the code interpreter feature. **This is not a standard OpenAI parameter.** When using the Python SDK, include it in `extra_body`: `extra_body={"enable_code_interpreter":xxx}`. seed: type: integer description: "The random number seed. Ensures reproducible results. If you use the same seed value and other parameters remain unchanged, the model returns the same result whenever possible. Valid values: [0, 2^31-1]." logprobs: type: boolean default: false description: |- Specifies whether to return the log probabilities of the output tokens. Content generated during the thinking phase (`reasoning_content`) does not include log probabilities. **Supported models:** - Qwen-plus series snapshots (excluding the stable model) - Qwen3-vl-plus models (including the stable model) - Qwen3 open source models top_logprobs: type: integer default: 0 description: "The number of most likely candidate tokens to return at each generation step. Valid values: 0 to 5. This parameter applies only if `logprobs` is set to `true`." stop: oneOf: - type: string - type: array items: type: string description: Stop words. If a string or token specified in `stop` appears in the generated text, generation stops immediately. If `stop` is an array, do not use a `token_id` and a string as elements simultaneously. tools: type: array description: An array of one or more tool objects that the model can call in function calling. When `tools` is set and the model determines that a tool needs to be called, the response returns tool information in the `tool_calls` field. For usage examples, see the [Function calling guide](/developer-guides/text-generation/function-calling). items: type: object required: - type - function properties: type: type: string enum: - function description: Tool type. Currently supports only `function`. function: type: object required: - name - description properties: name: type: string description: The tool name. Must contain only letters, digits, underscores, and hyphens. Up to 64 tokens. description: type: string description: A description of the tool. Helps the model determine when and how to call the tool. parameters: type: object default: {} description: The tool's parameters described using a valid JSON Schema. If empty, the tool has no input parameters. tool_choice: oneOf: - type: string enum: - auto - none - required - type: object properties: type: type: string enum: - function function: type: object properties: name: type: string description: The name of the function to call. required: - name required: - type - function default: auto description: 'The tool selection policy. `auto` lets the model select. `none` disables tool calling. `required` forces at least one tool to be called; the model will always return tool call information (the Qwen series models do not support `required`:in non-thinking mode it cannot guarantee that a tool is always called, and in thinking mode `required` is not supported). An object with `{"type": "function", "function": {"name": "..."}}` forces a specific tool. Models in thinking mode do not support forcing a specific tool.' parallel_tool_calls: type: boolean default: true description: Specifies whether to enable parallel tool calling. `kimi-k3` does not support using this parameter to control whether tool calls are parallel. Setting it to `false` does not guarantee sequential tool calls, and the model may still return multiple `tool_calls` in one turn. Process the returned tool calls as provided. enable_search: type: boolean default: false description: |- Enables web search. kimi-k3.1-pro (deployed on QwenCloud) supports this parameter in all regions: Singapore, China North 2 (Beijing), Germany (Frankfurt), China (Hong Kong), Japan (Tokyo), and US (Virginia). Enabling web search may increase token consumption. **This is not a standard OpenAI parameter.** When using the Python SDK, include it in `extra_body`: `extra_body={"enable_search": True}`. search_options: type: object description: |- The web search strategy. Takes effect only when `enable_search` is `true`. **Properties:** - `forced_search` (boolean, default: `false`): Forces web search. `true` forcefully enables web search. `false` lets the model decide. - `search_strategy` (string, default: `turbo`): The search scale strategy. `turbo` balances speed and effectiveness. `max` uses a more comprehensive strategy with multiple search engines. `agent` calls search and LLM multiple times for multi-round retrieval (applicable only to qwen3.7-max, qwen3.7-max-2026-06-08, qwen3.7-max-2026-05-20, qwen3.7-max-preview, qwen3.7-max-2026-05-17, 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.5-flash, qwen3.5-flash-2026-02-23,qwen3.8-omni-flash, qwen3.5-omni-plus, qwen3.5-omni-plus-2026-03-15, qwen3.5-omni-flash, and qwen3.5-omni-flash-2026-03-15). When `agent` is enabled, only return search sources (`enable_source:true`) is supported. All other web search features are unavailable. - `enable_search_extension` (boolean, default: `false`): Enables domain-specific search. **This is not a standard OpenAI parameter.** When using the Python SDK, include it in `extra_body`: `extra_body={"search_options":xxx}`. properties: forced_search: type: boolean default: false description: Forces web search. `true` forcefully enables web search. `false` lets the model decide. search_strategy: type: string enum: - turbo - max - agent default: turbo description: The search scale strategy. `turbo` (default) balances speed and effectiveness. `max` uses a more comprehensive strategy with multiple search engines; response time may be longer. `agent` calls web search and LLM multiple times for multi-round retrieval. Applicable only to qwen3.7-max, qwen3.7-max-2026-06-08, qwen3.7-max-2026-05-20, qwen3.7-max-preview, qwen3.7-max-2026-05-17, 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.5-flash, qwen3.5-flash-2026-02-23,qwen3.8-omni-flash, qwen3.5-omni-plus, qwen3.5-omni-plus-2026-03-15, qwen3.5-omni-flash, and qwen3.5-omni-flash-2026-03-15. When `agent` is enabled, only return search sources (`enable_source:true`) is supported. enable_search_extension: type: boolean default: false description: Enables domain-specific search. include_tool_usage: type: boolean default: false description: |- Whether to return web search usage statistics in the response `usage`. `x_tools` is returned only when a web search is actually triggered in the request. If `enable_search` is not enabled, or the model determines that no web search is needed, this field is not returned even when this parameter is set to `true`. **This is not a standard OpenAI parameter.** When using the Python SDK, include it in `extra_body`: `extra_body={"include_tool_usage": True}`. Message: oneOf: - title: System message type: object description: A system message that defines the role, tone, task objectives, or constraints for the model. Place it at the beginning of the messages array. Do not set a System Message for the QwQ model. A System Message has no effect on the QVQ model. required: - role - content properties: role: type: string enum: - system description: The role for a system message. Fixed as `system`. content: type: string description: A system instruction that defines the model's role, behavior, response style, and task constraints. - 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 for a user message. Fixed as `user`. content: description: The message content. A string for text-only input; an array for multimodal input or explicit caching. oneOf: - type: array description: An array of content parts. Use for multimodal input (images, audio, video) or when explicit caching is enabled. items: type: object properties: type: type: string enum: - text - image_url - input_audio - video - video_url description: The content type. `text` for text, `image_url` for images, `input_audio` for audio, `video` for image list video, `video_url` for video files. text: type: string description: The input text. Required when `type` is `text`. image_url: type: object description: The input image information. Required when `type` is `image_url`. For usage examples, see the [Vision guide](/developer-guides/multimodal/vision). properties: url: type: string description: The URL or Base64 Data URL of the image. required: - url input_audio: type: object description: The input audio information. Required when `type` is `input_audio`. For usage examples, see the [Audio understanding guide](/developer-guides/text-generation/audio-understanding). properties: data: type: string description: The URL or Base64 Data URL of the audio. format: type: string description: The format of the input audio, such as `mp3` or `wav`. required: - data - format video: type: array items: type: string description: The video as an image list. Required when `type` is `video`. For usage examples, see the [Vision guide](/developer-guides/multimodal/vision). video_url: type: object description: The input video file information. Required when `type` is `video_url`. For usage examples, see the [Vision guide](/developer-guides/multimodal/vision). properties: url: type: string description: The public network URL or Base64 Data URL of the video file. required: - url fps: type: number description: |- The number of frames to extract per second. Value range: [0.1, 10]. Default: 2.0. The fps parameter has two functions: - When you input a video file, it controls the frame extraction frequency. One frame is extracted every `1/fps` seconds. - It informs the model of the time interval between adjacent frames to help it better understand the video's progression over time. This applies to both video file and image list inputs. This feature is suitable for scenarios such as event time localization or segmented content summarization. Supported by Qwen3.7, Qwen3.6, Qwen3.5, `Qwen3-VL`, `Qwen2.5-VL`, Qwen3.8-Omni-Flash, Qwen3.5-Omni, and QVQ models. min_pixels: type: integer description: |- Sets the minimum pixel threshold for an input image or video frame. If an input image or video frame has a pixel count less than min_pixels, it is scaled up until the total pixel count exceeds min_pixels. See the supported models and values below. Value range: - For image input: - qwen4-max-preview, qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash, qwen3.8-2.4t-a95b, qwen3.8-27b, Qwen3.7, Qwen3.6, Qwen3.5, and Qwen3-VL: Default and minimum is 65536. - qwen3.8-omni-flash and Qwen3.5-Omni: Default and minimum is 24576. - Other models, open source Qwen2.5-VL series, and QVQ series models: Default and minimum is 3136. - For video file or image list input: - qwen4-max-preview, qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash, qwen3.8-2.4t-a95b, qwen3.8-27b, qwen3.8-omni-flash, Qwen3.7, Qwen3.6, Qwen3.5, Qwen3.5-Omni, Qwen3-VL (including commercial and open source versions):Default is 65536. Minimum is 4096. - Other models, open source Qwen2.5-VL series, and QVQ series models: Default is 50176. Minimum is 3136. max_pixels: type: integer description: |- Sets the maximum pixel threshold for an input image or video frame. If an input image or video has a pixel count within the [min_pixels, max_pixels] range, the model processes the original image. If the pixel count exceeds max_pixels, the image is scaled down until its total pixel count is less than max_pixels. See the supported models and values below. Value range: - For image input (max_pixels is related to whether the vl_high_resolution_images parameter is enabled): - If vl_high_resolution_images is False: - qwen4-max-preview, qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash, qwen3.8-2.4t-a95b, qwen3.8-27b, Qwen3.7, Qwen3.6, Qwen3.5, and Qwen3-VL: Default is 2621440. Maximum is 16777216. - qwen3.8-omni-flash and Qwen3.5-Omni: Default is 1310720. Maximum is 16777216. - Other models, open source Qwen2.5-VL series, and QVQ series models: Default is 1003520. Maximum is 12845056. - If vl_high_resolution_images is True: - qwen4-max-preview, qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash, qwen3.8-2.4t-a95b, qwen3.8-27b, qwen3.8-omni-flash, Qwen3.7, Qwen3.6, Qwen3.5-Omni, Qwen3.5, Qwen3-VL:max_pixels is invalid. The maximum pixel count for an input image is fixed at 16777216. - Other models, open source Qwen2.5-VL series, and QVQ series models:max_pixels is invalid. The maximum pixel count for an input image is fixed at 12845056. - For video file or image list input: - qwen4-max-preview, qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash, qwen3.8-2.4t-a95b, qwen3.8-27b, qwen3.8-omni-flash, Qwen3.7 series, Qwen3.6 series, Qwen3.5 series, Qwen3.5-Omni, Qwen3-VL closed-source series: Default is 655360. Maximum is 2048000. - Other Qwen3-VL open source models:Default is 655360. Maximum is 786432. - Other models, open source Qwen2.5-VL series, and QVQ series models: Default is 501760. Maximum is 602112. total_pixels: type: integer description: |- Limits the total number of pixels for all frames extracted from a video (pixels per frame × total number of frames). If the video's total pixel count exceeds this limit, the system scales down the video frames while ensuring that the pixel count of any single frame remains within the [min_pixels, max_pixels] range. See the supported models and values below. For long videos with many extracted frames, lower this value to reduce token consumption and processing time (though this may cause a loss of image detail). Value range: - qwen4-max-preview, qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash, qwen3.8-2.4t-a95b, qwen3.8-27b, Qwen3.7, Qwen3.6, Qwen3.5 series: Default and maximum is 819200000. This corresponds to approximately 800000 image tokens (1 image token per 32×32 pixels). - qwen3.8-omni-flash and Qwen3.5-Omni: Default and minimum is 184549376. This corresponds to approximately 180224 image tokens (1 image token per 32×32 pixels). - Qwen3-VL closed-source series: Default and maximum is 134217728. This corresponds to approximately 131072 image tokens (1 image token per 32×32 pixels). - Other Qwen3-VL open source models:Default and minimum is 67108864. This corresponds to approximately 65536 image tokens (1 image token per 32×32 pixels). - Other models, open source Qwen2.5-VL series, and QVQ series models: Default and minimum is 51380224. This corresponds to approximately 65536 image tokens (1 image token per 28×28 pixels). cache_control: type: object description: Enables explicit caching. properties: type: type: string enum: - ephemeral description: Only `ephemeral` is supported. required: - type required: - type - type: string description: A plain text string. Use for text-only input. - title: Assistant message type: object description: The model's reply. Typically sent back to the model as context in a multi-turn conversation. required: - role properties: role: type: string enum: - assistant description: The role for an assistant message. Fixed as `assistant`. content: type: string description: The text content of the model's reply. If `tool_calls` is included, `content` can be empty. Otherwise, `content` is required. partial: type: boolean default: false description: Specifies whether to enable partial mode. tool_calls: type: array description: The tool and input parameter information returned after a function call is initiated. items: type: object required: - id - type - function - index properties: id: type: string description: The ID of the tool response. type: type: string enum: - function description: The tool type. Currently, only `function` is supported. function: type: object required: - name - arguments properties: name: type: string description: The tool name. arguments: type: string description: The input parameter information, formatted as a JSON string. index: type: integer description: The index of the current tool in the `tool_calls` array. - title: Tool message type: object description: The output information of the tool. required: - role - content - tool_call_id properties: role: type: string enum: - tool description: Fixed as `tool`. content: type: string description: The output content of the tool function. Must be a string. If the tool returns structured data (such as JSON), serialize it into a string. tool_call_id: type: string description: The ID returned after a function call is initiated. Retrieve it from `completion.choices[0].message.tool_calls[$index].id`. ChatCompletion: type: object description: Chat response object (non-streaming output). properties: id: type: string description: The unique identifier for this request. choices: type: array description: An array of generated content from the model. items: type: object properties: finish_reason: type: string enum: - stop - length - tool_calls description: The reason the model stopped generating. `stop`:stopped naturally or by stop parameter. `length`:reached maximum output length. `tool_calls`:stopped to call a tool. index: type: integer description: The index of this object in the choices array. logprobs: $ref: "#/components/schemas/Logprobs" message: $ref: "#/components/schemas/AssistantResponseMessage" created: type: integer description: The Unix timestamp, in seconds, when the request was created. model: type: string description: The model used for this request. object: type: string enum: - chat.completion description: Always `chat.completion`. service_tier: type: string nullable: true description: Currently fixed as `null`. system_fingerprint: type: string nullable: true description: Currently fixed as `null`. usage: $ref: "#/components/schemas/Usage" ChatCompletionChunk: type: object description: Chat response chunk object (streaming output). properties: id: type: string description: The unique identifier for this request. All chunks in the same response share the same id. choices: type: array description: An array of generated content objects. If `include_usage` is `true`, the `choices` array is empty in the final chunk. items: type: object properties: delta: type: object description: The incremental content object for this chunk. properties: content: type: string description: The incremental message content. reasoning_content: type: string description: The incremental chain-of-thought content. function_call: type: object nullable: true description: Defaults to `null`. Use `tool_calls` instead. audio: type: object description: The response generated by Qwen-Omni. properties: data: type: string description: The incremental Base64-encoded audio data. expires_at: type: integer description: The UNIX timestamp when the request was created. refusal: type: object nullable: true description: Always `null`. role: type: string description: The role. Appears only in the first chunk. tool_calls: type: array description: Tool call information generated after a function call. items: type: object properties: index: type: integer description: The index of the current tool in the tool_calls array. id: type: string description: The unique ID for this tool response. function: type: object properties: arguments: type: string description: Incremental input parameter information. Concatenate from all chunks. name: type: string description: The tool name. Appears only in the first chunk. type: type: string description: The tool type. Currently, only `function` is supported. nullable: true finish_reason: type: string nullable: true enum: - stop - length - tool_calls - null description: The reason generation stopped. `null` before generation is complete. index: type: integer description: The index of the current response in the choices array. logprobs: $ref: "#/components/schemas/Logprobs" created: type: integer description: The UNIX timestamp when this request was created. model: type: string description: The model used for this request. object: type: string enum: - chat.completion.chunk description: Always `chat.completion.chunk`. service_tier: type: string nullable: true description: Currently fixed as `null`. system_fingerprint: type: string nullable: true description: Currently fixed as `null`. usage: $ref: "#/components/schemas/StreamingUsage" AssistantResponseMessage: type: object description: The message generated by the model. properties: content: type: string description: The content of the model's response. reasoning_content: type: string description: The content of the model's chain-of-thought reasoning. refusal: type: string nullable: true description: This field is always `null`. role: type: string enum: - assistant description: Always `assistant`. audio: type: object nullable: true description: This field is always `null`. function_call: type: object nullable: true description: (Deprecated) This field is always `null`. Use `tool_calls` instead. tool_calls: type: array description: Information about tools and their input parameters that the model generates after initiating a function call. items: type: object properties: id: type: string description: The unique identifier for this tool response. type: type: string enum: - function description: The type of the tool. Currently, only `function` is supported. function: type: object properties: name: type: string description: The name of the tool. arguments: type: string description: The input parameters, formatted as a JSON string. Model outputs are non-deterministic. Validate the parameters before calling the function. index: type: integer description: The index of this tool in the `tool_calls` array. Logprobs: type: object nullable: true description: Log probability information for tokens in the model's output. properties: content: type: array description: An array of tokens and their corresponding log probabilities. items: type: object properties: token: type: string description: The text of the current token. bytes: type: array items: type: integer description: A list of raw UTF-8 bytes for the current token. logprob: type: number nullable: true description: The log probability of the current token. `null` indicates an extremely low probability. top_logprobs: type: array description: The most likely candidate tokens for the current position. items: type: object properties: token: type: string description: The candidate token text. bytes: type: array items: type: integer description: Raw UTF-8 bytes for the token. logprob: type: number nullable: true description: The log probability of this candidate token. Usage: type: object description: Token consumption details for this request. properties: completion_tokens: type: integer description: The number of tokens in the model's output. prompt_tokens: type: integer description: The number of tokens in the input. total_tokens: type: integer description: The total number of tokens consumed (prompt_tokens + completion_tokens). completion_tokens_details: type: object description: A fine-grained breakdown of output tokens. This field is returned only by some models. Note that `text_tokens` includes `reasoning_tokens` — `reasoning_tokens` is the subset of `text_tokens` corresponding to the thinking process, so `text_tokens` minus `reasoning_tokens` is the number of tokens in the final visible reply. This field is typically returned only when the model outputs a thinking process; it may be `null` or absent when thinking is not enabled. properties: audio_tokens: type: integer nullable: true description: The number of audio tokens in the output (Qwen-Omni). reasoning_tokens: type: integer nullable: true description: The number of tokens in the thinking process. This value is a subset of `text_tokens`. text_tokens: type: integer description: The number of text tokens in the output. This value already includes `reasoning_tokens`. prompt_tokens_details: type: object description: A fine-grained breakdown of input tokens. properties: audio_tokens: type: integer nullable: true description: The number of tokens in the input audio. cached_tokens: type: integer description: The number of tokens that hit the cache. text_tokens: type: integer description: The number of text tokens in the input. image_tokens: type: integer description: The number of image tokens in the input. video_tokens: type: integer description: The number of tokens for the input video. cache_creation: type: object description: Information about explicit cache creation. properties: ephemeral_5m_input_tokens: type: integer description: The number of tokens used to create the explicit cache. cache_creation_input_tokens: type: integer description: The number of tokens used to create the explicit cache. cache_type: type: string description: When using an explicit cache, the value is `ephemeral`. Otherwise, this field does not exist. x_tools: type: object description: Web search usage statistics. Returned only when `include_tool_usage` is `true` in the request and a web search is actually triggered. properties: search: type: object description: Web search usage. Returned when [web search](/developer-guides/tool-calling/web-search) is enabled and a retrieval is actually triggered. properties: count: type: integer description: |- The number of times web search was triggered in this request. When the `agent` search strategy is used, the model can perform multiple retrieval rounds, so this value may be greater than 1. This value is set during the intent-detection stage. It is also counted when the rate limit is exceeded or retrieval returns no results, so it does not mean retrieval actually completed and is not a basis for billing or reconciliation. For details, see [The billed count does not match the count field](/developer-guides/tool-calling/web-search#faq-search-billing-count-mismatch-title). strategy: type: string description: The search strategy actually used for this web search. The value matches `search_options.search_strategy` in the request, such as `turbo`, `max`, or `agent`. ErrorResponse: type: object properties: error: type: object properties: message: type: string description: A human-readable error message. type: type: string description: The error type. param: type: - string - "null" description: The parameter that caused the error. code: type: - string - "null" description: The error code. StreamingUsage: type: object description: Token consumption details for this request. properties: completion_tokens: type: integer description: The number of tokens in the model's output. prompt_tokens: type: integer description: The number of tokens in the input. total_tokens: type: integer description: The total number of tokens consumed (prompt_tokens + completion_tokens). completion_tokens_details: type: object description: A fine-grained breakdown of output tokens. This field is returned only by some models. Note that `text_tokens` includes `reasoning_tokens` — `reasoning_tokens` is the subset of `text_tokens` corresponding to the thinking process, so `text_tokens` minus `reasoning_tokens` is the number of tokens in the final visible reply. This field is typically returned only when the model outputs a thinking process; it may be `null` or absent when thinking is not enabled. properties: audio_tokens: type: integer nullable: true description: The number of audio tokens in the output (Qwen-Omni). reasoning_tokens: type: integer nullable: true description: The number of tokens in the thinking process. This value is a subset of `text_tokens`. text_tokens: type: integer description: The number of text tokens in the output. This value already includes `reasoning_tokens`. prompt_tokens_details: type: object description: A fine-grained breakdown of input tokens. properties: audio_tokens: type: integer nullable: true description: The number of tokens in the input audio. cached_tokens: type: integer description: The number of tokens that hit the cache. text_tokens: type: integer description: The number of text tokens in the input. image_tokens: type: integer description: The number of image tokens in the input. video_tokens: type: integer description: The number of tokens for the input video. cache_creation: type: object description: Information about explicit cache creation. properties: ephemeral_5m_input_tokens: type: integer description: The number of tokens used to create the explicit cache. cache_creation_input_tokens: type: integer description: The number of tokens used to create the explicit cache. cache_type: type: string description: When using an explicit cache, the value is `ephemeral`. Otherwise, this field does not exist. x_tools: type: object description: Web search usage statistics. Returned only when `include_tool_usage` is `true` in the request and a web search is actually triggered. properties: search: type: object description: Web search usage. Returned when [web search](/developer-guides/tool-calling/web-search) is enabled and a retrieval is actually triggered. properties: count: type: integer description: |- The number of times web search was triggered in this request. When the `agent` search strategy is used, the model can perform multiple retrieval rounds, so this value may be greater than 1. This value is set during the intent-detection stage. It is also counted when the rate limit is exceeded or retrieval returns no results, so it does not mean retrieval actually completed and is not a basis for billing or reconciliation. For details, see [The billed count does not match the count field](/developer-guides/tool-calling/web-search#faq-search-billing-count-mismatch-title). strategy: type: string description: The search strategy actually used for this web search. The value matches `search_options.search_strategy` in the request, such as `turbo`, `max`, or `agent`. nullable: true ````