BRASILTradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗
Bate-papo DashScope
SDK nativo e API HTTP
Obtenha uma chave de API e defini-lo como uma variável de ambiente. Para usar o SDK, instale-o.
Ponto final
- HTTP (somente texto, como
qwen-plus):POST https://maas.qwencloudapi.com/api/v1/services/aigc/text-generation/generation - HTTP (multimodal, como
qwen3.7-plus,qwen3-vl-plus):POST https://maas.qwencloudapi.com/api/v1/services/aigc/multimodal-generation/generation-SDKbase_http_api_url:https://maas.qwencloudapi.com/api/v1
SDK Python:
dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1'
SDK Java:
// Option 1: Set during instantiation
import com.alibaba.dashscope.protocol.Protocol;
Generation gen = new Generation(Protocol.HTTP.getValue(), "https://maas.qwencloudapi.com/api/v1");
// Option 2: Set globally
import com.alibaba.dashscope.utils.Constants;
Constants.baseHttpApiUrl = "https://maas.qwencloudapi.com/api/v1";
OpenAPI
openapi: 3.1.0
info:
title: Qwen DashScope API
description: Call Qwen models using the DashScope native HTTP API. Supports text and multimodal models, streaming, tool calls, and structured output.
version: 1.0.0
servers:
- url: https://maas.qwencloudapi.com
description: Singapore
security:
- ApiKeyAuth: []
paths:
/api/v1/services/aigc/text-generation/generation:
post:
operationId: dashscopeTextGeneration
summary: Text generation
description: |-
Send messages to a Qwen text-only model (such as `qwen-plus`, `qwen-max`) and receive a generated reply. Supports multi-turn chat, streaming, tool calls, structured output, and thinking mode.
For streaming output via HTTP, add the `X-DashScope-SSE: enable` header.
For multimodal models (images, video, audio), use the `/api/v1/services/aigc/multimodal-generation/generation` endpoint.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeTextRequest"
example:
model: qwen-plus
input:
messages:
- role: system
content: You are a helpful assistant.
- role: user
content: Who are you?
parameters:
result_format: message
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeResponse"
example:
status_code: 200
request_id: 902fee3b-f7f0-9a8c-96a1-6b4ea25af114
code: ""
message: ""
output:
text: null
finish_reason: null
choices:
- finish_reason: stop
message:
role: assistant
content: I am a large-scale language model developed by Alibaba Cloud. My name is Qwen.
tool_calls: null
reasoning_content: null
usage:
input_tokens: 22
output_tokens: 17
total_tokens: 39
image_tokens: null
video_tokens: null
audio_tokens: null
"400":
description: Invalid request parameters
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeError"
example:
status_code: 400
request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
code: InvalidParameter
message: The parameter 'model' is required.
"401":
description: Authentication failed
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeError"
example:
status_code: 401
request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
code: InvalidApiKey
message: Invalid API key provided.
"429":
description: Rate limit exceeded
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeError"
example:
status_code: 429
request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
code: Throttling
message: Request was throttled.
x-codeSamples:
- lang: python
label: Text input
source: |-
import os
import dashscope
dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1'
messages = [
{'role': 'system', 'content': 'You are a helpful assistant.'},
{'role': 'user', 'content': 'Who are you?'}
]
response = dashscope.Generation.call(
api_key=os.getenv('DASHSCOPE_API_KEY'),
model='qwen-plus',
messages=messages,
result_format='message'
)
print(response)
- lang: python
label: Streaming (Text)
source: |-
import os
import dashscope
from dashscope import Generation
dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1'
messages = [
{'role': 'system', 'content': 'You are a helpful assistant.'},
{'role': 'user', 'content': 'Who are you?'}
]
responses = Generation.call(
api_key=os.getenv('DASHSCOPE_API_KEY'),
model='qwen-plus',
messages=messages,
result_format='message',
stream=True,
incremental_output=True
)
for response in responses:
print(response.output.choices[0].message.content, end='', flush=True)
print()
- lang: curl
label: Text input
source: |-
curl --location "https://maas.qwencloudapi.com/api/v1/services/aigc/text-generation/generation" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "qwen-plus",
"input": {
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Who are you?"}
]
},
"parameters": {"result_format": "message"}
}'
- lang: curl
label: Streaming (Text)
source: |-
curl --location "https://maas.qwencloudapi.com/api/v1/services/aigc/text-generation/generation" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--header "X-DashScope-SSE: enable" \
--data '{
"model": "qwen-plus",
"input": {
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Who are you?"}
]
},
"parameters": {"result_format": "message", "stream": true, "incremental_output": true}
}'
- lang: java
label: Text input
source: |-
import java.util.Arrays;
import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.protocol.Protocol;
import com.alibaba.dashscope.utils.JsonUtils;
public class Main {
public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException {
Generation gen = new Generation(Protocol.HTTP.getValue(), "https://maas.qwencloudapi.com/api/v1");
Message systemMsg = Message.builder().role(Role.SYSTEM.getValue()).content("You are a helpful assistant.").build();
Message userMsg = Message.builder().role(Role.USER.getValue()).content("Who are you?").build();
GenerationParam param = GenerationParam.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen-plus")
.messages(Arrays.asList(systemMsg, userMsg))
.resultFormat(GenerationParam.ResultFormat.MESSAGE)
.build();
GenerationResult result = gen.call(param);
System.out.println(JsonUtils.toJson(result));
}
}
- lang: java
label: Streaming (Text)
source: |-
import java.util.Arrays;
import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.protocol.Protocol;
import io.reactivex.Flowable;
public class Main {
public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException {
Generation gen = new Generation(Protocol.HTTP.getValue(), "https://maas.qwencloudapi.com/api/v1");
Message systemMsg = Message.builder().role(Role.SYSTEM.getValue()).content("You are a helpful assistant.").build();
Message userMsg = Message.builder().role(Role.USER.getValue()).content("Who are you?").build();
GenerationParam param = GenerationParam.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen-plus")
.messages(Arrays.asList(systemMsg, userMsg))
.resultFormat(GenerationParam.ResultFormat.MESSAGE)
.incrementalOutput(true)
.build();
Flowable<GenerationResult> result = gen.streamCall(param);
result.blockingForEach(r ->
System.out.print(r.getOutput().getChoices().get(0).getMessage().getContent())
);
System.out.println();
}
}
- lang: php
label: Text input
source: |-
<?php
$url = "https://maas.qwencloudapi.com/api/v1/services/aigc/text-generation/generation";
$apiKey = getenv('DASHSCOPE_API_KEY');
$data = [
"model" => "qwen-plus",
"input" => [
"messages" => [
[
"role" => "system",
"content" => "You are a helpful assistant."
],
[
"role" => "user",
"content" => "Who are you?"
]
]
],
"parameters" => [
"result_format" => "message"
]
];
$jsonData = json_encode($data);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer $apiKey",
"Content-Type: application/json"
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($httpCode == 200) {
echo "Response: " . $response;
} else {
echo "Error: " . $httpCode . " - " . $response;
}
curl_close($ch);
?>
- lang: javascript
label: Text input
source: |-
import fetch from 'node-fetch';
const apiKey = process.env.DASHSCOPE_API_KEY;
const data = {
model: "qwen-plus",
input: {
messages: [
{
role: "system",
content: "You are a helpful assistant."
},
{
role: "user",
content: "Who are you?"
}
]
},
parameters: {
result_format: "message"
}
};
fetch('https://maas.qwencloudapi.com/api/v1/services/aigc/text-generation/generation', {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => {
console.log(JSON.stringify(data));
})
.catch(error => {
console.error('Error:', error);
});
- 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)
{
// Replace the line below with string? apiKey = "sk-xxx"; if you have not set the environment variable.
string? apiKey = Environment.GetEnvironmentVariable("DASHSCOPE_API_KEY");
if (string.IsNullOrEmpty(apiKey))
{
Console.WriteLine("API Key is not set. Make sure that the environment variable 'DASHSCOPE_API_KEY' is set.");
return;
}
// Set the request URL and content.
string url = "https://maas.qwencloudapi.com/api/v1/services/aigc/text-generation/generation";
string jsonContent = @"{
""model"": ""qwen-plus"",
""input"": {
""messages"": [
{
""role"": ""system"",
""content"": ""You are a helpful assistant.""
},
{
""role"": ""user"",
""content"": ""Who are you?""
}
]
},
""parameters"": {
""result_format"": ""message""
}
}";
// Send the request and get the response.
string result = await SendPostRequestAsync(url, jsonContent, apiKey);
// Output the result.
Console.WriteLine(result);
}
private static async Task<string> 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);
// Process the response.
if (response.IsSuccessStatusCode)
{
return await response.Content.ReadAsStringAsync();
}
else
{
return $"Request failed: {response.StatusCode}";
}
}
}
}
- lang: go
label: Text input
source: |-
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"log"
"net/http"
"os"
)
type Message struct {
Role string `json:"role"`
Content string `json:"content"`
}
type Input struct {
Messages []Message `json:"messages"`
}
type Parameters struct {
ResultFormat string `json:"result_format"`
}
type RequestBody struct {
Model string `json:"model"`
Input Input `json:"input"`
Parameters Parameters `json:"parameters"`
}
func main() {
// Create an HTTP client.
client := &http.Client{}
// Build the request body.
requestBody := RequestBody{
Model: "qwen-plus",
Input: Input{
Messages: []Message{
{
Role: "system",
Content: "You are a helpful assistant.",
},
{
Role: "user",
Content: "Who are you?",
},
},
},
Parameters: Parameters{
ResultFormat: "message",
},
}
jsonData, err := json.Marshal(requestBody)
if err != nil {
log.Fatal(err)
}
// Create a POST request.
req, err := http.NewRequest("POST", "https://maas.qwencloudapi.com/api/v1/services/aigc/text-generation/generation", bytes.NewBuffer(jsonData))
if err != nil {
log.Fatal(err)
}
// Set the request headers.
// Replace the line below with apiKey := "sk-xxx" if you have not set the environment variable.
apiKey := os.Getenv("DASHSCOPE_API_KEY")
req.Header.Set("Authorization", "Bearer "+apiKey)
req.Header.Set("Content-Type", "application/json")
// Send the request.
resp, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
// Read the response body.
bodyText, err := io.ReadAll(resp.Body)
if err != nil {
log.Fatal(err)
}
// Print the response.
fmt.Printf("%s\n", bodyText)
}
components:
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
description: Your DashScope API key. See [Get API key](/api-reference/preparation/api-key) for details.
schemas:
DashScopeTextRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: The name of the model to call. Supports Qwen large language models (commercial and open-source), Qwen-Coder, and math models. For a list of models, see [Text generation — Qwen](/developer-guides/getting-started/text-generation-models).
example: qwen-plus
input:
type: object
required:
- messages
description: The input to the model.
properties:
messages:
type: array
description: The conversation context, provided as an ordered list of messages. Each message is a system, user, assistant, or tool message object.
items:
$ref: "#/components/schemas/Message"
parameters:
$ref: "#/components/schemas/TextParameters"
DashScopeMultimodalRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: The name of the multimodal model to call, such as `qwen3.7-plus` or `qwen3-vl-plus`.
example: qwen3-vl-plus
input:
type: object
required:
- messages
description: The input to the model.
properties:
messages:
type: array
description: The conversation context. For multimodal models, the user message `content` field is an array of content parts (text, image, video).
items:
$ref: "#/components/schemas/MultimodalMessage"
parameters:
$ref: "#/components/schemas/MultimodalParameters"
Message:
oneOf:
- title: System message
type: object
required:
- role
- content
description: Sets the role, tone, task objective, or constraints for the model. Usually placed first in the messages array. Do not set for QwQ models. Does not take effect for QVQ models.
properties:
role:
type: string
enum:
- system
description: Fixed as `system`.
content:
type: string
description: The system message content that sets context for the model.
- title: User message
type: object
required:
- role
- content
description: Passes questions, instructions, or context to the model.
properties:
role:
type: string
enum:
- user
description: Fixed as `user`.
content:
oneOf:
- type: string
description: Text-only input.
- type: array
description: Array of content parts for multimodal input (image, video, file) or explicit caching.
items:
type: object
properties:
text:
type: string
description: Input text.
image:
type: string
description: "Image as a public URL, base64 (data:image/<format>;base64,<data>), or local file path. Applicable models: Qwen-VL, QVQ. For usage examples, see the [Vision guide](/developer-guides/multimodal/vision)."
video:
oneOf:
- type: string
- type: array
items:
type: string
description: "Video as a file URL (string) or a list of image URLs (array). Applicable models: Qwen-VL, QVQ. For usage examples, see the [Vision guide](/developer-guides/multimodal/vision)."
fps:
type: number
minimum: 0.1
maximum: 10
description: |-
Frames per second to extract from video. Range: [0.1, 10]. Default: 2.0.
The `fps` parameter has two functions:
- **Frame extraction frequency**: When you pass a video file, this parameter controls how often frames are extracted (one frame every 1/fps seconds). Applies to Qwen-VL and QVQ models.
- **Temporal understanding**: It informs the model of the time interval between adjacent frames, helping it understand the video's temporal dynamics. This applies to both video files and image lists and is suitable for event time localization or content summarization by segment. Supported by Qwen3.5, Qwen3-VL, Qwen2.5-VL, and QVQ models.
A larger `fps` value suits high-speed motion scenarios (sports, action movies). A smaller value suits long videos or static content.
max_frames:
type: integer
description: |-
Maximum number of frames to extract from the video. If calculated frames exceed this limit, the system evenly samples to stay within it.
**Default and maximum values by model:**
- qwen3.5 series, qwen3-vl-plus series: **2000**
When using the OpenAI-compatible API, you cannot customize `max_frames`. The API automatically uses the default value for each model.
min_pixels:
type: integer
description: |-
Minimum pixel count for an input image or video frame. Images below this threshold are enlarged.
**Default values by model:**
For **image input**:
- Qwen3.5, Qwen3-VL: minimum and default = **65536**
- Qwen2.5-VL open source series, QVQ series: minimum and default = **3136**
For **video input** (video file or image list):
- Qwen3.5, Qwen3-VL (commercial and open source): default = **65536**, minimum = **4096**
- Qwen2.5-VL open source series, QVQ series: default = **50176**, minimum = **3136**
max_pixels:
type: integer
description: |-
Maximum pixel count for an input image or video frame. Images within [min_pixels, max_pixels] are processed at original resolution. Images exceeding max_pixels are scaled down.
**For image input** (depends on `vl_high_resolution_images`):
When `vl_high_resolution_images` is **false**:
- Qwen3.5, Qwen3-VL: default = **2621440**, maximum = **16777216**
- Qwen2.5-VL open source series, QVQ series: default = **1003520**, maximum = **12845056**
When `vl_high_resolution_images` is **true**:
- Qwen3.5, Qwen3-VL: max_pixels is **ignored**, fixed at **16777216**
- Qwen2.5-VL open source series, QVQ series: max_pixels is **ignored**, fixed at **12845056**
**For video input** (video file or image list):
- qwen3.5 series, qwen3-vl-plus series: default = **655360**, maximum = **2048000**
- Other Qwen3-VL open source models: default = **655360**, maximum = **786432**
- Qwen2.5-VL open source series, QVQ series: default = **501760**, maximum = **602112**
total_pixels:
type: integer
description: |-
Maximum total pixel count for all video frames combined, calculated as (pixel count per frame) × (total number of frames). If exceeded, frames are scaled down while keeping single-frame pixels within [min_pixels, max_pixels]. Applies to Qwen-VL and QVQ models. Reduce this value for long videos to decrease token consumption.
**Default values by model:**
- qwen3.5 series, qwen3-vl-plus series: **134217728** (corresponds to 131072 image tokens, 1 token per 32×32 pixels)
- Other Qwen3-VL open source models: **67108864** (corresponds to 65536 image tokens, 1 token per 32×32 pixels)
- Qwen2.5-VL open source series, QVQ series: **51380224** (corresponds to 65536 image tokens, 1 token per 28×28 pixels)
file:
type: string
description: "Document as a public URL (PDF, DOCX, etc.). Applicable models: Qwen-VL."
cache_control:
type: object
description: Enables explicit caching. Only supported by models with explicit caching feature.
properties:
type:
type: string
enum:
- ephemeral
description: The message content. String for text-only input; array for multimodal input (image, video, file) or explicit caching.
- title: Assistant message
type: object
required:
- role
description: The model's reply to the user message.
properties:
role:
type: string
enum:
- assistant
description: Fixed as `assistant`.
content:
type: string
nullable: true
description: The message content. Not required if `tool_calls` is present.
tool_calls:
type: array
description: The tool calls the model wants to make. Contains one or more tool call objects from the previous model response.
items:
$ref: "#/components/schemas/ToolCall"
partial:
type: boolean
description: Whether to enable prefix continuation. See [Prefix Continuation](/developer-guides/text-generation/partial-mode) for supported models.
- title: Tool message
type: object
required:
- role
- content
description: The output of a tool function call.
properties:
role:
type: string
enum:
- tool
description: Fixed as `tool`.
content:
type: string
description: The tool function output. Must be a string.
tool_call_id:
type: string
description: The ID of the tool call this message responds to. Get it from `response.output.choices[0].message.tool_calls[$index].id`.
MultimodalMessage:
oneOf:
- title: User message
type: object
required:
- role
- content
description: Passes questions, instructions, or context to the model with multimodal content.
properties:
role:
type: string
enum:
- user
description: Fixed as `user`.
content:
type: array
description: An array of content parts. Each part can contain text, image, video, file, or cache_control properties.
items:
type: object
properties:
text:
type: string
description: Input text.
image:
type: string
description: "Image as a public URL, base64 (data:image/<format>;base64,<data>), or local file path. Applicable models: Qwen-VL, QVQ. For usage examples, see the [Vision guide](/developer-guides/multimodal/vision)."
video:
oneOf:
- type: string
- type: array
items:
type: string
description: "Video as a file URL (string) or a list of image URLs (array). Applicable models: Qwen-VL, QVQ. For usage examples, see the [Vision guide](/developer-guides/multimodal/vision)."
fps:
type: number
minimum: 0.1
maximum: 10
description: |-
Frames per second to extract from video. Range: [0.1, 10]. Default: 2.0.
The `fps` parameter has two functions:
- **Frame extraction frequency**: When you pass a video file, this parameter controls how often frames are extracted (one frame every 1/fps seconds). Applies to Qwen-VL and QVQ models.
- **Temporal understanding**: It informs the model of the time interval between adjacent frames, helping it understand the video's temporal dynamics. This applies to both video files and image lists and is suitable for event time localization or content summarization by segment. Supported by Qwen3.5, Qwen3-VL, Qwen2.5-VL, and QVQ models.
A larger `fps` value suits high-speed motion scenarios (sports, action movies). A smaller value suits long videos or static content.
max_frames:
type: integer
description: |-
Maximum number of frames to extract from the video. If calculated frames exceed this limit, the system evenly samples to stay within it.
**Default and maximum values by model:**
- qwen3.5 series, qwen3-vl-plus series: **2000**
When using the OpenAI-compatible API, you cannot customize `max_frames`. The API automatically uses the default value for each model.
min_pixels:
type: integer
description: |-
Minimum pixel count for an input image or video frame. Images below this threshold are enlarged.
**Default values by model:**
For **image input**:
- Qwen3.5, Qwen3-VL: minimum and default = **65536**
- Qwen2.5-VL open source series, QVQ series: minimum and default = **3136**
For **video input** (video file or image list):
- Qwen3.5, Qwen3-VL (commercial and open source): default = **65536**, minimum = **4096**
- Qwen2.5-VL open source series, QVQ series: default = **50176**, minimum = **3136**
max_pixels:
type: integer
description: |-
Maximum pixel count for an input image or video frame. Images within [min_pixels, max_pixels] are processed at original resolution. Images exceeding max_pixels are scaled down.
**For image input** (depends on `vl_high_resolution_images`):
When `vl_high_resolution_images` is **false**:
- Qwen3.5, Qwen3-VL: default = **2621440**, maximum = **16777216**
- Qwen2.5-VL open source series, QVQ series: default = **1003520**, maximum = **12845056**
When `vl_high_resolution_images` is **true**:
- Qwen3.5, Qwen3-VL: max_pixels is **ignored**, fixed at **16777216**
- Qwen2.5-VL open source series, QVQ series: max_pixels is **ignored**, fixed at **12845056**
**For video input** (video file or image list):
- qwen3.5 series, qwen3-vl-plus series: default = **655360**, maximum = **2048000**
- Other Qwen3-VL open source models: default = **655360**, maximum = **786432**
- Qwen2.5-VL open source series, QVQ series: default = **501760**, maximum = **602112**
total_pixels:
type: integer
description: |-
Maximum total pixel count for all video frames combined, calculated as (pixel count per frame) × (total number of frames). If exceeded, frames are scaled down while keeping single-frame pixels within [min_pixels, max_pixels]. Applies to Qwen-VL and QVQ models. Reduce this value for long videos to decrease token consumption.
**Default values by model:**
- qwen3.5 series, qwen3-vl-plus series: **134217728** (corresponds to 131072 image tokens, 1 token per 32×32 pixels)
- Other Qwen3-VL open source models: **67108864** (corresponds to 65536 image tokens, 1 token per 32×32 pixels)
- Qwen2.5-VL open source series, QVQ series: **51380224** (corresponds to 65536 image tokens, 1 token per 28×28 pixels)
file:
type: string
description: "Document as a public URL (PDF, DOCX, etc.). Applicable models: Qwen-VL."
cache_control:
type: object
description: Enables explicit caching. Only supported by models with explicit caching feature.
properties:
type:
type: string
enum:
- ephemeral
- title: Assistant message
type: object
required:
- role
description: The model's reply to the user message.
properties:
role:
type: string
enum:
- assistant
description: Fixed as `assistant`.
content:
type: array
description: An array of content parts from the model's response.
items:
oneOf:
- title: Text
type: object
properties:
text:
type: string
description: Input text.
- title: Image
type: object
properties:
image:
type: string
description: "Image as a public URL, base64 (data:image/<format>;base64,<data>), or local file path. Applicable models: Qwen-VL, QVQ. For usage examples, see the [Vision guide](/developer-guides/multimodal/vision)."
- title: Video
type: object
properties:
video:
oneOf:
- type: string
- type: array
items:
type: string
description: "Video as a file URL (string) or a list of image URLs (array). Applicable models: Qwen-VL, QVQ. For usage examples, see the [Vision guide](/developer-guides/multimodal/vision)."
fps:
type: number
minimum: 0.1
maximum: 10
description: |-
Frames per second to extract from video. Range: [0.1, 10]. Default: 2.0.
The `fps` parameter has two functions:
- **Frame extraction frequency**: When you pass a video file, this parameter controls how often frames are extracted (one frame every 1/fps seconds). Applies to Qwen-VL and QVQ models.
- **Temporal understanding**: It informs the model of the time interval between adjacent frames, helping it understand the video's temporal dynamics. This applies to both video files and image lists and is suitable for event time localization or content summarization by segment. Supported by Qwen3.5, Qwen3-VL, Qwen2.5-VL, and QVQ models.
A larger `fps` value suits high-speed motion scenarios (sports, action movies). A smaller value suits long videos or static content.
max_frames:
type: integer
description: |-
Maximum number of frames to extract from the video. If calculated frames exceed this limit, the system evenly samples to stay within it.
**Default and maximum values by model:**
- qwen3.5 series, qwen3-vl-plus series: **2000**
When using the OpenAI-compatible API, you cannot customize `max_frames`. The API automatically uses the default value for each model.
min_pixels:
type: integer
description: |-
Minimum pixel count for an input image or video frame. Images below this threshold are enlarged.
**Default values by model:**
For **image input**:
- Qwen3.5, Qwen3-VL: minimum and default = **65536**
- Qwen2.5-VL open source series, QVQ series: minimum and default = **3136**
For **video input** (video file or image list):
- Qwen3.5, Qwen3-VL (commercial and open source): default = **65536**, minimum = **4096**
- Qwen2.5-VL open source series, QVQ series: default = **50176**, minimum = **3136**
max_pixels:
type: integer
description: |-
Maximum pixel count for an input image or video frame. Images within [min_pixels, max_pixels] are processed at original resolution. Images exceeding max_pixels are scaled down.
**For image input** (depends on `vl_high_resolution_images`):
When `vl_high_resolution_images` is **false**:
- Qwen3.5, Qwen3-VL: default = **2621440**, maximum = **16777216**
- Qwen2.5-VL open source series, QVQ series: default = **1003520**, maximum = **12845056**
When `vl_high_resolution_images` is **true**:
- Qwen3.5, Qwen3-VL: max_pixels is **ignored**, fixed at **16777216**
- Qwen2.5-VL open source series, QVQ series: max_pixels is **ignored**, fixed at **12845056**
**For video input** (video file or image list):
- qwen3.5 series, qwen3-vl-plus series: default = **655360**, maximum = **2048000**
- Other Qwen3-VL open source models: default = **655360**, maximum = **786432**
- Qwen2.5-VL open source series, QVQ series: default = **501760**, maximum = **602112**
total_pixels:
type: integer
description: |-
Maximum total pixel count for all video frames combined, calculated as (pixel count per frame) × (total number of frames). If exceeded, frames are scaled down while keeping single-frame pixels within [min_pixels, max_pixels]. Applies to Qwen-VL and QVQ models. Reduce this value for long videos to decrease token consumption.
**Default values by model:**
- qwen3.5 series, qwen3-vl-plus series: **134217728** (corresponds to 131072 image tokens, 1 token per 32×32 pixels)
- Other Qwen3-VL open source models: **67108864** (corresponds to 65536 image tokens, 1 token per 32×32 pixels)
- Qwen2.5-VL open source series, QVQ series: **51380224** (corresponds to 65536 image tokens, 1 token per 28×28 pixels)
- title: File
type: object
properties:
file:
type: string
description: "Document as a public URL (PDF, DOCX, etc.). Applicable models: Qwen-VL."
cache_control:
type: object
description: Enables explicit caching. Only supported by models with explicit caching feature.
properties:
type:
type: string
enum:
- ephemeral
partial:
type: boolean
description: Whether to enable prefix continuation. See Prefix Continuation for supported models.
ToolCall:
type: object
properties:
id:
type: string
description: The ID of the tool call.
type:
type: string
enum:
- function
description: The type of tool. Currently only `function` is supported.
function:
type: object
properties:
name:
type: string
description: The name of the tool function.
arguments:
type: string
description: The input parameters for the tool, as a JSON string.
index:
type: integer
description: The index of this tool call in the tool_calls array.
TextParameters:
type: object
description: Optional generation parameters for text models.
properties:
result_format:
type: string
enum:
- message
- text
default: text
description: |-
The format of the returned data. Set to `message` for multi-turn conversations.
**Default values:** `text` for most models, except Qwen3-VL, QwQ, and Qwen3 open source models, which default to `message`.
When the model is Qwen-VL/QVQ, setting `text` has no effect. For Qwen3-VL and Qwen3 models in thinking mode, this can only be set to `message`.
temperature:
type: number
minimum: 0
exclusiveMaximum: 2
description: |-
Sampling temperature. Controls output diversity. Higher values produce more diverse output; lower values produce more deterministic output. Range: [0, 2).
Do not modify the default temperature value for QVQ models.
top_p:
type: number
exclusiveMinimum: 0
maximum: 1
description: |-
Nucleus sampling threshold. Higher values produce more diverse output. Range: (0, 1.0].
**Default values by model:**
- Qwen3.5 (non-thinking), Qwen3 (non-thinking), Qwen3-Instruct series, Qwen3-Coder series, qwen-max series, qwen-plus series (non-thinking), qwen-flash series (non-thinking), qwen open source series, Qwen3-VL (non-thinking): **0.8**
- qwen2.5-vl-3b/7b/32b/72b-instruct: **0.001**
- QVQ series: **0.5**
- Qwen3-Omni-Flash series: **1.0**
- Qwen3.5 (thinking), Qwen3 (thinking), Qwen3-VL (thinking), Qwen3-Thinking, QwQ series, Qwen3-Omni-Captioner: **0.95**
Do not modify the default `top_p` value for QVQ models.
top_k:
type: integer
minimum: 0
description: |-
The size of the candidate token set for sampling. A larger value increases randomness; a smaller value increases determinism. If `None` or greater than 100, top_k is disabled and only top_p takes effect. Must be >= 0.
**Default values by model:**
- QVQ series: **10**
- QwQ series: **40**
- Qwen3-Omni-Flash series: **50**
- All other models: **20**
Do not modify the default `top_k` value for QVQ models.
max_tokens:
type: integer
description: |-
**Deprecated.** Use `max_completion_tokens` for new integrations.
The meaning of this parameter varies by model:
- **deepseek-v4.1-flash, 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 the `thinking_budget` parameter 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 the `thinking_budget` parameter is passed, `max_tokens` is the maximum number of tokens for the model's answer only, and the chain-of-thought length 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`.
The default and maximum values are both the model's maximum output length.
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`. The default and maximum values correspond to the model's maximum output length.
**Difference from `max_tokens`:** `max_completion_tokens` limits the total length of both the chain-of-thought and the final response, while `max_tokens` does not limit the chain-of-thought length. 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
- DeepSeek: deepseek-v4-pro-0813, deepseek-v4-pro, deepseek-v4.1-flash and later
The actual number of output tokens may differ from the configured value by up to 10 tokens.
For HTTP calls, place `max_completion_tokens` in the `parameters` field.
stream:
type: boolean
default: false
description: "Whether to stream the response. For HTTP streaming, also set the `X-DashScope-SSE: enable` header. For Java SDK streaming, use the `streamCall` interface."
incremental_output:
type: boolean
default: false
description: When streaming, whether to return only the new delta tokens (true) or the full accumulated text so far (false).
enable_thinking:
type: boolean
description: "Whether to enable thinking mode. Applies to hybrid thinking models: Qwen3.7, Qwen3.6, Qwen3.5, Qwen3, and Qwen3-VL series, as well as the DeepSeek-V4-Pro/V4-Flash series, Kimi-K2.6/K2.5 series, and GLM series. qwen3.8-max and qwen3.8-max-0902 enable thinking mode by default. When enabled, thinking content is returned in the `reasoning_content` field."
thinking_budget:
type: integer
description: Maximum length of the thinking chain. Applies to Qwen3.7, Qwen3.6, Qwen3.5, Qwen3-VL, Qwen3, GLM, and Kimi models. Default is the model's maximum chain-of-thought length.
preserve_thinking:
type: boolean
default: false
description: |-
Whether to append the `reasoning_content` from assistant messages in the conversation history to the model input. Useful when the model needs to refer to the historical thinking process.
Currently supported by: qwen3.8-max (enabled by default), qwen3.8-max-0902 (enabled by default), qwen3.8-flash, 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, kimi-k2.7-code-highspeed, and kimi-k2.7-code.
- If the historical messages do not contain `reasoning_content`, enabling this parameter does not cause an error.
- When enabled, the `reasoning_content` from the conversation history is included in the input token count and is billed.
For HTTP calls, place `preserve_thinking` in the `parameters` object.
**Important:** When using qwen3.8-max, preserve_thinking defaults to true. You must pass back the complete reasoning_content from all historical assistant messages. Concatenating reasoning_content into the content field is not supported.
reasoning_effort:
type: string
description: |-
Controls model reasoning effort.
**Qwen3.8 series:** 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`.
**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, and kimi-k3 (default `max`, only supports `max`).
**glm-5.3:** Default value: `max`. Valid values: `low` (light inference), `high` (enhanced inference), `max` (deep inference). This model always thinks. `enable_thinking` supports only `true`; passing `false` causes the API request to fail.
**deepseek-v4-flash-0731, deepseek-v4-pro-0813, and deepseek-v4.1-flash:** 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.
Pass reasoning_effort inside the parameters object when calling via HTTP.
tool_stream:
type: boolean
default: false
description: |-
Controls streaming behavior for complex tool arguments. Only takes effect in streaming mode. This parameter only affects the streaming output behavior of complex tool parameters. Simple tool parameters, where all parameter types are strings, can be streamed as long as streaming calls are enabled; `tool_stream` has no effect on them. Complex tools are tools where some parameter types in the tool definition are arrays or objects.
**Supported Qwen models:**
- qwen-max series: text modality of the 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.
For HTTP calls, place `tool_stream` in the `parameters` object.
enable_code_interpreter:
type: boolean
default: false
description: Whether to enable the code interpreter feature. For more information, see Code interpreter.
clear_thinking:
type: boolean
default: false
description: |-
Controls whether to use the `reasoning_content` (thinking process) from previous turns as context input for the model in a multi-turn conversation. Supported only by GLM series models: glm-5.3, glm-5.2, glm-5.1, glm-5, and glm-4.7. 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, and results as context input. This can reduce context length and cost.
- `false` (default): Retains the `reasoning_content` from previous turns and provides it to the model along with the context.
repetition_penalty:
type: number
description: |-
Penalty for token repetition. A value of 1.0 means no penalty. Higher values reduce repetition. Must be a positive number.
Do not modify the default `repetition_penalty` value for QVQ models.
presence_penalty:
type: number
minimum: -2
maximum: 2
description: |-
Controls how much the model avoids repeating content already present in the text. Range: [-2.0, 2.0]. Positive values reduce repetition; negative values increase it.
**Default values by model:**
- Qwen3.8 (non-thinking), Qwen3.5 (non-thinking), Qwen3 (non-thinking), Qwen3-Instruct series, qwen3-0.6b/1.7b/4b (thinking), 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): **0.5**
- All other models: **0.0**
Do not modify the default for QVQ models.
seed:
type: integer
minimum: 0
description: "Random seed for reproducible results. Range: [0, 2³¹−1]. With the same seed and parameters, the model returns the same result whenever possible."
stop:
oneOf:
- type: string
- type: array
items:
oneOf:
- type: string
- type: integer
description: Stop sequences. When the generated text contains a specified string or token ID, generation stops immediately. Do not mix strings and token IDs in the same array. Not supported by all models; check model documentation.
tools:
type: array
description: An array of tool objects for function calling. When using tools, you must set `result_format` to `message`. Not supported by qwen-vl series models. 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: The type of tool. Currently only `function` is supported.
function:
type: object
required:
- name
- description
properties:
name:
type: string
description: The name of the tool function. Can contain letters, numbers, underscores, and hyphens. Maximum 64 characters.
description:
type: string
description: A description of the tool function that helps the model decide when and how to call it.
parameters:
type: object
description: A JSON Schema object describing the function parameters. Defaults to `{}`.
tool_choice:
oneOf:
- type: string
enum:
- auto
- none
- required
description: "`auto`: The model autonomously selects the tool strategy. `none`: Disable all tool calls for this request. `required`: Force 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."
- type: object
description: 'Force a specific tool call: `{"type": "function", "function": {"name": "the_function_to_call"}}`.'
default: auto
description: Defines the tool selection strategy. Thinking mode models do not support forcing a specific tool.
parallel_tool_calls:
type: boolean
default: false
description: Whether to enable parallel tool calls. Not supported by thinking mode models when forcing a specific tool. See [Parallel tool calls](/developer-guides/text-generation/function-calling).
response_format:
type: object
default:
type: text
description: The format of the returned content. If set to `json_object`, you must instruct the model to output JSON in the prompt.
properties:
type:
type: string
enum:
- text
- json_object
- json_schema
description: "The output format type. `text`: plain text. `json_object`: standard JSON string. `json_schema`: JSON matching the provided schema."
json_schema:
type: object
description: Required when `type` is `json_schema`. Defines the JSON Schema for structured output. For supported models, see [Structured output](/developer-guides/text-generation/structured-output).
properties:
name:
type: string
description: Unique schema name (letters, numbers, underscores, hyphens; max 64 characters).
description:
type: string
description: Description of the schema's purpose.
schema:
type: object
description: A JSON Schema object defining the output data structure.
strict:
type: boolean
default: false
description: Whether the model must strictly adhere to all schema constraints. `true` is recommended.
logprobs:
type: boolean
default: false
description: "Whether to return log probabilities of the output tokens. Supported by: snapshot models of qwen-plus series; qwen3-vl-plus series; Qwen3 open source models. See model page for supported models."
top_logprobs:
type: integer
minimum: 0
maximum: 5
default: 0
description: "Number of most likely candidate tokens to return at each generation step. Valid values: 0–5. Only takes effect when `logprobs` is `true`. Supported by the same models as `logprobs`."
n:
type: integer
minimum: 1
maximum: 4
default: 1
description: "The number of responses to generate. Range: 1–4. Currently only non-thinking mode Qwen3 models are supported. Fixed at 1 when `tools` is specified. Increases output token consumption."
vl_high_resolution_images:
type: boolean
default: false
description: |-
Whether to enable high-resolution image processing. When enabled, uses a fixed-resolution strategy where `max_pixels` is ignored. Default: false.
**Pixel limits when enabled (true):**
- Qwen3.5 series, Qwen3-VL series: fixed at **16777216** pixels (16384 tokens × 32×32 pixels)
- QVQ series and other Qwen2.5-VL series: fixed at **12845056** pixels (16384 tokens × 28×28 pixels)
When `false`, the pixel limit is determined by `max_pixels`.
vl_enable_image_hw_output:
type: boolean
default: false
description: Whether to return the dimensions of the scaled image in the response (`image_hw` field). When streaming, returned in the last chunk. Applies to Qwen-VL series models.
MultimodalParameters:
type: object
description: Optional generation parameters for multimodal models.
properties:
result_format:
type: string
enum:
- message
default: message
description: The format of returned data. For multimodal models, only `message` is supported.
temperature:
type: number
minimum: 0
exclusiveMaximum: 2
description: "Sampling temperature. Controls output diversity. Range: [0, 2). Do not modify the default temperature value for QVQ models."
top_p:
type: number
exclusiveMinimum: 0
maximum: 1
description: |-
Nucleus sampling threshold. Range: (0, 1.0].
**Default values by model:**
- Qwen3.5 (non-thinking), Qwen3-VL (non-thinking): **0.8**
- qwen2.5-vl-3b/7b/32b/72b-instruct: **0.001**
- QVQ series: **0.5**
- Qwen3.5 (thinking), Qwen3-VL (thinking): **0.95**
Do not modify the default `top_p` value for QVQ models.
top_k:
type: integer
minimum: 0
description: |-
The size of the candidate token set for sampling. Must be >= 0.
**Default values by model:**
- QVQ series: **10**
- All other models: **20**
Do not modify the default `top_k` value for QVQ models.
max_tokens:
type: integer
description: |-
**Deprecated.** Use `max_completion_tokens` for new integrations.
The maximum length of the model's answer, which excludes chain-of-thought content.
**Note:** For GLM-5.2 and later GLM series models, `max_tokens` behaves the same as `max_completion_tokens` — it limits the total output length including the chain-of-thought, not just the final response. We recommend using `max_completion_tokens` directly with GLM-5.2 series models for more semantically explicit control.
deprecated: true
max_completion_tokens:
type: integer
description: |-
The maximum number of tokens in this response, including chain-of-thought tokens. For reasoning models, `max_completion_tokens` is recommended over `max_tokens`.
For HTTP calls, place `max_completion_tokens` in the `parameters` field.
stream:
type: boolean
default: false
description: "Whether to stream the response. For HTTP streaming, also set the `X-DashScope-SSE: enable` header."
enable_thinking:
type: boolean
description: Whether to enable thinking mode for hybrid thinking models (Qwen3-VL). Thinking content is returned in `reasoning_content`.
thinking_budget:
type: integer
description: Maximum length of the thinking chain for Qwen3-VL models.
repetition_penalty:
type: number
description: |-
Penalty for token repetition. Must be a positive number. A value of 1.0 means no penalty.
Do not modify the default `repetition_penalty` value for QVQ models.
vl_high_resolution_images:
type: boolean
default: false
description: |-
Whether to enable high-resolution image processing. When enabled, uses a fixed-resolution strategy where `max_pixels` is ignored. Default: false.
**Pixel limits when enabled (true):**
- Qwen3.5 series, Qwen3-VL series: fixed at **16777216** pixels
- QVQ series and other Qwen2.5-VL series: fixed at **12845056** pixels
When `false`, the pixel limit is determined by `max_pixels`.
vl_enable_image_hw_output:
type: boolean
default: false
description: Whether to return image height and width information in the response (`image_hw` field). Applies to Qwen-VL series models.
seed:
type: integer
minimum: 0
description: "Random seed for reproducible results. Range: [0, 2³¹−1]."
incremental_output:
type: boolean
default: false
description: When streaming, whether to return only the new delta tokens (true) or the full accumulated text so far (false).
stop:
oneOf:
- type: string
- type: array
items:
oneOf:
- type: string
- type: integer
description: Stop sequences. When the generated text contains a specified string or token ID, generation stops immediately. Do not mix strings and token IDs in the same array.
presence_penalty:
type: number
minimum: -2
maximum: 2
description: |-
Controls how much the model avoids repeating content. Range: [-2.0, 2.0]. Positive values reduce repetition; negative values increase it.
**Default values by model:**
- Qwen3.5 (non-thinking), QVQ series, Qwen3-VL (non-thinking), qwen2.5-vl series: **1.5**
- All other models: **0.0**
Do not modify the default for QVQ models.
logprobs:
type: boolean
default: false
description: Whether to return log probabilities of the output tokens. Supported by qwen3-vl-plus series (stable models included), and Qwen3 open source models.
top_logprobs:
type: integer
minimum: 0
maximum: 5
default: 0
description: "Number of most likely candidate tokens to return at each generation step. Valid values: 0–5. Only takes effect when `logprobs` is `true`."
DashScopeResponse:
type: object
properties:
status_code:
type: integer
description: The status code of the request. `200` indicates success. The Java SDK does not return this field; if a call fails, an exception is thrown containing the status_code.
request_id:
type: string
description: A unique identifier for this request. In the Java SDK, this is `requestId`.
code:
type: string
description: The error code. Empty string if the request was successful. Only the Python SDK returns this field.
message:
type: string
description: A human-readable error message. Empty string if the request was successful.
output:
type: object
description: The model's output.
properties:
text:
type: string
nullable: true
description: The generated text. Returned when `result_format` is `text`.
finish_reason:
type: string
nullable: true
description: "The reason generation stopped. Returned when `result_format` is `text`. Values: `null` (still generating), `stop` (natural end or stop condition triggered), `length` (max tokens reached), `tool_calls` (tool call triggered)."
choices:
type: array
description: The output choices. Returned when `result_format` is `message`.
items:
type: object
properties:
finish_reason:
type: string
nullable: true
description: "The reason generation stopped. Values: `null` (generating), `stop`, `length`, `tool_calls`."
message:
type: object
description: The assistant's output message.
properties:
role:
type: string
description: Always `assistant`.
content:
oneOf:
- type: string
- type: array
items:
type: object
properties:
text:
type: string
description: The output text content for Qwen-VL or Qwen-Audio models.
image_hw:
type: array
items:
type: integer
description: "Returned when `vl_enable_image_hw_output` is enabled. For image input: [height, width] in pixels. For video input: empty array."
description: Array items for Qwen-VL/Qwen-Audio output. Each item may contain `text` (string) and `image_hw` (array of [height, width] in pixels, returned when `vl_enable_image_hw_output` is enabled).
nullable: true
description: The message content. A string for text models; an array for Qwen-VL/Qwen-Audio models. Empty when `tool_calls` is present.
reasoning_content:
type: string
nullable: true
description: The deep thinking content. Returned when thinking mode is enabled.
tool_calls:
type: array
nullable: true
description: Tool calls the model wants to make. Present when the model triggers a function call.
items:
$ref: "#/components/schemas/ToolCall"
logprobs:
type: object
nullable: true
description: Log probability information for this choice. Returned when `logprobs` is `true`.
properties:
content:
type: array
description: An array of tokens with log probability information.
items:
type: object
properties:
token:
type: string
bytes:
type: array
items:
type: integer
logprob:
type: number
nullable: true
top_logprobs:
type: array
items:
type: object
properties:
token:
type: string
bytes:
type: array
items:
type: integer
logprob:
type: number
nullable: true
usage:
type: object
description: Token usage information for this request.
properties:
input_tokens:
type: integer
description: Number of tokens in the user input.
output_tokens:
type: integer
description: Number of tokens in the model output.
total_tokens:
type: integer
description: Total tokens (input + output). Returned for plain text input.
image_tokens:
type: integer
nullable: true
description: Number of tokens in the input image. Returned when the input includes an image.
video_tokens:
type: integer
nullable: true
description: Number of tokens in the input video. Returned when the input includes a video.
audio_tokens:
type: integer
nullable: true
description: Number of tokens in the input audio. Returned when the input includes audio.
input_tokens_details:
type: object
description: Detailed input token breakdown for Qwen-VL and QVQ models.
properties:
text_tokens:
type: integer
image_tokens:
type: integer
video_tokens:
type: integer
output_tokens_details:
type: object
description: Detailed output token breakdown.
properties:
text_tokens:
type: integer
description: Number of tokens in the output text.
reasoning_tokens:
type: integer
description: Number of tokens in the thinking process.
prompt_tokens_details:
type: object
description: Fine-grained classification of input tokens.
properties:
cached_tokens:
type: integer
description: Number of tokens that hit the cache. See [Context cache](/developer-guides/text-generation/context-cache).
cache_creation_input_tokens:
type: integer
description: Number of tokens used to create the explicit cache.
cache_type:
type: string
description: If explicit caching is used, the value is `ephemeral`. Otherwise not returned.
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 a 5-minute explicit cache.
DashScopeError:
type: object
properties:
status_code:
type: integer
description: HTTP status code.
request_id:
type: string
description: Unique request identifier for troubleshooting.
code:
type: string
description: Machine-readable error code.
message:
type: string
description: Human-readable error message.