For scenarios that do not require real-time responses, such as data annotation and content generation, real-time inference APIs suffer from high costs and limited concurrency. The Batch Chat API of Alibaba Cloud Model Studio retains the same synchronous invocation style as the real-time API—you simply send a request and wait for the final result to be returned. This feature currently enjoys a limited-time 50% discount on the official website, directly reducing your inference costs by 50%.
This interface only supports submitting a single request. To submit multiple requests at once, you can submit them via a file. For details, see OpenAI-compatible-Batch (file input).
How it works
-
Request submission: The client sends a request and establishes a connection.
-
Connection maintenance: The request enters a queue, and the client keeps the connection open while waiting.
-
Synchronous return: Once the request has been processed, the server returns the complete result to the client in one pass over the previously held connection.
If the maximum waiting time is exceeded, the connection is automatically closed and a timeout error is returned.
Scope
China (Beijing)
- Text generation models: qwen4-max, qwen3.8-max, qwen3.8-flash, qwen3.7-max, qwen3.7-plus, qwen3.6-plus, qwen3.7-flash, qwen3.6-flash, qwen3.5-plus, qwen3.5-flash, qwen-plus, qwen-flash
- Image and video understanding models: qwen4-max, qwen3.8-max, qwen3.8-flash, qwen3.7-plus, qwen3.6-plus, qwen3.7-flash, qwen3.6-flash, qwen3.5-plus, qwen3.5-flash, qwen3.5-omni-plus, qwen3.5-omni-flash, qwen3-vl-plus
Important
- In Batch scenarios,
qwen3.8-max,qwen3.8-flash,qwen3.7-max,qwen3.7-plus,qwen3.6-plus,qwen3.7-flash,qwen3.6-flash,qwen3.5-plus,qwen3.5-flash,qwen3.5-omni-flash, andqwen3.5-omni-plussupport a maximum of 256K context tokens per request;qwen3.5-omni-plusandqwen3.5-omni-flashdo not support audio output. - Some models support the thinking mode; when enabled, it produces thinking
tokens, which increases costs. - The
qwen3.8,qwen3.7,qwen3.6, andqwen3.5series models have the thinking mode enabled by default. When using hybrid-thinking models, we recommend explicitly setting theenable_thinkingparameter (trueto enable /falseto disable). - In the JSONL request body,
enable_thinkingis a top-level parameter ofbodyand must be passed at the same level asmodel; it cannot be placed insideextra_body.
How to use
Prerequisites
-
You have activated the Alibaba Cloud Model Studio service and obtained an API Key.
We recommend configuring your API Key in environment variables to reduce the risk of API Key leakage.
-
If you make calls through the OpenAI SDK, you need to install the SDK.
pip3 install -U openai
Step 1: Configure the API endpoint
Simply change the API endpoint (base_url) to easily switch your existing real-time inference requests to batch inference. Configure the correct API endpoint according to your invocation method.
SDK configuration: Set base_url to https://batch.dashscope.aliyuncs.com/compatible-mode/v1
HTTP invocation: The request endpoint is POST https://batch.dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
Step 2: Make the call
This section uses a text conversation as an example to show how to call the Batch Chat API.
The default waiting timeout for a request is 3600 seconds (1 hour); in most cases, no additional configuration is required.
The following example shows how to proactively set a custom timeout (60-3600 seconds) for reference.
Python
Sample requestimport os
from openai import OpenAI
client = OpenAI(
# 若没有配置环境变量,可用阿里云百炼API Key将下行替换为:api_key="sk-xxx",但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险.
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://batch.dashscope.aliyuncs.com/compatible-mode/v1", # 阿里云百炼Batch chat API 的 URL
).with_options(timeout=1800.0) # 设置1800秒(30分钟)的等待时间,最长3600秒
completion = client.chat.completions.create(
model="qwen-plus",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "你是谁?"},
]
)
print(completion.choices[0].message.content)
Sample response我是千问,阿里巴巴集团旗下的超大规模语言模型。我能够回答问题、创作文字,比如写故事、写公文、写邮件、写剧本、逻辑推理、编程等等,还能表达观点,玩游戏等。如果你有任何问题或需要帮助,欢迎随时告诉我!
Java
Sample requestimport com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
import java.time.Duration;
public class Main {
public static void main(String[] args) {
OpenAIClient client = OpenAIOkHttpClient.builder()
// 若没有配置环境变量,可用百炼API Key将下行替换为:.apiKey("sk-xxx")。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.baseUrl("https://batch.dashscope.aliyuncs.com/compatible-mode/v1") // # 阿里云百炼Batch chat API 的 URL
.timeout(Duration.ofSeconds(1800)) // 设置等待时间1800秒(半小时),最长3600秒
.build();
ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
.addUserMessage("你是谁")
.model("qwen-plus")
.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();
}
}
}
Sample responseChatCompletion{id=chatcmpl-a12c115e-15fc-94f9-a984-81bd65f0527b, choices=[Choice{finishReason=stop, index=0, logprobs=, message=ChatCompletionMessage{
content=我是千问,阿里巴巴集团旗下的超大规模语言模型。我可以帮助你回答问题、创作文字、提供信息查询等服务。很高兴认识你!, refusal=, role=assistant, annotations=, audio=, functionCall=, toolCalls=, additionalProperties={}}, additionalProperties={}}], created=1763609020, model=qwen-plus, object_=chat.completion, serviceTier=, systemFingerprint=, usage=CompletionUsage{completionTokens=33, promptTokens=10, totalTokens=43, completionTokensDetails=, promptTokensDetails=, additionalProperties={}}, additionalProperties={}}
Node.js
Sample requestimport OpenAI from "openai";
const openai = new OpenAI(
{
// 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey: "sk-xxx",但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
apiKey: process.env.DASHSCOPE_API_KEY,
baseURL: "https://batch.dashscope.aliyuncs.com/compatible-mode/v1", // 阿里云百炼Batch chat API的 URL
// 在这里添加超时设置 (单位:毫秒)
// 1800秒 * 1000 = 1,800,000 毫秒,最长支持 3,600,000 毫秒
timeout: 1800 * 1000,
}
);
async function main() {
const completion = await openai.chat.completions.create({
model: "qwen-plus", //此处以qwen-plus为例,可按需更换模型名称。
messages: [
{ role: "system", content: "You are a helpful assistant." },
{ role: "user", content: "你是谁?" }
],
});
console.log(JSON.stringify(completion))
}
main();
Sample response{
"created": 1763618557,
"usage": {
"completion_tokens": 80,
"prompt_tokens": 22,
"total_tokens": 102
},
"model": "qwen-plus",
"id": "chatcmpl-af23c086-8662-91eb-b236-892032ddee92",
"choices": [
{
"finish_reason": "stop",
"index": 0,
"message": {
"role": "assistant",
"content": "我是千问,由阿里云研发的超大规模语言模型。我能够回答问题、创作文字,如写故事、公文、邮件、剧本等,还能进行逻辑推理、编程,表达观点,玩游戏等。我支持多种语言,包括中文、英文、德语、法语、西班牙语等。如果你有任何问题或需要帮助,欢迎随时告诉我!"
}
}
],
"object": "chat.completion"
}
Go
Sample requestpackage main
import (
"context"
"os"
"time"
"github.com/openai/openai-go"
"github.com/openai/openai-go/option"
)
func main() {
client := openai.NewClient(
option.WithAPIKey(os.Getenv("DASHSCOPE_API_KEY")),
// 阿里云百炼Batch chat API 的 URL
option.WithBaseURL("https://batch.dashscope.aliyuncs.com/compatible-mode/v1"),
)
// 设置超时时间:1800秒 = 30分钟,最长支持3600秒
ctx, cancel := context.WithTimeout(context.Background(), 3600*time.Second)
defer cancel()
chatCompletion, err := client.Chat.Completions.New(
ctx, openai.ChatCompletionNewParams{
Messages: []openai.ChatCompletionMessageParamUnion{
openai.UserMessage("你是谁"),
},
Model: "qwen-plus",
},
)
if err != nil {
panic(err.Error())
}
println(chatCompletion.Choices[0].Message.Content)
}
Sample response我是千问,由阿里云研发的超大规模语言模型。我可以生成各种类型的文本,如文章、故事、诗歌、故事等,并能够根据不同的场景和需求进行变换和扩展。此外,我还能够回答各种问题,提供帮助和解决方案。很高兴为您服务!
C#(HTTP)
Sample requestusing System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
class Program
{
private static readonly HttpClient httpClient = new HttpClient
{
// 设置超时时间:1800秒 = 30分钟,最长支持3600秒
Timeout = TimeSpan.FromSeconds(1800)
};
static async Task Main(string[] args)
{
// 若没有配置环境变量,请用百炼API Key将下行替换为:string? apiKey = "sk-xxx";
string? apiKey = Environment.GetEnvironmentVariable("DASHSCOPE_API_KEY");
if (string.IsNullOrEmpty(apiKey))
{
Console.WriteLine("API Key 未设置。请确保环境变量 'DASHSCOPE_API_KEY' 已设置。");
return;
}
// 设置请求 URL 和内容
string url = "https://batch.dashscope.aliyuncs.com/compatible-mode/v1/chat/completions"; // Batch chat API 的 URL
// 此处以qwen-plus为例,可按需更换模型名称。
string jsonContent = @"{
""model"": ""qwen-plus"",
""messages"": [
{
""role"": ""system"",
""content"": ""You are a helpful assistant.""
},
{
""role"": ""user"",
""content"": ""你是谁?""
}
]
}";
// 发送请求并获取响应
string result = await SendPostRequestAsync(url, jsonContent, apiKey);
// 输出结果
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"))
{
// 设置请求头
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
// 发送请求并获取响应
HttpResponseMessage response = await httpClient.PostAsync(url, content);
// 处理响应
if (response.IsSuccessStatusCode)
{
return await response.Content.ReadAsStringAsync();
}
else
{
return $"请求失败: {response.StatusCode}";
}
}
}
}
Sample response{
"created": 1763620689,
"usage": {
"completion_tokens": 60,
"prompt_tokens": 22,
"total_tokens": 82
},
"model": "qwen-plus",
"id": "chatcmpl-db85828d-af47-97a3-a2f4-120b8f7d72d3",
"choices": [
{
"finish_reason": "stop",
"index": 0,
"message": {
"role": "assistant",
"content": "我是千问,阿里巴巴集团旗下的超大规模语言模型。我能够回答问题、创作文字,比如写故事、写公文、写邮件、写剧本、逻辑推理、编程等等,还能表达观点,玩游戏等。如果你有任何问题或需要帮助,欢迎随时告诉我!"
}
}
],
"object": "chat.completion"
}
PHP(HTTP)
Sample request<?php
// 设置Batch Chat 请求 的 URL
$url = 'https://batch.dashscope.aliyuncs.com/compatible-mode/v1/chat/completions';
// 若没有配置环境变量,请用百炼API Key将下行替换为:$apiKey = "sk-xxx";
$apiKey = getenv('DASHSCOPE_API_KEY');
// 设置请求头
$headers = [
'Authorization: Bearer '.$apiKey,
'Content-Type: application/json'
];
// 设置请求体
$data = [
// 此处以qwen-plus为例,可按需更换模型名称。
"model" => "qwen-plus",
"messages" => [
[
"role" => "system",
"content" => "You are a helpful assistant."
],
[
"role" => "user",
"content" => "你是谁?"
]
]
];
// 初始化cURL会话
$ch = curl_init();
// 设置cURL选项
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);
// 在此处设置Batch chat 请求的超时时间:1800秒 = 30分钟,最长支持3600秒
curl_setopt($ch, CURLOPT_TIMEOUT, 1800);
// 执行cURL会话
$response = curl_exec($ch);
// 检查是否有错误发生
if (curl_errno($ch)) {
echo 'Curl error: ' . curl_error($ch);
}
// 关闭cURL资源
curl_close($ch);
// 输出响应结果
echo $response;
?>
Sample response{
"created": 1763621824,
"usage": {
"completion_tokens": 81,
"prompt_tokens": 22,
"total_tokens": 103
},
"model": "qwen-plus",
"id": "chatcmpl-b25aeb86-5cfe-93ea-ab03-aa3de1381c23",
"choices": [
{
"finish_reason": "stop",
"index": 0,
"message": {
"role": "assistant",
"content": "我是千问,由阿里云研发的超大规模语言模型。我能够回答问题、创作文字,如写故事、公文、邮件、剧本等,还能进行逻辑推理、编程,甚至表达观点和玩游戏。我支持多种语言,包括但不限于中文、英文、德语、法语、西班牙语等。如果你有任何问题或需要帮助,欢迎随时告诉我!"
}
}
],
"object": "chat.completion"
}
curl
Sample requestSet the maximum waiting time max-time to 1800 seconds; the maximum supported value is 3600 seconds.
curl -X POST https://batch.dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
--max-time 1800 \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-plus",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "你是谁?"
}
]
}'
Sample response{
"created": 1763622152,
"usage": {
"completion_tokens": 79,
"prompt_tokens": 22,
"total_tokens": 101
},
"model": "qwen-plus",
"id": "chatcmpl-daa344d2-60df-9b79-81a4-28c9a10a0a0e",
"choices": [
{
"finish_reason": "stop",
"index": 0,
"message": {
"role": "assistant",
"content": "我是千问,阿里巴巴集团旗下的超大规模语言模型。我能够回答问题、创作文字,如写故事、公文、邮件、剧本等,还能进行逻辑推理、编程,表达观点,玩游戏等。我支持多种语言,包括但不限于中文、英文、德语、法语、西班牙语等。如果你有任何问题或需要帮助,欢迎随时告诉我!"
}
}
],
"object": "chat.completion"
}
Limits
-
Waiting time: After a request is submitted, the result is awaited synchronously, and the server keeps the connection open for up to 3600 seconds (1 hour). You can set a custom timeout based on your actual needs, with a valid range of 60-3600 seconds.
-
Concurrency limit: A single account can maintain up to 10,000 pending requests per model. New requests that exceed this limit are rejected with a corresponding error code until pending requests complete and free up available slots.
-
Request rate: A single account can submit requests at a maximum rate of 1000 QPS (10,000 requests / 10 seconds).
This limit is a theoretical maximum set by the system. In actual usage, the API's available resources are dynamically affected by the overall system load. We recommend implementing retry logic in your code.
Billing Details
- Billing unit price: You are billed for the input and output tokens of successful requests, at the same rates as real-time model invocations. For a limited time, the official website offers a 50% discount for Batch Chat calls, with the final fee being 50% of the real-time invocation price. For more information, see Models.
- Billing scope: Only requests that are successfully executed in a task are billed. Any failed requests (including system errors or timeouts) are not billed.
ImportantBatch inference is a separate billing item and does not support upfront payment (savings plans), the new-user free quota, or features such as context caching.
Error codes
If a model invocation fails and returns an error message, see Error codes for troubleshooting.
FAQ
-
Is there a difference in processing time between Batch Chat requests and real-time APIs?
Yes. Batch Chat requests must queue for scheduling, so the end-to-end processing time is usually longer than that of real-time APIs. The maximum waiting time on the server side is 1 hour. If a request is not executed within this time, the connection is automatically closed and an error is returned.
-
How do I choose between Batch Chat and Batch File?
Choose Batch Chat when your business logic requires submitting a large number of independent conversation requests with high concurrency via synchronous API calls. Choose Batch File when you need to process a single large file containing many requests and can accept asynchronously retrieving the result file.
-
Does Batch Chat guarantee that all requests are completed?
No. Batch Chat uses Batch resources, and completion depends on system resource allocation. If system resources are busy, requests may wait in the queue. If a request is still not scheduled for execution after the maximum waiting time, the connection times out and closes. In this case, the request is not billed, and you can retry later.
Related documentation
- For the complete parameter list for real-time model invocations, see OpenAI-compatible Chat.
- To perform batch processing by submitting files and retrieving results asynchronously, see OpenAI-compatible Batch (file input).