OpenAI Batch API

Reference, synced 2026-06-13.

flowchart TD
  n0["Models"]
  n1["Overview"]
  n2["Products"]
  n3["Solutions"]
  n4["Pricing"]
  n5["Resources"]
  n6["Partners"]
  n7["Support"]
  n8["Language"]
  n0 --> n1
  n1 --> n2
  n2 --> n3
  n3 --> n4
  n4 --> n5
  n5 --> n6
  n6 --> n7
  n7 --> n8

Free access Accelerate Delivery with Fixed-Cost Agentic CodingWatch how it works

Models

Empowering AI innovation for both enterprises and developers with Alibaba Cloud’s best-in-class Qwen models, AI-native apps, and AI solutions.

Alibaba Cloud Model Studio \ Enterprise-grade large model service and application development platform.

Try Visual Model \ Supports image understanding, image generation, and video generation.

Models

HappyHorse-1.0-T2V \ Cinematic creative generation, ultimate dynamic details Qwen3-VL-Plus \ Native VL, spatial reasoning, 1M-context video analysis Wan2.7-VideoEdit \ Supports both localized and global editing with prompt

Qwen3.6-Plus \ Native multimodal, 1M context, agentic coding Wan2.7-Image-Pro \ Interactive editing, long-text rendering, precise prompt following Qwen-Plus \ Balanced intelligence, efficient inference, production-ready performance

Qwen-Image-2.0 \ Professional infographics, exquisite photorealism Z-Image-Turbo \ Ultra-fast image generation, high throughput, cost-optimized inference Qwen3-Coder-Next \ Multi-turn tool interactions, future-ready development support

Wan2.7-T2V \ High-fidelity T2V, 15s duration, advanced camera control Wan2.7-I2V \ Cinematic I2V with emotional depth and visceral impact Wan2.7-R2V \ Up to 5 mixed image/video inputs and audio timbre cloning

GenAI Application

Qoder \ Intelligent coding assistant, available for enterprise-dedicated deployment. Qoder CN \ AI-powered coding assistant that boosts developer productivity with intelligent code completion, AI chat, multi-file editing, and task automation.

AI Service

Model Experience \ Experience full-scale, multimodal model capabilities online. Platform for AI \ An AI-native algorithm engineering platform for end-to-end modeling, training, and inference service deployment. Fine-tune Video Generation Model \ Customize Wan’s text-to-video capabilities through model fine-tuning to meet your unique requirements.

AI Use Case

AI Savings Plan Hot \ Save up to 47% on AI costs. Limited-time offer tailored to your usage. AI Video Creation \ Elevate your professional video production with Wan 2.6.

AI Token Plan \ One plan. Multiple models. Big Savings with a Fixed Subscription. AI Image Creation \ All-in-one creative suite for copywriting, image generation, and poster design.

Overview

As a global full-stack AI leader, Alibaba Cloud aims to make computing accessible to everyone and help worldwide customers accelerate innovation.

Why Alibaba Cloud

About Alibaba Cloud \ AI Powered Cloud Technology Our Global Network \ Explore our global presence and deployment regions around the world Our Global Offices \ With offices in 4 continents, we're always close to where it matters.

Asia Accelerator \ Accelerate Success in Asia with Alibaba Cloud Go Global \ Benefits of our Global Alliance Trust Center \ Empowering enterprises with a secure, compliant, and globally trusted cloud infrastructure

Customers and Insights

Olympic Games \ Alibaba Cloud Powers Olympic Games with AI-powered cloud technology Case Studies \ Learn how customers are scaling their businesses on Alibaba Cloud Analyst Reports \ Learn what the top industry analyst firms are saying about Alibaba Cloud

What's New

Events and Webinars \ Quick access to upcoming and on-demand events Product Updates \ Stay informed of the latest innovations Press Room \ Latest news and media releases

Products

Featured ProductsAI & Machine Learning Computing Container Storage Networking & CDN Security Middleware Database Analytics ComputingMedia ServicesEnterprise Services & Cloud CommunicationDomain Names and WebsitesEnd User ComputingServerlessDeveloper ToolsMigration & O&M ManagementApsara Stack

Featured Products

Alibaba Cloud Model Studio \ Supercharge your AI journey effortlessly with industry-leading GenAI models ApsaraDB RDS \ Store and manage your business data, with automated monitoring and backups Certificate Management Service (Original SSL Certificate) \ Create a safe and secure connection between your website and users

Elastic Compute Service (ECS) \ Host websites anywhere and scale enterprise workloads Container Service for Kubernetes (ACK) \ Run and scale containerized applications on managed Kubernetes infrastructure Object Storage Service (OSS) \ Store large amounts of data in the cloud and access it anywhere, anytime

Simple Application Server (SAS) \ All-in-one services for fast deployment Elastic IP Address (EIP) \ Manage your public IPs independently to improve internet network quality Domain Names and Website \ Get the perfect domain name to suit your every need

Solutions

Solutions by Industry Technical Solutions AI WebsitesNetworking Security and ComplianceData and AnalyticsEnterprise Service and ApplicationCloud MigrationCloud NativeHybrid CloudSMB solutions

Financial Services \ Innovate faster with Alibaba Cloud Games \ Grow your game rapidly with high global availability

New Retail \ Alibaba Cloud enables digital retail transformation to fuel growth and realize an omnichannel customer experience throughout the consumer journey. Media and Entertainment \ Ready your content for today's media market with a digitalized media journey

Supply Chain \ Power your supply chain with intelligent, efficient, and reliable solutions Sports \ Digitizing the sports industry with intelligent tech

Sustainability \ Achieve a sustainable future with low-carbon and energy-efficient technologies

Pricing

Flexible options like pay-as-you-go and clear billing rules to meet diverse business needs.

Overview & Tools

Pricing Calculator \ Get an instant pricing estimate based on your usage and needs Free Trial \ Try our 80+ cloud products for free.

Pricing Options \ Get the most out of Alibaba Cloud with flexible pricing

Optimize your cost

Migrate & Save \ Superior Performance At Lower Pricing. Save up to 50%. Promotion Center \ Unlock the latest Alibaba Cloud offers & promos

Resources

Official documentation, extensive tools, training resources, and a community to grow and innovate in the cloud.

Technical Resources

Documentation \ Product guides and FAQs Architecture Center \ Design reliable, secure, and efficient cloud architecture. Intelligent Solution Explorer \ Find the right solution for you, powered by AI

Blog \ Latest cloud insights and developer trends Whitepapers \ Research that explores the how and why behind our technology

Training&Certification

Alibaba Cloud Academy \ Build cloud skills and earn certifications with expert-led training.

Developer Hub

Alibaba Cloud Project Hub \ Explore real-world projects built by developers using our platform. Our Developer MVPs \ Celebrating the developers who lead, build, and inspire our community

Partners

Partner-first strategy offering collaborative product, sales, and service models, plus high-quality partner solutions that complement Alibaba Cloud’s capabilities.

Marketplace

AI Alliance for ISVs \ Partner with us to build and grow AI solutions together ISV Benefits \ Unlock resources, market access, and go-to-market support as an ISV partner

Alibaba Cloud Marketplace \ Explore ready-to-deploy solutions from our partners and ISVs

Find a Partner

Partner Hub \ Find your ideal partner in no time

Become a Partner

Partner Network \ A partner portal for Alibaba Cloud Channel, Technology, MSP partner and other partner programs

Support

Full-lifecycle support and expert services, from cloud advisory and migration to operations.

Support & Professional Services

Professional Services \ Expert-led services to design, migrate, and optimize your cloud journey Support Plans \ Flexible support for every stage — from startup to enterprise

Partner Support Program \ Priority technical support for partners, with dedicated managers and faster issue resolution

Contact us

Connect With Us \

Talk to a sales expert and get a custom quote for your business

Language

English
简体中文
繁體中文
日本語
Bahasa Indonesia

Locale

Visit aliyun.com

Documentation

Alibaba Cloud Model Studio

User Guide (Models) User Guide (Application) API Reference (Models) API Reference (Application)

Search for Help Content

Getting Started

The Beginner's Guide

Well-Architected Framework

AI & Machine Learning

Platform For AI

Alibaba Cloud Model Studio

DashVector

Artificial Intelligence Recommendation

OpenSearch

Image Search

Machine Translation

Intelligent Speech Interaction

Optimization Solver

Intelligent Computing LINGJUN

Computing

Elastic Compute Service

Elastic GPU Service

Elastic Container Instance

Dedicated Host

Compute Nest

Simple Application Server

Cloud Box

Auto Scaling

Elastic High Performance Computing

Batch Compute (Deprecated)

Function Compute

Serverless App Engine

ENS

Elastic Desktop Service

App Streaming

WUYING Terminal

Cloud Phone

Edge Network Acceleration

Alibaba Cloud Linux

AgentBay

Container

Container Service for Kubernetes

Container Compute Service

Container Registry

Storage

Object Storage Service

Cloud Parallel File Storage

File Storage NAS

Tablestore

Storage Capacity Unit

Simple Log Service

Cloud Backup

Intelligent Media Management

Drive and Photo Service

Data Transport

Cloud Storage Gateway

Data Online Migration

Hybrid Cloud Storage Array

Storage Services Overview

Backup and Disaster Recovery Center

Networking and CDN

Server Load Balancer

Elastic IP Address

Internet Shared Bandwidth

Data Transfer Plan

Virtual Private Cloud

NAT Gateway

PrivateLink

Alibaba Cloud DNS PrivateZone

Network Intelligence Service

Cloud Data Transfer

IPv6 Gateway

Anycast Elastic IP Address

Cloud Enterprise Network

Global Accelerator

VPN Gateway

Smart Access Gateway

Express Connect

CDN

Edge Security Acceleration

Cloud Network Well-architected Design Guidelines

Security

Anti-DDoS

Web Application Firewall

Cloud Firewall

Security Center

Bastionhost

Secure Access Service Edge

Certificate Management Service

Key Management Service

Data Security Center

Identity as a Service

Fraud Detection

AI Guardrails

Captcha

Blockchain as a Service

ID Verification

Managed Security Service

Middleware

Enterprise Distributed Application Service

Microservices Engine

Alibaba Cloud Service Mesh

SchedulerX

ApsaraMQ for RocketMQ

ApsaraMQ for Kafka

ApsaraMQ for RabbitMQ

ApsaraMQ for MQTT

Simple Message Queue (formerly MNS)

CloudFlow

EventBridge

Application Real-Time Monitoring Service

Managed Service for Prometheus

Managed Service for Grafana

Managed Service for OpenTelemetry

Performance Testing

STAROps

Databases

ApsaraDB Console

PolarDB

ApsaraDB RDS

ApsaraDB for OceanBase (Deprecated)

Tair (Redis® OSS-Compatible)

Lindorm

Time Series Database

ApsaraDB for MongoDB

ApsaraDB for HBase

ApsaraDB for Memcache

ApsaraDB for MyBase

AnalyticDB

ApsaraDB for ClickHouse

ApsaraDB for SelectDB

Data Transmission Service

Database Autonomy Service

Data Management

Database Gateway - Deprecated

ApsaraDB for Cassandra - Deprecated

Analytics Computing

MaxCompute

Hologres

Realtime Compute for Apache Flink

Elasticsearch

Vector Retrieval Service for Milvus

E-MapReduce

Data Lake Formation

DataV

Quick BI

Quick Audience

Quick Tracking

DataWorks

DataHub

Dataphin

Media Services

ApsaraVideo VOD

ApsaraVideo Live

Intelligent Media Services

ApsaraVideo Media Processing

Apsara Video SDK

Enterprise Services & Cloud Communication

Energy Expert

CloudQuotation

Salesforce on Alibaba Cloud

GoChina ICP Filing Assistant

Marketplace

Alibaba Mail

Direct Mail

Short Message Service

Voice Service

Phone Number Verification Service

Cell Phone Number Service

Chat App Message Service

Financial Intelligence Engine

Domain Names and Websites

Domain Names

ICP Filing

Alibaba Cloud DNS

End User Computing

Elastic Desktop Service

App Streaming

WUYING Terminal

Cloud Phone

AgentBay

Internet of Things

IoT Platform

Serverless

Serverless App Engine

CloudFlow

EventBridge

Simple Message Queue (formerly MNS)

Function Compute

Developer Tools

OpenAPI Explorer

Alibaba Cloud SDK

Cloud Shell

Resource Orchestration Service

Alibaba Cloud CLI

BSS OpenAPI

Terraform

Pulumi

Ticket System API

Mobile Platform as a Service

Alibaba Cloud DevOps

API Gateway

Cloud Control API

AI Coding Assistant Lingma

Cloud Skills Portal

Migration & O&M Management

CloudOps Orchestration Service

Cloud Monitor

Intelligent Advisor

Cloud Governance Center

ActionTrail

Cloud Config

Resource Access Management

Resource Management

Cloud Architect Design Tools

Migration Hub

Server Migration Center

Service Catalog

Logic Composer

Quota Center

CloudSSO

HTTPDNS

Solutions

SAP

SuperApp

OpenLake

Membership Service

Expenses and Costs

Account Center

Support

Legal

Tech Share Terms and Conditions

After Sales Support

China Gateway Program

Service Level Objectives

Management Console

Security Control

Alibaba Cloud Model Studio provides an OpenAI-compatible Batch File API. Submit requests in bulk through files. The system processes them asynchronously and returns results when all requests complete or the maximum wait time is reached. Costs are only 50% of real-time calls. Ideal for data analytics, model evaluation, and other large-scale workloads where latency is not critical.

To use the console, see console guide.

Workflow

Prerequisites

You can call the Batch File API through the OpenAI SDK (Python, Node.js) or HTTP API.

Get an API Key: Get and configure your Model Studio API Key as an environment variable
Install SDK (optional): Install the OpenAI SDK if you plan to use it.
Service endpoints
- Chinese mainland: https://dashscope.aliyuncs.com/compatible-mode/v1
- International: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1

Important

The legacy Singapore domain https://dashscope-intl.aliyuncs.com will be discontinued. Migrate to https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com as soon as possible.

Scope

Singapore

China (Beijing)

Supported models: qwen-max, qwen-plus, qwen-flash, qwen-turbo.

Supported models:

Text generation models: The stable versions and some latest versions of Qwen-Max, Plus, Flash, and Long. The QwQ series (qwq-plus) and some third-party models (deepseek-r1, deepseek-v3.2, deepseek-v3) are also supported.
Multimodal models: The stable versions and some latest versions of Qwen-VL-Max, Plus, and Flash. The Qwen-OCR model is also supported.
Text embedding models: The text-embedding-v4 model.

List of supported model names

Text generation models
- Qwen-Max: qwen3.7-max, qwen3-max, qwen-max, qwen-max-latest
- Qwen-Plus: qwen3.7-plus, qwen3.6-plus, qwen3.5-plus, qwen-plus, qwen-plus-latest
- Qwen-Flash: qwen3.5-flash, qwen-flash
- Recommended models: qwen-long-latest
- Recommended models: qwq-plus
- Third-party models: deepseek-r1, deepseek-v3.2, deepseek-v3
Multimodal models
- Image and video understanding: qwen3.7-plus, qwen3.6-plus, qwen3.5-plus, qwen3.5-flash, qwen3-vl-plus, qwen3-vl-flash, qwen-vl-max, qwen-vl-max-latest, qwen-vl-plus, qwen-vl-plus-latest
- Text extraction: qwen-vl-ocr
Text embedding models: text-embedding-v4

Important

In the batch processing scenario, the maximum context tokens per request is 256 K for qwen3.7-max, qwen3.7-plus, qwen3.6-plus, qwen3.5-plus, and qwen3.5-flash.
Some models support thinking mode. Enabling this mode generates thinking tokens and increases costs.
The qwen3.6-plus and qwen3.5 series models, such as qwen3.5-plus and qwen3.5-flash, have thinking mode enabled by default. If you use a hybrid thinking model, you must explicitly set the enable_thinking parameter. Set this parameter to true to enable the mode or false to disable it.
In the JSONL request body, enable_thinking is a top-level parameter of body and must be placed at the same level as model. Do not place it inside extra_body.

Getting started

Before processing formal tasks, test with the batch-test-model. This test model skips inference and returns a fixed success response, allowing you to verify your API call chain and data format.

Note

Limitations of batch-test-model:

Your test file must meet Input file requirements. Maximum size: 1 MB. Maximum lines: 100.
Concurrency limit: Up to 2 parallel tasks.
Cost: The test model does not incur model inference fees.

Step 1: Prepare the input file

Prepare a file named test_model.jsonl with the following content:

json

{"custom_id":"1","method":"POST","url":"/v1/chat/ds-test","body":{"model":"batch-test-model","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"Hello! How can I help you?"}]}}
{"custom_id":"2","method":"POST","url":"/v1/chat/ds-test","body":{"model":"batch-test-model","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is 2+2?"}]}}

Multimodal models (e.g., qwen-vl-plus) support file URLs and Base64-encoded inputs:

json

{"custom_id":"image-url","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"image_url","image_url":{"url":"https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"}},{"type":"text","text":"Describe this image."}]}]}}
{"custom_id":"image-base64","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"image_url","image_url":{"url":"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEA8ADwAAD..."}},{"type":"text","text":"Describe this image."}]}]}}

Step 2: Run the code

Select a code snippet for your programming language. Save it in the same directory as your input file and run it. The code handles the full workflow: upload, create task, poll status, and download results.

To customize the file path or other parameters, modify the code as needed.

Note

Reuse an existing file ID: The ID returned after uploading a file (e.g., file-batch-xxx) can be reused. If the input content remains the same, skip re-uploading and directly create a task with the existing ID:

python

batch = client.batches.create(
    input_file_id="file-batch-xxx",  # Reuse existing file ID, no need to re-upload
    endpoint="/v1/chat/completions",
    completion_window="24h"
)

You can retrieve historical file IDs through the client.files.list(purpose="batch") API to query uploaded Batch file IDs.

Sample code

OpenAI Python SDK

OpenAI Node.js SDK

Java (HTTP)

curl (HTTP)

python

import os
from pathlib import Path
from openai import OpenAI
import time

# Initialize the client
client = OpenAI(
    # If no environment variable is set, replace the line below with api_key="sk-xxx". But never hard-code in production to reduce leak risk.
    # API keys differ between Singapore and Beijing regions.
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Singapore region's base_url. For Beijing, use: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"  # The base_url for the Model Studio service
)

def upload_file(file_path):
    print(f"Uploading the JSONL file that contains request information...")
    file_object = client.files.create(file=Path(file_path), purpose="batch")
    print(f"File uploaded successfully. File ID: {file_object.id}\n")
    return file_object.id

def create_batch_job(input_file_id):
    print(f"Creating a batch task based on the file ID...")
    # Note: The value of the endpoint parameter here must match the url field in the input file.
    # For the test model (batch-test-model), use /v1/chat/ds-test.
    # For text embedding models, use /v1/embeddings.
    # For other models, use /v1/chat/completions.
    batch = client.batches.create(input_file_id=input_file_id, endpoint="/v1/chat/ds-test", completion_window="24h")
    print(f"Batch task created. Batch task ID: {batch.id}\n")
    return batch.id

def check_job_status(batch_id):
    print(f"Checking the batch task status...")
    batch = client.batches.retrieve(batch_id=batch_id)
    print(f"Batch task status: {batch.status}\n")
    return batch.status

def get_output_id(batch_id):
    print(f"Getting the output file ID for successful requests in the batch task...")
    batch = client.batches.retrieve(batch_id=batch_id)
    print(f"Output file ID: {batch.output_file_id}\n")
    return batch.output_file_id

def get_error_id(batch_id):
    print(f"Getting the output file ID for failed requests in the batch task...")
    batch = client.batches.retrieve(batch_id=batch_id)
    print(f"Error file ID: {batch.error_file_id}\n")
    return batch.error_file_id

def download_results(output_file_id, output_file_path):
    print(f"Printing and downloading the results of successful requests from the batch task...")
    content = client.files.content(output_file_id)
    # Print some content for testing
    print(f"Printing the first 1,000 characters of the successful request results: {content.text[:1000]}...\n")
    # Save the result file locally
    content.write_to_file(output_file_path)
    print(f"The complete output results have been saved to the local output file result.jsonl\n")

def download_errors(error_file_id, error_file_path):
    print(f"Printing and downloading the failure information for requests from the batch task...")
    content = client.files.content(error_file_id)
    # Print some content for testing
    print(f"Printing the first 1,000 characters of the request failure information: {content.text[:1000]}...\n")
    # Save the error information file locally
    content.write_to_file(error_file_path)
    print(f"The complete request failure information has been saved to the local error file error.jsonl\n")

def main():
    # File paths
    input_file_path = "test_model.jsonl"  # You can replace this with your input file path
    output_file_path = "result.jsonl"  # You can replace this with your output file path
    error_file_path = "error.jsonl"  # You can replace this with your error file path
    try:
        # Step 1: Upload the JSONL file containing request information to get the input file ID
        input_file_id = upload_file(input_file_path)
        # Step 2: Create a batch task based on the input file ID
        batch_id = create_batch_job(input_file_id)
        # Step 3: Check the batch task status until it is finished
        status = ""
        while status not in ["completed", "failed", "expired", "cancelled"]:
            status = check_job_status(batch_id)
            print(f"Waiting for the task to complete...")
            time.sleep(10)  # Wait 10 seconds and then query the status again
        # If the task fails, print the error message and exit
        if status == "failed":
            batch = client.batches.retrieve(batch_id)
            print(f"Batch task failed. Error message: {batch.errors}\n")
            print(f"For more information, see Error codes: https://www.alibabacloud.com/help/en/model-studio/developer-reference/error-code
            return
        # Step 4: Download results: If the output file ID is not empty, print the first 1,000 characters of the successful request results and download the complete results to a local output file.
        # If the error file ID is not empty, print the first 1,000 characters of the request failure information and download the complete information to a local error file.
        output_file_id = get_output_id(batch_id)
        if output_file_id:
            download_results(output_file_id, output_file_path)
        error_file_id = get_error_id(batch_id)
        if error_file_id:
            download_errors(error_file_id, error_file_path)
            print(f"For more information, see Error codes: https://www.alibabacloud.com/help/en/model-studio/developer-reference/error-code
    except Exception as e:
        print(f"An error occurred: {e}")
        print(f"For more information, see Error codes: https://www.alibabacloud.com/help/en/model-studio/developer-reference/error-code

if __name__ == "__main__":
    main()

javascript

/**
 * Model Studio Batch API Test - Using OpenAI Node.js SDK
 *
 * Install dependencies: npm install openai
 * Run: node test-nodejs.js
 */

const OpenAI = require('openai');
const fs = require('fs');

// Base URL for the Singapore region
const BASE_URL = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1';
// For Beijing, use: const BASE_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1';

const apiKey = process.env.DASHSCOPE_API_KEY;
if (!apiKey) {
    console.error('Error: Please set the environment variable DASHSCOPE_API_KEY');
    process.exit(1);
}

// Initialize the client
const client = new OpenAI({
    apiKey: apiKey,
    baseURL: BASE_URL
});

async function sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
}

async function main() {
    try {
        console.log('=== Start Batch API Test ===\n');

        // Step 1: Upload file
        console.log('Step 1: Uploading the JSONL file that contains request information...');
        const fileStream = fs.createReadStream('test_model.jsonl');
        const fileObject = await client.files.create({
            file: fileStream,
            purpose: 'batch'
        });
        const fileId = fileObject.id;
        console.log(`✓ File uploaded successfully, File ID: ${fileId}\n`);

        // Step 2: Create batch task
        console.log('Step 2: Creating batch task...');
        const batch = await client.batches.create({
            input_file_id: fileId,
            endpoint: '/v1/chat/ds-test',  // Use /v1/chat/ds-test for the test model
            completion_window: '24h'
        });
        const batchId = batch.id;
        console.log(`✓ Batch task created successfully, Task ID: ${batchId}\n`);

        // Step 3: Poll task status
        console.log('Step 3: Waiting for task to complete...');
        let status = batch.status;
        let pollCount = 0;
        let latestBatch = batch;

        while (!['completed', 'failed', 'expired', 'cancelled'].includes(status)) {
            await sleep(10000); // Wait 10 seconds
            latestBatch = await client.batches.retrieve(batchId);
            status = latestBatch.status;
            pollCount++;
            console.log(`  [${pollCount}] Task status: ${status}`);
        }

        console.log(`\n✓ Task completed, final status: ${status}\n`);

        // Step 4: Process results
        if (status === 'completed') {
            console.log('Step 4: Downloading result file...');

            // Download successful results
            const outputFileId = latestBatch.output_file_id;
            if (outputFileId) {
                console.log(`  Output file ID: ${outputFileId}`);
                const content = await client.files.content(outputFileId);
                const text = await content.text();
                console.log('\n--- Successful results (first 500 characters) ---');
                console.log(text.substring(0, Math.min(500, text.length)));
                console.log('...\n');
            }

            // Download error file (if any)
            const errorFileId = latestBatch.error_file_id;
            if (errorFileId) {
                console.log(`  Error file ID: ${errorFileId}`);
                const errorContent = await client.files.content(errorFileId);
                const errorText = await errorContent.text();
                console.log('\n--- Error information ---');
                console.log(errorText);
            }

            console.log('\n=== Test completed successfully ===');
        } else if (status === 'failed') {
            console.error('\n✗ Batch task failed');
            if (latestBatch.errors) {
                console.error('Error message:', latestBatch.errors);
            }
            console.error('\nSee error code documentation: https://www.alibabacloud.com/help/en/model-studio/developer-reference/error-code
        } else {
            console.log(`\nTask status: ${status}`);
        }

    } catch (error) {
        console.error('An error occurred:', error.message);
        console.error(error);
    }
}

main();

java

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Scanner;

/**
 * Model Studio Batch API Test - Using HTTP API
 *
 * Prerequisites:
 * 1. Ensure the environment variable DASHSCOPE_API_KEY is set
 * 2. Prepare the test file test_model.jsonl (in the project root directory)
 *
 * Region configuration:
 * - Beijing region: https://dashscope.aliyuncs.com/compatible-mode/v1
 * - Singapore region: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
 */
public class BatchAPITest {

    // Base URL for the Singapore region
    private static final String BASE_URL = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1";
    // For Beijing, use: private static final String BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1";

    private static String API_KEY;

    public static void main(String[] args) throws Exception {
        // Get API Key from environment variable
        API_KEY = System.getenv("DASHSCOPE_API_KEY");
        if (API_KEY == null || API_KEY.isEmpty()) {
            System.err.println("Error: Please set the environment variable DASHSCOPE_API_KEY");
            System.exit(1);
        }

        System.out.println("=== Start Batch API Test ===\n");

        try {
            // Step 1: Upload file
            System.out.println("Step 1: Uploading the JSONL file that contains request information...");
            String fileId = uploadFile("test_model.jsonl");
            System.out.println("✓ File uploaded successfully, File ID: " + fileId + "\n");

            // Step 2: Create batch task
            System.out.println("Step 2: Creating batch task...");
            String batchId = createBatch(fileId);
            System.out.println("✓ Batch task created successfully, Task ID: " + batchId + "\n");

            // Step 3: Poll task status
            System.out.println("Step 3: Waiting for task to complete...");
            String status = "";
            int pollCount = 0;

            while (!isTerminalStatus(status)) {
                Thread.sleep(10000); // Wait 10 seconds
                String batchInfo = getBatch(batchId);
                status = parseStatus(batchInfo);
                pollCount++;
                System.out.println("  [" + pollCount + "] Task status: " + status);

                // Step 4: If completed, download results
                if ("completed".equals(status)) {
                    System.out.println("\n✓ Task completed!\n");
                    System.out.println("Step 4: Downloading result file...");

                    String outputFileId = parseOutputFileId(batchInfo);
                    if (outputFileId != null && !outputFileId.isEmpty()) {
                        System.out.println("  Output file ID: " + outputFileId);
                        String content = getFileContent(outputFileId);
                        System.out.println("\n--- Successful results (first 500 characters) ---");
                        System.out.println(content.substring(0, Math.min(500, content.length())));
                        System.out.println("...\n");
                    }

                    String errorFileId = parseErrorFileId(batchInfo);
                    if (errorFileId != null && !errorFileId.isEmpty() && !"null".equals(errorFileId)) {
                        System.out.println("  Error file ID: " + errorFileId);
                        String errorContent = getFileContent(errorFileId);
                        System.out.println("\n--- Error information ---");
                        System.out.println(errorContent);
                    }

                    System.out.println("\n=== Test completed successfully ===");
                    break;
                } else if ("failed".equals(status)) {
                    System.err.println("\n✗ Batch task failed");
                    System.err.println("Task info: " + batchInfo);
                    System.err.println("\nSee error code documentation: https://www.alibabacloud.com/help/en/model-studio/developer-reference/error-code
                    break;
                } else if ("expired".equals(status) || "cancelled".equals(status)) {
                    System.out.println("\nTask status: " + status);
                    break;
                }
            }

        } catch (Exception e) {
            System.err.println("An error occurred: " + e.getMessage());
            e.printStackTrace();
        }
    }

    /**
     * Upload file
     */
    private static String uploadFile(String filePath) throws Exception {
        String boundary = "----WebKitFormBoundary" + System.currentTimeMillis();
        URL url = new URL(BASE_URL + "/files");
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setDoOutput(true);
        conn.setRequestMethod("POST");
        conn.setRequestProperty("Authorization", "Bearer " + API_KEY);
        conn.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);

        try (DataOutputStream out = new DataOutputStream(conn.getOutputStream())) {
            // Add purpose field
            out.writeBytes("--" + boundary + "\r\n");
            out.writeBytes("Content-Disposition: form-data; name=\"purpose\"\r\n\r\n");
            out.writeBytes("batch\r\n");

            // Add file
            out.writeBytes("--" + boundary + "\r\n");
            out.writeBytes("Content-Disposition: form-data; name=\"file\"; filename=\"" + filePath + "\"\r\n");
            out.writeBytes("Content-Type: application/octet-stream\r\n\r\n");

            byte[] fileBytes = Files.readAllBytes(Paths.get(filePath));
            out.write(fileBytes);
            out.writeBytes("\r\n");
            out.writeBytes("--" + boundary + "--\r\n");
        }

        String response = readResponse(conn);
        return parseField(response, "\"id\":\\s*\"([^\"]+)\"");
    }

    /**
     * Create batch task
     */
    private static String createBatch(String fileId) throws Exception {
        String jsonBody = String.format(
            "{\"input_file_id\":\"%s\",\"endpoint\":\"/v1/chat/ds-test\",\"completion_window\":\"24h\"}",
            fileId
        );

        String response = sendRequest("POST", "/batches", jsonBody);
        return parseField(response, "\"id\":\\s*\"([^\"]+)\"");
    }

    /**
     * Get batch task info
     */
    private static String getBatch(String batchId) throws Exception {
        return sendRequest("GET", "/batches/" + batchId, null);
    }

    /**
     * Get file content
     */
    private static String getFileContent(String fileId) throws Exception {
        return sendRequest("GET", "/files/" + fileId + "/content", null);
    }

    /**
     * Send HTTP request
     */
    private static String sendRequest(String method, String path, String jsonBody) throws Exception {
        URL url = new URL(BASE_URL + path);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod(method);
        conn.setRequestProperty("Authorization", "Bearer " + API_KEY);

        if (jsonBody != null) {
            conn.setDoOutput(true);
            conn.setRequestProperty("Content-Type", "application/json");
            try (OutputStream os = conn.getOutputStream()) {
                os.write(jsonBody.getBytes("UTF-8"));
            }
        }

        return readResponse(conn);
    }

    /**
     * Read response
     */
    private static String readResponse(HttpURLConnection conn) throws Exception {
        int responseCode = conn.getResponseCode();
        InputStream is = (responseCode < 400) ? conn.getInputStream() : conn.getErrorStream();

        try (Scanner scanner = new Scanner(is, "UTF-8").useDelimiter("\\A")) {
            return scanner.hasNext() ? scanner.next() : "";
        }
    }

    /**
     * Parse JSON field (simple implementation)
     */
    private static String parseField(String json, String regex) {
        java.util.regex.Pattern pattern = java.util.regex.Pattern.compile(regex);
        java.util.regex.Matcher matcher = pattern.matcher(json);
        return matcher.find() ? matcher.group(1) : null;
    }

    private static String parseStatus(String json) {
        return parseField(json, "\"status\":\\s*\"([^\"]+)\"");
    }

    private static String parseOutputFileId(String json) {
        return parseField(json, "\"output_file_id\":\\s*\"([^\"]+)\"");
    }

    private static String parseErrorFileId(String json) {
        return parseField(json, "\"error_file_id\":\\s*\"([^\"]+)\"");
    }

    /**
     * Check if status is terminal
     */
    private static boolean isTerminalStatus(String status) {
        return "completed".equals(status)
            || "failed".equals(status)
            || "expired".equals(status)
            || "cancelled".equals(status);
    }
}

bash

#!/bin/bash
# Model Studio Batch API Test - Using curl
#
# Prerequisites:
# 1. Ensure the environment variable DASHSCOPE_API_KEY is set
# 2. Prepare the test file test_model.jsonl (in the current directory)
#
# Region configuration:
# - Beijing region: https://dashscope.aliyuncs.com/compatible-mode/v1
# - Singapore region: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1

API_KEY="${DASHSCOPE_API_KEY}"
BASE_URL="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"

# For Beijing, use: BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"

# Check API Key
if [ -z "$API_KEY" ]; then
    echo "Error: Please set the environment variable DASHSCOPE_API_KEY"
    exit 1
fi

echo "=== Start Batch API Test ==="
echo ""

# Step 1: Upload file
echo "Step 1: Uploading the JSONL file that contains request information..."
UPLOAD_RESPONSE=$(curl -s -X POST "${BASE_URL}/files" \
  -H "Authorization: Bearer ${API_KEY}" \
  -F 'file=@test_model.jsonl' \
  -F 'purpose=batch')

FILE_ID=$(echo $UPLOAD_RESPONSE | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)
echo "✓ File uploaded successfully, File ID: ${FILE_ID}"
echo ""

# Step 2: Create batch task
echo "Step 2: Creating batch task..."
BATCH_RESPONSE=$(curl -s -X POST "${BASE_URL}/batches" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{\"input_file_id\":\"${FILE_ID}\",\"endpoint\":\"/v1/chat/ds-test\",\"completion_window\":\"24h\"}")

BATCH_ID=$(echo $BATCH_RESPONSE | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)
echo "✓ Batch task created successfully, Task ID: ${BATCH_ID}"
echo ""

# Step 3: Poll task status
echo "Step 3: Waiting for task to complete..."
STATUS=""
POLL_COUNT=0

while [[ "$STATUS" != "completed" && "$STATUS" != "failed" && "$STATUS" != "expired" && "$STATUS" != "cancelled" ]]; do
    sleep 10
    BATCH_INFO=$(curl -s -X GET "${BASE_URL}/batches/${BATCH_ID}" \
      -H "Authorization: Bearer ${API_KEY}")
    STATUS=$(echo $BATCH_INFO | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
    POLL_COUNT=$((POLL_COUNT + 1))
    echo "  [${POLL_COUNT}] Task status: ${STATUS}"
done

echo ""
echo "✓ Task completed, final status: ${STATUS}"
echo ""

# Step 4: Download results
if [[ "$STATUS" == "completed" ]]; then
    echo "Step 4: Downloading result file..."

    OUTPUT_FILE_ID=$(echo $BATCH_INFO | grep -o '"output_file_id":"[^"]*"' | cut -d'"' -f4)
    if [[ -n "$OUTPUT_FILE_ID" && "$OUTPUT_FILE_ID" != "null" ]]; then
        echo "  Output file ID: ${OUTPUT_FILE_ID}"

        RESULT_CONTENT=$(curl -s -X GET "${BASE_URL}/files/${OUTPUT_FILE_ID}/content" \
          -H "Authorization: Bearer ${API_KEY}")

        echo ""
        echo "--- Successful results (first 500 characters) ---"
        echo "${RESULT_CONTENT:0:500}"
        echo "..."
        echo ""
    fi

    ERROR_FILE_ID=$(echo $BATCH_INFO | grep -o '"error_file_id":"[^"]*"' | cut -d'"' -f4)
    if [[ -n "$ERROR_FILE_ID" && "$ERROR_FILE_ID" != "null" ]]; then
        echo "  Error file ID: ${ERROR_FILE_ID}"

        ERROR_CONTENT=$(curl -s -X GET "${BASE_URL}/files/${ERROR_FILE_ID}/content" \
          -H "Authorization: Bearer ${API_KEY}")

        echo ""
        echo "--- Error information ---"
        echo "${ERROR_CONTENT}"
    fi

    echo ""
    echo "=== Test completed successfully ==="
elif [[ "$STATUS" == "failed" ]]; then
    echo ""
    echo "✗ Batch task failed"
    echo "Task info: ${BATCH_INFO}"
    echo ""
    echo "See error code documentation: https://www.alibabacloud.com/help/en/model-studio/developer-reference/error-code
else
    echo ""
    echo "Task status: ${STATUS}"
fi

Step 3: Verify test results

After the task succeeds, the result file result.jsonl contains the fixed response {"content":"This is a test result."}:

json

{"id":"a2b1ae25-21f4-4d9a-8634-99a29926486c","custom_id":"1","response":{"status_code":200,"request_id":"a2b1ae25-21f4-4d9a-8634-99a29926486c","body":{"created":1743562621,"usage":{"completion_tokens":6,"prompt_tokens":20,"total_tokens":26},"model":"batch-test-model","id":"chatcmpl-bca7295b-67c3-4b1f-8239-d78323bb669f","choices":[{"finish_reason":"stop","index":0,"message":{"content":"This is a test result."}}],"object":"chat.completion"}},"error":null}
{"id":"39b74f09-a902-434f-b9ea-2aaaeebc59e0","custom_id":"2","response":{"status_code":200,"request_id":"39b74f09-a902-434f-b9ea-2aaaeebc59e0","body":{"created":1743562621,"usage":{"completion_tokens":6,"prompt_tokens":20,"total_tokens":26},"model":"batch-test-model","id":"chatcmpl-1e32a8ba-2b69-4dc4-be42-e2897eac9e84","choices":[{"finish_reason":"stop","index":0,"message":{"content":"This is a test result."}}],"object":"chat.completion"}},"error":null}

Run a formal task

Input file requirements

Format: UTF-8 encoded JSONL (one independent JSON object per line).
Size limits: Maximum 50,000 requests per file, maximum 500 MB.
Line limit: Each JSON object must not exceed 6 MB and must fit within the model's context window.
Consistency: All requests in the same file must use the same model and the same thinking mode (if applicable).
Unique identifier: Each request must include a unique custom_id field within the file. This field is used to match requests with results.

Scenario 1: Text chat

Example file content:

json

{"custom_id":"1","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-plus","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"Hello!"}]}}
{"custom_id":"2","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-plus","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is 2+2?"}]}}

Scenario 2: Image and video understanding

Multimodal models (e.g., qwen-vl-plus) support file URLs and Base64-encoded inputs.

json

{"custom_id":"image-url","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"image_url","image_url":{"url":"https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"}},{"type":"text","text":"Describe this image."}]}]}}
{"custom_id":"image-base64","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"image_url","image_url":{"url":"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEA8ADwAAD..."}},{"type":"text","text":"Describe this image."}]}]}}
{"custom_id":"video-url","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"video","video":"https://example.com/video.mp4"},{"type":"text","text":"Describe this video."}]}]}}
{"custom_id":"video-base64","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"video","video":["data:image/jpeg;base64,{frame1}","data:image/jpeg;base64,{frame2}","data:image/jpeg;base64,{frame3}"]},{"type":"text","text":"Describe this video."}]}]}}
{"custom_id":"multi-image-url","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"image_url","image_url":{"url":"https://example.com/image1.jpg"}},{"type":"image_url","image_url":{"url":"https://example.com/image2.jpg"}},{"type":"text","text":"Compare these two images."}]}]}}
{"custom_id":"multi-image-base64","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"image_url","image_url":{"url":"data:image/jpeg;base64,{image1_base64}"}},{"type":"image_url","image_url":{"url":"data:image/jpeg;base64,{image2_base64}"}},{"type":"text","text":"Compare these two images."}]}]}}

The Base64 strings in the examples above are truncated. Generate full encodings using the Python code below.

Pass Base64-encoded strings (using images as an example)

Convert a local file to Base64 encoding:

python

# Encoding function: Convert a local file to a Base64-encoded string
import base64
def encode_image(image_path):
       with open(image_path, "rb") as image_file:
           return base64.b64encode(image_file.read()).decode("utf-8")

# Replace xxx/eagle.png with the absolute path to your local image
base64_image = encode_image("xxx/eagle.png")

Build a Data URL format: data:[MIME_type];base64,{base64_image};
Replace MIME_type with the actual media type. It must match the MIME Type value (e.g., image/jpeg, image/png);
base64_image is the Base64 string generated in the previous step.

Note

For full details (including file limits, MIME types, and encoding methods), see Pass local files (Base64 encoding or file paths).

JSONL batch generation tool

Use this tool to quickly generate JSONL files.

JSONL batch generation tool

Select a mode:

Chinese Mainland (Beijing)International

**Select a model series:**Text generation modelMultimodal modelGeneral text embedding model

**Select a specific model:**qwen3-maxqwen-maxqwen-max-latestqwen-flash (thinking mode)qwen-flash (non-thinking mode)qwen-plus (thinking mode)qwen-plus (non-thinking mode)qwen-plus-latest (thinking mode)qwen-plus-latest (non-thinking mode)qwen-turbo (thinking mode)qwen-turbo (non-thinking mode)qwen-turbo-latest (thinking mode)qwen-turbo-latest (non-thinking mode)qwen-longqwen-long-latestqwq-plusqwq-32b-previewdeepseek-r1deepseek-v3

Enter your requests (one request per line):

**Paste your media URLs (one or more per line, separated by commas)😗*Enter your questions about the media:

Generate

Select a mode:

Chinese Mainland (Beijing)International

**Select a model series:**Text generation model

**Select a specific model:**qwen-maxqwen-plusqwen-flash (thinking mode)qwen-flash (non-thinking mode)qwen-turbo

Enter your requests (one request per line):

Generate

1. Modify the input file

In the test_model.jsonl file, set the model parameter to the target model and set the url field:

Model type	url


Model type	url
Text generation/multimodal models	`/v1/chat/completions`
Text embedding models	`/v1/embeddings`

Or use the "JSONL batch generation tool" above to generate a new file for formal tasks. Ensure the model and url fields are correct.

2. Modify the Getting Started code

Change the input file path to your file name.
Set the endpoint parameter to match the url field in your input file.

3. Run the code and wait for results

When the task completes, successful request results are saved to the local result.jsonl file. If any requests failed, the error details are saved to the error.jsonl file.

Successful results (output_file_id): Each line corresponds to one successful request and includes the custom_id and response.

json

{"id":"3a5c39d5-3981-4e4c-97f2-e0e821893f03","custom_id":"req-001","response":{"status_code":200,"request_id":"3a5c39d5-3981-4e4c-97f2-e0e821893f03","body":{"created":1768306034,"usage":{"completion_tokens":654,"prompt_tokens":14,"total_tokens":668},"model":"qwen-plus","id":"chatcmpl-3a5c39d5-3981-4e4c-97f2-e0e821893f03","choices":[{"finish_reason":"stop","index":0,"message":{"role":"assistant","content":"Hello! Hangzhou West Lake is a famous scenic spot in China, located in the western part of Hangzhou City, Zhejiang Province, hence the name \"West Lake\". It is one of China's top ten scenic spots and a World Cultural Heritage site (listed by UNESCO in 2011). It is renowned worldwide for its beautiful natural scenery and profound cultural heritage.\n\n### I. Natural Landscape\nWest Lake is surrounded by mountains on three sides and borders the city on one side, covering an area of approximately 6.39 square kilometers, shaped like a ruyi scepter with rippling blue waters. The lake is naturally or artificially divided into multiple water areas by Solitary Hill, Bai Causeway, Su Causeway, and Yanggong Causeway, forming a layout of \"one mountain, two pagodas, three islands, and three causeways\".\n\nMain attractions include the following:\n- **Spring Dawn at Su Causeway**: During the Northern Song Dynasty, the great literary figure Su Dongpo, while serving as the prefect of Hangzhou, led the dredging of West Lake and used the excavated silt to build a causeway, later named \"Su Causeway\". In spring, peach blossoms and willows create a picturesque scene.\n- **Lingering Snow on Broken Bridge**: Located at the eastern end of Bai Causeway, this is where the reunion scene from the Legend of the White Snake took place. After snowfall in winter, it is particularly famous for its silver-white appearance.\n- **Leifeng Pagoda at Sunset**: Leifeng Pagoda glows golden under the setting sun and was once one of the \"Ten Scenes of West Lake\".\n- **Three Pools Mirroring the Moon**: On Xiaoyingzhou Island in the lake, there are three stone pagodas. During the Mid-Autumn Festival, lanterns can be lit inside the pagodas, creating a harmonious interplay of moonlight, lamplight, and lake reflections.\n- **Autumn Moon over Calm Lake**: Located at the western end of Bai Causeway, it is an excellent spot for viewing the moon over the lake.\n- **Viewing Fish at Flower Harbor**: Known for viewing flowers and fish, with peonies and koi complementing each other beautifully in the garden.\n\n### II. Cultural History\nWest Lake not only boasts beautiful scenery but also carries rich historical and cultural significance:\n- Since the Tang and Song dynasties, numerous literati such as Bai Juyi, Su Dongpo, Lin Bu, and Yang Wanli have left poems here.\n- Bai Juyi oversaw the construction of \"Bai Causeway\" and dredged West Lake, benefiting the local people.\n- Around West Lake are many historical sites, including Yuewang Temple (commemorating national hero Yue Fei), Lingyin Temple (a millennium-old Buddhist temple), Liuhe Pagoda, and Longjing Village (the origin of Longjing tea, one of China's top ten famous teas).\n\n### III. Cultural Symbolism\nWest Lake is regarded as a representative of \"paradise on earth\" and a model of traditional Chinese landscape aesthetics. It embodies the philosophical concept of \"harmony between heaven and humanity\" by integrating natural beauty with cultural depth. Many poems, paintings, and operas feature West Lake, making it an important symbol of Chinese culture.\n\n### IV. Travel Recommendations\n- Best visiting seasons: Spring (March-May) for peach blossoms and willows, Autumn (September-November) for clear skies and cool weather.\n- Recommended ways: Walking, cycling (along the lakeside greenway), or boating on the lake.\n- Local cuisine: West Lake vinegar fish, Longjing shrimp, Dongpo pork, pian'erchuan noodles.\n\nIn summary, Hangzhou West Lake is not just a natural wonder but also a living cultural museum worth exploring in detail. If you ever visit Hangzhou, don't miss this earthly paradise that is \"equally charming in light or heavy makeup\"."}}],"object":"chat.completion"}},"error":null}
{"id":"628312ba-172c-457d-ba7f-3e5462cc6899","custom_id":"req-002","response":{"status_code":200,"request_id":"628312ba-172c-457d-ba7f-3e5462cc6899","body":{"created":1768306035,"usage":{"completion_tokens":25,"prompt_tokens":18,"total_tokens":43},"model":"qwen-plus","id":"chatcmpl-628312ba-172c-457d-ba7f-3e5462cc6899","choices":[{"finish_reason":"stop","index":0,"message":{"role":"assistant","content":"The spring breeze brushes green willows,\nNight rain nourishes red flowers.\nBird songs fill the forest,\nMountains and rivers share the same beauty."}}],"object":"chat.completion"}},"error":null}

Failure details (error_file_id): Contains information about failed requests with line numbers and error reasons. See Error codes for troubleshooting.

Detailed procedure

The Batch API workflow consists of four steps: upload a file, create a task, query task status, and download results.

1. Upload file

Upload your JSONL file using the file upload API to obtain a file_id.

When uploading a file, the purpose parameter must be batch .

Note

python

batch = client.batches.create(
    input_file_id="file-batch-xxx",  # Reuse existing file ID, no need to re-upload
    endpoint="/v1/chat/completions",
    completion_window="24h"
)

You can retrieve historical file IDs through the client.files.list(purpose="batch") API to query uploaded Batch file IDs.

OpenAI Python SDK

OpenAI Node.js SDK

Java (HTTP)

curl (HTTP)

Request example

python

import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    # If no environment variable is set, use api_key="sk-xxx" (not in production - risk of leaks).
    # API keys differ between regions.
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Singapore region's base_url. For Beijing, use: https://dashscope.aliyuncs.com/compatible-mode/v1 and update the API key.
    # Note: When switching regions, also update the API key accordingly.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# test.jsonl is a local sample file. purpose must be batch.
file_object = client.files.create(file=Path("test.jsonl"), purpose="batch")

print(file_object.model_dump_json())

Request example

javascript

/**
 * Model Studio Batch API - Upload file
 *
 * If no environment variable is set, use apiKey: 'sk-xxx' (not in production - risk of leaks).
 * API keys differ between regions.
 *
 * Install dependencies: npm install openai
 */
const OpenAI = require('openai');
const fs = require('fs');

// Singapore region configuration (default)
const BASE_URL = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1';
// If using the Beijing region, replace the above BASE_URL with:
// const BASE_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1';
// Note: When switching regions, also update the API key accordingly.

const apiKey = process.env.DASHSCOPE_API_KEY;
if (!apiKey) {
    console.error('Error: Please set the environment variable DASHSCOPE_API_KEY');
    console.error('Or set in code: const apiKey = "sk-xxx";');
    process.exit(1);
}

const client = new OpenAI({
    apiKey: apiKey,
    baseURL: BASE_URL
});

const fileStream = fs.createReadStream('test.jsonl');
const fileObject = await client.files.create({
    file: fileStream,
    purpose: 'batch'
});
console.log(fileObject.id);

Request example

java

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Scanner;
import java.util.regex.Pattern;
import java.util.regex.Matcher;

/**
 * Model Studio Batch API - Upload file
 *
 * If no environment variable is set, use API_KEY = "sk-xxx" (not in production - risk of leaks).
 * API keys differ between regions.
 *
 * Region configuration:
 * - Beijing region: https://dashscope.aliyuncs.com/compatible-mode/v1
 * - Singapore region: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
 * Note: When switching regions, also update the API key accordingly.
 */
public class BatchAPIUploadFile {

    // Singapore region configuration
    private static final String BASE_URL = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1";
    // For Beijing, use: private static final String BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"; and update the API key.

    private static String API_KEY;

    public static void main(String[] args) throws Exception {
        API_KEY = System.getenv("DASHSCOPE_API_KEY");
        if (API_KEY == null || API_KEY.isEmpty()) {
            System.err.println("Error: Please set the environment variable DASHSCOPE_API_KEY");
            System.err.println("Or set in code: API_KEY = \"sk-xxx\";");
            System.exit(1);
        }

String fileId = uploadFile("test.jsonl");
        System.out.println("File ID: " + fileId);
    }

    // === Utility methods ===

    private static String uploadFile(String filePath) throws Exception {
        String boundary = "----WebKitFormBoundary" + System.currentTimeMillis();
        URL url = new URL(BASE_URL + "/files");
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setDoOutput(true);
        conn.setRequestMethod("POST");
        conn.setRequestProperty("Authorization", "Bearer " + API_KEY);
        conn.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);

        try (DataOutputStream out = new DataOutputStream(conn.getOutputStream())) {
            // Add purpose field
            out.writeBytes("--" + boundary + "\r\n");
            out.writeBytes("Content-Disposition: form-data; name=\"purpose\"\r\n\r\n");
            out.writeBytes("batch\r\n");

            // Add file
            out.writeBytes("--" + boundary + "\r\n");
            out.writeBytes("Content-Disposition: form-data; name=\"file\"; filename=\"" + filePath + "\"\r\n");
            out.writeBytes("Content-Type: application/octet-stream\r\n\r\n");

            byte[] fileBytes = Files.readAllBytes(Paths.get(filePath));
            out.write(fileBytes);
            out.writeBytes("\r\n");
            out.writeBytes("--" + boundary + "--\r\n");
        }

        String response = readResponse(conn);
        return parseField(response, "\"id\":\\s*\"([^\"]+)\"");
    }

    private static String readResponse(HttpURLConnection conn) throws Exception {
        int responseCode = conn.getResponseCode();
        InputStream is = (responseCode < 400) ? conn.getInputStream() : conn.getErrorStream();
        try (Scanner scanner = new Scanner(is, "UTF-8").useDelimiter("\\A")) {
            return scanner.hasNext() ? scanner.next() : "";
        }
    }

    private static String parseField(String json, String regex) {
        Pattern pattern = Pattern.compile(regex);
        Matcher matcher = pattern.matcher(json);
        return matcher.find() ? matcher.group(1) : null;
    }
}

Request example

curl

# ======= Important =======
# API keys differ between Singapore and Beijing regions.
# The following is the base_url for the Singapore region. If you use a model in the Beijing region, replace the base_url with: https://dashscope.aliyuncs.com/compatible-mode/v1/files
# === Delete this comment before execution ===
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/files \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
--form 'file=@"test.jsonl"' \
--form 'purpose="batch"'

Response example

json

{
    "id": "file-batch-xxx",
    "bytes": 437,
    "created_at": 1742304153,
    "filename": "test.jsonl",
    "object": "file",
    "purpose": "batch",
    "status": "processed",
    "status_details": null
}

2. Create a batch task

Create a batch task using the file ID obtained from the file upload step.

OpenAI Python SDK

OpenAI Node.js SDK

Java (HTTP)

curl (HTTP)

Request example

python

import os
from openai import OpenAI

client = OpenAI(
    # If no environment variable is set, use api_key="sk-xxx" (not in production - risk of leaks).
    # API keys differ between regions.
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Singapore region's base_url. For Beijing, use: https://dashscope.aliyuncs.com/compatible-mode/v1 and update the API key.
    # Note: When switching regions, also update the API key accordingly.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

batch = client.batches.create(
    input_file_id="file-batch-xxx",  # The ID returned after uploading the file
    endpoint="/v1/chat/completions",  # For the test model batch-test-model, use /v1/chat/ds-test. For text embedding models, use /v1/embeddings. For text generation/multimodal models, use /v1/chat/completions.
    completion_window="24h",
    metadata={'ds_name':"Task name",'ds_description':'Task description'} # Optional metadata field for creating task name and description
)
print(batch)

Request example

javascript

/**
 * Model Studio Batch API - Create batch task
 *
 * If no environment variable is set, use apiKey: 'sk-xxx' (not in production - risk of leaks).
 * API keys differ between regions.
 *
 * Install dependencies: npm install openai
 */
const OpenAI = require('openai');

// Singapore region configuration (default)
const BASE_URL = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1';
// If using the Beijing region, replace the above BASE_URL with:
// const BASE_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1';
// Note: When switching regions, also update the API key accordingly.

const apiKey = process.env.DASHSCOPE_API_KEY;
if (!apiKey) {
    console.error('Error: Please set the environment variable DASHSCOPE_API_KEY');
    console.error('Or set in code: const apiKey = "sk-xxx";');
    process.exit(1);
}

const client = new OpenAI({
    apiKey: apiKey,
    baseURL: BASE_URL
});

const batch = await client.batches.create({
    input_file_id: 'file-batch-xxx',
    endpoint: '/v1/chat/completions',
    completion_window: '24h',
    metadata: {'ds_name': 'Task name', 'ds_description': 'Task description'}
});
console.log(batch.id);

Request example

java

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;
import java.util.regex.Pattern;
import java.util.regex.Matcher;

/**
 * Model Studio Batch API - Create batch task
 *
 * If no environment variable is set, use API_KEY = "sk-xxx" (not in production - risk of leaks).
 * API keys differ between regions.
 *
 * Region configuration:
 * - Beijing region: https://dashscope.aliyuncs.com/compatible-mode/v1
 * - Singapore region: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
 * Note: When switching regions, also update the API key accordingly.
 */
public class BatchAPICreateBatch {

    // Singapore region configuration (default)
    private static final String BASE_URL = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1";
    // For Beijing, use: private static final String BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"; and update the API key.

    private static String API_KEY;

    public static void main(String[] args) throws Exception {
        API_KEY = System.getenv("DASHSCOPE_API_KEY");
        if (API_KEY == null || API_KEY.isEmpty()) {
            System.err.println("Error: Please set the environment variable DASHSCOPE_API_KEY");
            System.err.println("Or set in code: API_KEY = \"sk-xxx\";");
            System.exit(1);
        }

        String jsonBody = "{\"input_file_id\":\"file-batch-xxx\",\"endpoint\":\"/v1/chat/completions\",\"completion_window\":\"24h\",\"metadata\":{\"ds_name\":\"Task name\",\"ds_description\":\"Task description\"}}";
String response = sendRequest("POST", "/batches", jsonBody);
        String batchId = parseField(response, "\"id\":\\s*\"([^\"]+)\"");
        System.out.println("Batch task ID: " + batchId);
    }

    // === Utility methods ===

    private static String sendRequest(String method, String path, String jsonBody) throws Exception {
        URL url = new URL(BASE_URL + path);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod(method);
        conn.setRequestProperty("Authorization", "Bearer " + API_KEY);

        if (jsonBody != null) {
            conn.setDoOutput(true);
            conn.setRequestProperty("Content-Type", "application/json");
            try (OutputStream os = conn.getOutputStream()) {
                os.write(jsonBody.getBytes("UTF-8"));
            }
        }

        return readResponse(conn);
    }

    private static String readResponse(HttpURLConnection conn) throws Exception {
        int responseCode = conn.getResponseCode();
        InputStream is = (responseCode < 400) ? conn.getInputStream() : conn.getErrorStream();
        try (Scanner scanner = new Scanner(is, "UTF-8").useDelimiter("\\A")) {
            return scanner.hasNext() ? scanner.next() : "";
        }
    }

    private static String parseField(String json, String regex) {
        Pattern pattern = Pattern.compile(regex);
        Matcher matcher = pattern.matcher(json);
        return matcher.find() ? matcher.group(1) : null;
    }
}

Request example

curl

# ======= Important =======
# API keys differ between Singapore and Beijing regions.
# The following is the base_url for the Singapore region. If you use a model in the Beijing region, replace the base_url with: https://dashscope.aliyuncs.com/compatible-mode/v1/batches
# === Delete this comment before execution ===
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/batches \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-batch-xxx",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h",
    "metadata":{"ds_name":"Task name","ds_description":"Task description"}
  }'

Input parameters


Field	Type	Method	Required	Description
input_file_id	String	Body	Yes	The input file ID. Use the file ID returned by the Prepare and upload file API, such as `file-batch-xxx`.
endpoint	String	Body	Yes	The API access path. Must match the url field in the input file. - For the test model `batch-test-model`, enter `/v1/chat/ds-test` - For other models, enter `/v1/chat/completions`
completion_window	String	Body	Yes	Maximum wait time. Range: 24h-336h, integers only. Units: "h" or "d" (e.g., "24h" or "14d").
metadata	Map	Body	No	Extended metadata for the task, specified as key-value pairs.
metadata.ds_name	String	Body	No	Task name. Example: `"ds_name": "Batch task"` Maximum length: 100 characters. If specified multiple times, the last value takes effect.
metadata.ds_description	String	Body	No	Task description. Example: `"ds_description": "Batch inference task test"` Maximum length: 200 characters. If specified multiple times, the last value takes effect.

Response example

json

{
    "id": "batch_xxx",
    "object": "batch",
    "endpoint": "/v1/chat/completions",
    "errors": null,
    "input_file_id": "file-batch-xxx",
    "completion_window": "24h",
    "status": "validating",
    "output_file_id": null,
    "error_file_id": null,
    "created_at": 1742367779,
    "in_progress_at": null,
    "expires_at": null,
    "finalizing_at": null,
    "completed_at": null,
    "failed_at": null,
    "expired_at": null,
    "cancelling_at": null,
    "cancelled_at": null,
    "request_counts": {
        "total": 0,
        "completed": 0,
        "failed": 0
    },
    "metadata": {
        "ds_name": "Task name",
        "ds_description": "Task description"
    }
}

Response parameters


Field	Type	Description
id	String	The batch task ID.
object	String	Fixed value: `batch`.
endpoint	String	The API access path.
errors	Map	Error information.
input_file_id	String	Input file ID .
completion_window	String	Maximum wait time. Range: 24h-336h, integers only. Units: "h" or "d" (e.g., "24h" or "14d").
status	String	Task status: validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled.
output_file_id	String	File ID for successful request results.
error_file_id	String	File ID for failed request results.
created_at	Integer	Unix timestamp (seconds) when the task was created.
in_progress_at	Integer	Unix timestamp (seconds) when the task started processing.
expires_at	Integer	Unix timestamp (seconds) when the task starts timing out.
finalizing_at	Integer	Unix timestamp (seconds) when the task last started.
completed_at	Integer	Unix timestamp (seconds) when the task completed.
failed_at	Integer	Unix timestamp (seconds) when the task failed.
expired_at	Integer	Unix timestamp (seconds) when the task expired.
cancelling_at	Integer	Unix timestamp (seconds) when the task entered the cancelling state.
cancelled_at	Integer	Unix timestamp (seconds) when the task was cancelled.
request_counts	Map	Request counts by state.
metadata	Map	Additional metadata as key-value pairs.
metadata.ds_name	String	Task name.
metadata.ds_description	String	Task description.

3. Query and manage batch tasks

After creating a task, use the following APIs to query its status, list historical tasks, or cancel an ongoing task.

Query specific task status

Query a batch task by its ID. Only tasks created within the past 30 days can be queried.

OpenAI Python SDK

OpenAI Node.js SDK

Java (HTTP)

curl (HTTP)

Request example

python

import os
from openai import OpenAI

client = OpenAI(
    # If no environment variable is set, use api_key="sk-xxx" (not in production - risk of leaks).
    # API keys differ between regions.
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Singapore region's base_url. For Beijing, use: https://dashscope.aliyuncs.com/compatible-mode/v1 and update the API key.
    # Note: When switching regions, also update the API key accordingly.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
batch = client.batches.retrieve("batch_id")  # Replace batch_id with the batch task ID
print(batch)

Request example

javascript

/**
 * Model Studio Batch API - Query single task
 *
 * If no environment variable is set, use apiKey: 'sk-xxx' (not in production - risk of leaks).
 * API keys differ between regions.
 *
 * Install dependencies: npm install openai
 */
const OpenAI = require('openai');

// Singapore region configuration (default)
const BASE_URL = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1';
// If using the Beijing region, replace the above BASE_URL with:
// const BASE_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1';
// Note: When switching regions, also update the API key accordingly.

const apiKey = process.env.DASHSCOPE_API_KEY;
if (!apiKey) {
    console.error('Error: Please set the environment variable DASHSCOPE_API_KEY');
    console.error('Or set in code: const apiKey = "sk-xxx";');
    process.exit(1);
}

const client = new OpenAI({
    apiKey: apiKey,
    baseURL: BASE_URL
});

const batch = await client.batches.retrieve('batch_id');
console.log(batch.status);

Request example

java

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;
import java.util.regex.Pattern;
import java.util.regex.Matcher;

/**
 * Model Studio Batch API - Query single task
 *
 * If no environment variable is set, use API_KEY = "sk-xxx" (not in production - risk of leaks).
 * API keys differ between regions.
 *
 * Region configuration:
 * - Beijing region: https://dashscope.aliyuncs.com/compatible-mode/v1
 * - Singapore region: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
 * Note: When switching regions, also update the API key accordingly.
 */
public class BatchAPIRetrieveBatch {

    // Singapore region configuration
    private static final String BASE_URL = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1";
    // For Beijing, use: private static final String BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"; and update the API key.

    private static String API_KEY;

    public static void main(String[] args) throws Exception {
        API_KEY = System.getenv("DASHSCOPE_API_KEY");
        if (API_KEY == null || API_KEY.isEmpty()) {
            System.err.println("Error: Please set the environment variable DASHSCOPE_API_KEY");
            System.err.println("Or set in code: API_KEY = \"sk-xxx\";");
            System.exit(1);
        }

        String batchInfo = sendRequest("GET", "/batches/batch_id", null);
        String status = parseField(batchInfo, "\"status\":\\s*\"([^\"]+)\"");
        System.out.println("Task status: " + status);
    }

    // === Utility methods ===

    private static String sendRequest(String method, String path, String jsonBody) throws Exception {
        URL url = new URL(BASE_URL + path);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod(method);
        conn.setRequestProperty("Authorization", "Bearer " + API_KEY);

        if (jsonBody != null) {
            conn.setDoOutput(true);
            conn.setRequestProperty("Content-Type", "application/json");
            try (OutputStream os = conn.getOutputStream()) {
                os.write(jsonBody.getBytes("UTF-8"));
            }
        }

        return readResponse(conn);
    }

    private static String readResponse(HttpURLConnection conn) throws Exception {
        int responseCode = conn.getResponseCode();
        InputStream is = (responseCode < 400) ? conn.getInputStream() : conn.getErrorStream();
        try (Scanner scanner = new Scanner(is, "UTF-8").useDelimiter("\\A")) {
            return scanner.hasNext() ? scanner.next() : "";
        }
    }

    private static String parseField(String json, String regex) {
        Pattern pattern = Pattern.compile(regex);
        Matcher matcher = pattern.matcher(json);
        return matcher.find() ? matcher.group(1) : null;
    }
}

Request example

curl

# ======= Important =======
# API keys differ between Singapore and Beijing regions.
# The following is the base_url for the Singapore region. If you use a model in the Beijing region, replace the base_url with: https://dashscope.aliyuncs.com/compatible-mode/v1/batches/batch_id
# === Delete this comment before execution ===
curl --request GET 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/batches/batch_id' \
 -H "Authorization: Bearer $DASHSCOPE_API_KEY"

Response example

A successful query returns detailed batch task information. The following is a response example for a task with completed status:

json

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "completed",
  "output_file_id": "file-batch_output-xyz789",
  "error_file_id": "file-batch_error-xyz789",
  "created_at": 1711402400,
  "in_progress_at": 1711402450,
  "expires_at": 1711488800,
  "finalizing_at": 1711405000,
  "completed_at": 1711406000,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 100,
    "completed": 95,
    "failed": 5
  },
  "metadata": {
    "customer_id": "user_123456789",
    "batch_description": "Nightly eval job"
  }
}

For field descriptions, see the table below.


Field	Type	Description
id	String	Batch task ID.
status	String	Task status. Possible values: - validating - in_progress - finalizing - completed - failed - expired - cancelling - cancelled
output_file_id	String	ID of the output file containing successful results. Generated after task completion.
error_file_id	String	ID of the error file containing failed request details. Generated after task completion if any requests failed.
request_counts	Object	Request count statistics containing total, completed, and failed counts.

Query task list

Use the batches.list() method to retrieve the list of batch tasks. Use pagination to retrieve the full task list.

OpenAI Python SDK

OpenAI Node.js SDK

Java (HTTP)

curl (HTTP)

Request example

python

import os
from openai import OpenAI

client = OpenAI(
    # If no environment variable is set, use api_key="sk-xxx" (not in production - risk of leaks).
    # API keys differ between regions.
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Singapore region's base_url. For Beijing, use: https://dashscope.aliyuncs.com/compatible-mode/v1 and update the API key.
    # Note: When switching regions, also update the API key accordingly.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
batches = client.batches.list(after="batch_xxx", limit=2,extra_query={'ds_name':'Task name','input_file_ids':'file-batch-xxx,file-batch-xxx','status':'completed,expired','create_after':'20250304000000','create_before':'20250306123000'})
print(batches)

Request example

javascript

/**
 * Model Studio Batch API - Query task list
 *
 * If no environment variable is set, use apiKey: 'sk-xxx' (not in production - risk of leaks).
 * API keys differ between regions.
 *
 * Install dependencies: npm install openai
 */
const OpenAI = require('openai');

// Singapore region configuration (default)
const BASE_URL = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1';
// If using the Beijing region, replace the above BASE_URL with:
// const BASE_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1';
// Note: When switching regions, also update the API key accordingly.

const apiKey = process.env.DASHSCOPE_API_KEY;
if (!apiKey) {
    console.error('Error: Please set the environment variable DASHSCOPE_API_KEY');
    console.error('Or set in code: const apiKey = "sk-xxx";');
    process.exit(1);
}

const client = new OpenAI({
    apiKey: apiKey,
    baseURL: BASE_URL
});

const batches = await client.batches.list({
    after: 'batch_xxx',
    limit: 2,
    extra_query: {
        'ds_name': 'Task name',
        'input_file_ids': 'file-batch-xxx,file-batch-xxx',
        'status': 'completed,expired',
        'create_after': '20250304000000',
        'create_before': '20250306123000'
    }
});

for (const batch of batches.data) {
    console.log(batch.id, batch.status);
}

Request example

java

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;
import java.util.regex.Pattern;
import java.util.regex.Matcher;

/**
 * Model Studio Batch API - Query task list
 *
 * If no environment variable is set, use API_KEY = "sk-xxx" (not in production - risk of leaks).
 * API keys differ between regions.
 *
 * Region configuration:
 * - Beijing region: https://dashscope.aliyuncs.com/compatible-mode/v1
 * - Singapore region: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
 * Note: When switching regions, also update the API key accordingly.
 */
public class BatchAPIListBatches {

    // Singapore region configuration
    private static final String BASE_URL = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1";
    // For Beijing, use: private static final String BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"; and update the API key.

    private static String API_KEY;

    public static void main(String[] args) throws Exception {
        API_KEY = System.getenv("DASHSCOPE_API_KEY");
        if (API_KEY == null || API_KEY.isEmpty()) {
            System.err.println("Error: Please set the environment variable DASHSCOPE_API_KEY");
            System.err.println("Or set in code: API_KEY = \"sk-xxx\";");
            System.exit(1);
        }

        String response = sendRequest("GET", "/batches?after=batch_xxx&limit=2&ds_name=Batch&input_file_ids=file-batch-xxx,file-batch-xxx&status=completed,failed&create_after=20250303000000&create_before=20250320000000", null);
// Parse JSON to get task list
        System.out.println(response);
    }

    // === Utility methods ===

    private static String sendRequest(String method, String path, String jsonBody) throws Exception {
        URL url = new URL(BASE_URL + path);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod(method);
        conn.setRequestProperty("Authorization", "Bearer " + API_KEY);

        if (jsonBody != null) {
            conn.setDoOutput(true);
            conn.setRequestProperty("Content-Type", "application/json");
            try (OutputStream os = conn.getOutputStream()) {
                os.write(jsonBody.getBytes("UTF-8"));
            }
        }

        return readResponse(conn);
    }

    private static String readResponse(HttpURLConnection conn) throws Exception {
        int responseCode = conn.getResponseCode();
        InputStream is = (responseCode < 400) ? conn.getInputStream() : conn.getErrorStream();
        try (Scanner scanner = new Scanner(is, "UTF-8").useDelimiter("\\A")) {
            return scanner.hasNext() ? scanner.next() : "";
        }
    }

    private static String parseField(String json, String regex) {
        Pattern pattern = Pattern.compile(regex);
        Matcher matcher = pattern.matcher(json);
        return matcher.find() ? matcher.group(1) : null;
    }
}

Request example

curl

# ======= Important =======
# API keys differ between Singapore and Beijing regions.
# The following is the base_url for the Singapore region. If you use a model in the Beijing region, replace the base_url with: https://dashscope.aliyuncs.com/compatible-mode/v1/batches?xxx same as below xxx
# === Delete this comment before execution ===
curl --request GET  'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/batches?after=batch_xxx&limit=2&ds_name=Batch&input_file_ids=file-batch-xxx,file-batch-xxx&status=completed,failed&create_after=20250303000000&create_before=20250320000000' \
 -H "Authorization: Bearer $DASHSCOPE_API_KEY"

Replace batch_id in after=batch_id with the actual value. Set limit to the number of tasks to return. Specify a partial task name for ds_name . For input_file_ids, specify one or more file IDs. Specify one or more batch task statuses for status . For create_after and create_before , specify the time boundaries.

Input parameters


Field	Type	Method	Required	Description
after	String	Query	No	Cursor for pagination. Set this to the last task ID from the previous page.
limit	Integer	Query	No	Number of tasks per page. Range: [1, 100]. Default: 20.
ds_name	String	Query	No	Fuzzy match by task name.
input_file_ids	String	Query	No	Filter by file IDs. Specify multiple IDs separated by commas (up to 20).
status	String	Query	No	Filter by task status. Specify multiple statuses separated by commas.
create_after	String	Query	No	Filter tasks created after this time. Format: `yyyyMMddHHmmss`.
create_before	String	Query	No	Filter tasks created before this time. Format: `yyyyMMddHHmmss`.

Response example

json

{
  "object": "list",
  "data": [\
    {\
      "id": "batch_xxx",\
      "object": "batch",\
      "endpoint": "/v1/chat/completions",\
      "errors": null,\
      "input_file_id": "file-batch-xxx",\
      "completion_window": "24h",\
      "status": "completed",\
      "output_file_id": "file-batch_output-xxx",\
      "error_file_id": null,\
      "created_at": 1722234109,\
      "in_progress_at": 1722234109,\
      "expires_at": null,\
      "finalizing_at": 1722234165,\
      "completed_at": 1722234165,\
      "failed_at": null,\
      "expired_at": null,\
      "cancelling_at": null,\
      "cancelled_at": null,\
      "request_counts": {\
        "total": 100,\
        "completed": 95,\
        "failed": 5\
      },\
      "metadata": {}\
    },\
    { ... }\
  ],
  "first_id": "batch_xxx",
  "last_id": "batch_xxx",
  "has_more": true
}

Response parameters


Field	Type	Description
object	String	Object type. Fixed value: list.
data	Array	Array of batch task objects. See the response parameters for creating a batch task.
first_id	String	ID of the first batch task on the current page.
last_id	String	ID of the last batch task on the current page.
has_more	Boolean	Whether additional pages are available.

Cancel batch task

Cancel a task that is in progress or queued. After a successful call, the task status changes to cancelling and then to cancelled. You are still billed for requests that completed before the cancellation takes full effect.

OpenAI Python SDK

OpenAI Node.js SDK

Java (HTTP)

curl (HTTP)

Request example

python

import os
from openai import OpenAI

client = OpenAI(
    # If no environment variable is set, use api_key="sk-xxx" (not in production - risk of leaks).
    # API keys differ between regions.
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Singapore region's base_url. For Beijing, use: https://dashscope.aliyuncs.com/compatible-mode/v1 and update the API key.
    # Note: When switching regions, also update the API key accordingly.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
batch = client.batches.cancel("batch_id")  # Replace batch_id with the batch task ID
print(batch)

Request example

javascript

/**
 * Model Studio Batch API - Cancel task
 *
 * If no environment variable is set, use apiKey: 'sk-xxx' (not in production - risk of leaks).
 * API keys differ between regions.
 *
 * Install dependencies: npm install openai
 */
const OpenAI = require('openai');

// Singapore region configuration (default)
const BASE_URL = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1';
// If using the Beijing region, replace the above BASE_URL with:
// const BASE_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1';
// Note: When switching regions, also update the API key accordingly.

const apiKey = process.env.DASHSCOPE_API_KEY;
if (!apiKey) {
    console.error('Error: Please set the environment variable DASHSCOPE_API_KEY');
    console.error('Or set in code: const apiKey = "sk-xxx";');
    process.exit(1);
}

const client = new OpenAI({
    apiKey: apiKey,
    baseURL: BASE_URL
});

const batch = await client.batches.cancel('batch_id');
console.log(batch.status); // cancelled

Request example

java

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;
import java.util.regex.Pattern;
import java.util.regex.Matcher;

/**
 * Model Studio Batch API - Cancel task
 *
 * If no environment variable is set, use API_KEY = "sk-xxx" (not in production - risk of leaks).
 * API keys differ between regions.
 *
 * Region configuration:
 * - Beijing region: https://dashscope.aliyuncs.com/compatible-mode/v1
 * - Singapore region: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
 * Note: When switching regions, also update the API key accordingly.
 */
public class BatchAPICancelBatch {

    // Singapore region configuration
    private static final String BASE_URL = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1";
    // For Beijing, use: private static final String BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"; and update the API key.

    private static String API_KEY;

    public static void main(String[] args) throws Exception {
        API_KEY = System.getenv("DASHSCOPE_API_KEY");
        if (API_KEY == null || API_KEY.isEmpty()) {
            System.err.println("Error: Please set the environment variable DASHSCOPE_API_KEY");
            System.err.println("Or set in code: API_KEY = \"sk-xxx\";");
            System.exit(1);
        }

        String response = sendRequest("POST", "/batches/batch_id/cancel", null);
        System.out.println(response);
    }

    // === Utility methods ===

    private static String sendRequest(String method, String path, String jsonBody) throws Exception {
        URL url = new URL(BASE_URL + path);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod(method);
        conn.setRequestProperty("Authorization", "Bearer " + API_KEY);

        if (jsonBody != null) {
            conn.setDoOutput(true);
            conn.setRequestProperty("Content-Type", "application/json");
            try (OutputStream os = conn.getOutputStream()) {
                os.write(jsonBody.getBytes("UTF-8"));
            }
        }

        return readResponse(conn);
    }

    private static String readResponse(HttpURLConnection conn) throws Exception {
        int responseCode = conn.getResponseCode();
        InputStream is = (responseCode < 400) ? conn.getInputStream() : conn.getErrorStream();
        try (Scanner scanner = new Scanner(is, "UTF-8").useDelimiter("\\A")) {
            return scanner.hasNext() ? scanner.next() : "";
        }
    }

    private static String parseField(String json, String regex) {
        Pattern pattern = Pattern.compile(regex);
        Matcher matcher = pattern.matcher(json);
        return matcher.find() ? matcher.group(1) : null;
    }
}

Request example

curl

# ======= Important =======
# API keys differ between Singapore and Beijing regions.
# The following is the base_url for the Singapore region. If you use a model in the Beijing region, replace the base_url with: https://dashscope.aliyuncs.com/compatible-mode/v1/batches/batch_id/cancel
# === Delete this comment before execution ===
curl --request POST 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/batches/batch_id/cancel' \
 -H "Authorization: Bearer $DASHSCOPE_API_KEY"

Replace batch_id with the actual value.

Response example

After you successfully cancel a task, the API returns detailed batch task information. The following is a response example for a task in cancelling status:

json

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "cancelling",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1711402400,
  "in_progress_at": 1711402450,
  "expires_at": 1711488800,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": 1711403000,
  "cancelled_at": null,
  "request_counts": {
    "total": 100,
    "completed": 23,
    "failed": 1
  },
  "metadata": null
}

After you cancel a task, the status first changes to cancelling while the system waits for currently executing requests to complete. The status eventually changes to cancelled . Results from completed requests are still saved in the output file.

4. Download Batch result file

After a task completes, result files (output_file_id) and error files (error_file_id) may be generated. Download both file types using the same file download API.

You can download only files whose file_id starts with file-batch_output.

OpenAI Python SDK

OpenAI Node.js SDK

Java (HTTP)

curl (HTTP)

Use the content method to retrieve the batch task result file content and use the write_to_file method to save it locally.

Request example

python

import os
from openai import OpenAI

client = OpenAI(
    # If no environment variable is set, use api_key="sk-xxx" (not in production - risk of leaks).
    # API keys differ between regions.
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Singapore region's base_url. For Beijing, use: https://dashscope.aliyuncs.com/compatible-mode/v1 and update the API key.
    # Note: When switching regions, also update the API key accordingly.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
content = client.files.content(file_id="file-batch_output-xxx")
# Print result file content
print(content.text)
# Save result file locally
content.write_to_file("result.jsonl")

Response example

json

{"id":"c308ef7f-xxx","custom_id":"1","response":{"status_code":200,"request_id":"c308ef7f-0824-9c46-96eb-73566f062426","body":{"created":1742303743,"usage":{"completion_tokens":35,"prompt_tokens":26,"total_tokens":61},"model":"qwen-plus","id":"chatcmpl-c308ef7f-0824-9c46-96eb-73566f062426","choices":[{"finish_reason":"stop","index":0,"message":{"content":"Hello! Of course. Whether you need information, learning materials, problem-solving methods, or any other help, I am here to support you. Please tell me what you need help with."}}],"object":"chat.completion"}},"error":null}
{"id":"73291560-xxx","custom_id":"2","response":{"status_code":200,"request_id":"73291560-7616-97bf-87f2-7d747bbe84fd","body":{"created":1742303743,"usage":{"completion_tokens":7,"prompt_tokens":26,"total_tokens":33},"model":"qwen-plus","id":"chatcmpl-73291560-7616-97bf-87f2-7d747bbe84fd","choices":[{"finish_reason":"stop","index":0,"message":{"content":"2+2 equals 4."}}],"object":"chat.completion"}},"error":null}

Use the content method to retrieve the batch task result file content.

Request example

javascript

/**
 * Model Studio Batch API - Download result file
 *
 * If no environment variable is set, use apiKey: 'sk-xxx' (not in production - risk of leaks).
 * API keys differ between regions.
 *
 * Install dependencies: npm install openai
 */
const OpenAI = require('openai');
const fs = require('fs');

// Singapore region configuration (default)
const BASE_URL = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1';
// If using the Beijing region, replace the above BASE_URL with:
// const BASE_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1';
// Note: When switching regions, also update the API key accordingly.

const apiKey = process.env.DASHSCOPE_API_KEY;
if (!apiKey) {
    console.error('Error: Please set the environment variable DASHSCOPE_API_KEY');
    console.error('Or set in code: const apiKey = "sk-xxx";');
    process.exit(1);
}

const client = new OpenAI({
    apiKey: apiKey,
    baseURL: BASE_URL
});

// Download result file
const content = await client.files.content('file-batch_output-xxx');
const text = await content.text();
console.log(text);

// Save to local file
fs.writeFileSync('result.jsonl', text);
console.log('Results saved to result.jsonl');

Use a GET request to the /files/{file_id}/content endpoint to download the file content.

Request example

java

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Scanner;
import java.util.regex.Pattern;
import java.util.regex.Matcher;

/**
 * Model Studio Batch API - Download result file
 *
 * If no environment variable is set, use API_KEY = "sk-xxx" (not in production - risk of leaks).
 * API keys differ between regions.
 *
 * Region configuration:
 * - Beijing region: https://dashscope.aliyuncs.com/compatible-mode/v1
 * - Singapore region: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
 * Note: When switching regions, also update the API key accordingly.
 */
public class BatchAPIDownloadFile {

    // Singapore region configuration
    private static final String BASE_URL = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1";
    // For Beijing, use: private static final String BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"; and update the API key.

    private static String API_KEY;

    public static void main(String[] args) throws Exception {
        API_KEY = System.getenv("DASHSCOPE_API_KEY");
        if (API_KEY == null || API_KEY.isEmpty()) {
            System.err.println("Error: Please set the environment variable DASHSCOPE_API_KEY");
            System.err.println("Or set in code: API_KEY = \"sk-xxx\";");
            System.exit(1);
        }

// Download result file
String content = sendRequest("GET", "/files/file-batch_output-xxx/content", null);
System.out.println(content);

// Save to local file
        Files.write(Paths.get("result.jsonl"), content.getBytes());
        System.out.println("Results saved to result.jsonl");
    }

    // === Utility methods ===

    private static String sendRequest(String method, String path, String jsonBody) throws Exception {
        URL url = new URL(BASE_URL + path);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod(method);
        conn.setRequestProperty("Authorization", "Bearer " + API_KEY);

        if (jsonBody != null) {
            conn.setDoOutput(true);
            conn.setRequestProperty("Content-Type", "application/json");
            try (OutputStream os = conn.getOutputStream()) {
                os.write(jsonBody.getBytes("UTF-8"));
            }
        }

        return readResponse(conn);
    }

    private static String readResponse(HttpURLConnection conn) throws Exception {
        int responseCode = conn.getResponseCode();
        InputStream is = (responseCode < 400) ? conn.getInputStream() : conn.getErrorStream();
        try (Scanner scanner = new Scanner(is, "UTF-8").useDelimiter("\\A")) {
            return scanner.hasNext() ? scanner.next() : "";
        }
    }

    private static String parseField(String json, String regex) {
        Pattern pattern = Pattern.compile(regex);
        Matcher matcher = pattern.matcher(json);
        return matcher.find() ? matcher.group(1) : null;
    }
}

Download the result file by specifying the file_id in a GET request.

Request example

curl

# ======= Important =======
# API keys differ between Singapore and Beijing regions.
# The following is the base_url for the Singapore region. If you use a model in the Beijing region, replace the base_url with: https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-batch_output-xxx/content
# === Delete this comment before execution ===
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/files/file-batch_output-xxx/content \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" > result.jsonl

Response example

Single response example:

json

{
    "id": "c308ef7f-xxx",
    "custom_id": "1",
    "response": {
        "status_code": 200,
        "request_id": "c308ef7f-0824-9c46-96eb-73566f062426",
        "body": {
            "created": 1742303743,
            "usage": {
                "completion_tokens": 35,
                "prompt_tokens": 26,
                "total_tokens": 61
            },
            "model": "qwen-plus",
            "id": "chatcmpl-c308ef7f-0824-9c46-96eb-73566f062426",
            "choices": [\
                {\
                    "finish_reason": "stop",\
                    "index": 0,\
                    "message": {\
                        "content": "Hello! Of course. Whether you need information, learning materials, problem-solving methods, or any other help, I am here to support you. Please tell me what you need help with."\
                    }\
                }\
            ],
            "object": "chat.completion"
        }
    },
    "error": null
}

Response parameters


Field	Type	Description
id	String	The request ID.
custom_id	String	The user-defined request identifier.
response	Object	The request result.
status_code	Integer	HTTP status code. 200 indicates success.
request_id	String	Server-generated unique ID for this request.
completion_tokens	Integer	Number of tokens in the model-generated response.
prompt_tokens	Integer	Number of tokens in the input content (`prompt`) sent to the model.
total_tokens	Integer	Total number of tokens used by this request.
model	String	Name of the model used for this request.
error	Object	The error object. Returns `null` on success. On failure, contains the error code and detailed message.
error.code	String	Error line and reason information. See Error codes for troubleshooting.
error.message	String	Error message.

Advanced features

Set completion notifications

For long-running tasks, use asynchronous notifications instead of polling to reduce resource consumption.

Note

Completion notification is only supported in the Beijing region.

Callback: Specify a publicly accessible URL when creating the task.
EventBridge message queue: Deeply integrated with the Alibaba Cloud ecosystem. No public IP required.

Method 1: Callback

When creating a task, specify a publicly accessible URL via metadata. After the task completes, the system sends a POST request containing the task status to the specified URL:

OpenAI Python SDK

curl (HTTP)

python

import os
from openai import OpenAI

client = OpenAI(
    # If no environment variable is set, use api_key="sk-xxx" (not in production - risk of leaks).
    # API keys differ between regions.
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Beijing region's base_url. For Singapore, use: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1 and update the API key.
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

batch = client.batches.create(
    input_file_id="file-batch-xxx",  # The ID returned after uploading the file
    endpoint="/v1/chat/completions",  # For text embedding models, enter "/v1/embeddings". For the test model batch-test-model, enter /v1/chat/ds-test. For other models, enter /v1/chat/completions.
    completion_window="24h",
    metadata={
            "ds_batch_finish_callback": "https://xxx/xxx"
          }
)
print(batch)

Request example

curl

curl -X POST --location "https://dashscope.aliyuncs.com/compatible-mode/v1/batches" \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "input_file_id": "file-batch-xxxxx",
          "endpoint": "/v1/chat/completions",
          "completion_window": "24h",
          "metadata": {
            "ds_batch_finish_callback": "https://xxx/xxx"
          }
        }'

Method 2: EventBridge message queue

This method requires no public IP and is suitable for complex scenarios that need integration with services such as Function Compute or RocketMQ.

When a batch task completes, the system sends an event to Alibaba Cloud EventBridge. Configure EventBridge rules to listen for this event and route it to a specified target.

Event source (Source): acs.dashscope
Event type (Type): dashscope:System:BatchTaskFinish

Reference: Route events to Message Queue for RocketMQ.

Going live

File management
- Periodically delete unnecessary files using the OpenAI File delete API to avoid reaching storage limits (10,000 files or 100 GB).
- Store large files in OSS instead of uploading directly.
Task monitoring
- Use Callback or EventBridge asynchronous notifications.
- If polling is required, set the interval to more than 1 minute and use an exponential backoff strategy.
Error handling
- Implement handling for network errors, API errors, and other exceptions.
- Download and analyze error details from error_file_id.
- For common error codes, see Error codes.
Cost optimization
- Consolidate small tasks into a single batch.
- Set completion_window appropriately to allow greater scheduling flexibility.

Utility tools

CSV to JSONL

If your data is in a CSV file (first column: ID, second column: content), use this script to generate a JSONL batch input file.

To customize the file path or other parameters, modify the code as needed.

python

import csv
import json
def messages_builder_example(content):
    messages = [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": content}]
    return messages

with open("input_demo.csv", "r") as fin:
    with open("input_demo.jsonl", 'w', encoding='utf-8') as fout:
        csvreader = csv.reader(fin)
        for row in csvreader:
            body = {"model": "qwen-turbo", "messages": messages_builder_example(row[1])}
            # When calling a text embedding model, set the url value to "/v1/embeddings". For other models, set it to /v1/chat/completions.
            request = {"custom_id": row[0], "method": "POST", "url": "/v1/chat/completions", "body": body}
            fout.write(json.dumps(request, separators=(',', ':'), ensure_ascii=False) + "\n")

JSONL results to CSV

Use this script to convert result.jsonl into result.csv for analysis in Excel.

To customize the file path or other parameters, modify the code as needed.

python

import json
import csv
columns = ["custom_id",\
           "model",\
           "request_id",\
           "status_code",\
           "error_code",\
           "error_message",\
           "created",\
           "content",\
           "usage"]

def dict_get_string(dict_obj, path):
    obj = dict_obj
    try:
        for element in path:
            obj = obj[element]
        return obj
    except:
        return None

with open("result.jsonl", "r") as fin:
    with open("result.csv", 'w', encoding='utf-8') as fout:
        rows = [columns]
        for line in fin:
            request_result = json.loads(line)
            row = [dict_get_string(request_result, ["custom_id"]),\
                   dict_get_string(request_result, ["response", "body", "model"]),\
                   dict_get_string(request_result, ["response", "request_id"]),\
                   dict_get_string(request_result, ["response", "status_code"]),\
                   dict_get_string(request_result, ["error", "error_code"]),\
                   dict_get_string(request_result, ["error", "error_message"]),\
                   dict_get_string(request_result, ["response", "body", "created"]),\
                   dict_get_string(request_result, ["response", "body", "choices", 0, "message", "content"]),\
                   dict_get_string(request_result, ["response", "body", "usage"])]
            rows.append(row)
        writer = csv.writer(fout)
        writer.writerows(rows)

Fix garbled text in Excel

Use a text editor (such as Sublime Text) to convert the CSV file encoding to GBK, then open it in Excel.
Alternatively, create a new Excel file and specify UTF-8 encoding when importing the data.

Rate limits

API	Rate limit (per Alibaba Cloud account)


API	Rate limit (per Alibaba Cloud account)
Create task	1,000 calls/minute; up to 1,000 concurrent tasks
Query task	1,000 calls/minute
Query task list	100 calls/minute
Cancel task	1,000 calls/minute

Billing

Unit price: The input and output tokens for all successful requests are charged at 50% of the real-time inference price for the corresponding model. For more information, see Model list.
Billing scope:
- Only requests successfully executed within a task are billed.
- Requests that fail because of file parsing errors, task execution failures, or row-level errors do not incur charges.
- For canceled tasks, requests successfully completed before the cancellation are still billed as normal.

Note

Batch inference is a separate billing item. It supports AI General-purpose Savings Plan, but not discounts, such as subscription (other savings plans) or free quotas for new users. It also does not support features such as context cache.
Some models, such as qwen3.5-plus and qwen3.5-flash, have thinking mode enabled by default. This mode generates additional thinking tokens, which are billed at the output token price and increase costs. To control costs, set the `enable_thinking` parameter based on task complexity. For more information, see Deep thinking.

Error codes

If a request fails and returns an error message, see Error codes for a solution.

FAQ

How do I choose between Batch Chat and Batch File?

Use Batch File when you need to process a large file containing many requests asynchronously. Use Batch Chat when your business logic requires submitting many independent conversation requests synchronously with high concurrency.

How is the Batch File API billed? Do I need to purchase a separate package?

Batch uses pay-as-you-go billing based on tokens consumed by successful requests. No separate resource package is required.

Are submitted batch files executed in order?

No. The system uses dynamic scheduling based on compute load and does not guarantee execution order. Tasks may be delayed when resources are constrained.

How long does it take to complete a submitted batch file?

Execution time depends on system resources and task scale. If a task does not complete within the completion_window, it expires. Unprocessed requests in expired tasks are not executed and do not incur charges.

Scenario recommendations: Use real-time calls for scenarios requiring strict real-time model inference. Use batch calls for large-scale data processing scenarios that can tolerate delay.

Previous: OpenAI compatible - FileNext: OpenAI-compatible - Batch Chat

Is this page helpful?

Workflow

Prerequisites

Scope

Getting started

Step 1: Prepare the input file

Step 2: Run the code

Step 3: Verify test results

Run a formal task

Input file requirements

1. Modify the input file

2. Modify the Getting Started code

3. Run the code and wait for results

Detailed procedure

1. Upload file

2. Create a batch task

3. Query and manage batch tasks

4. Download Batch result file

Advanced features

Set completion notifications

Going live

Utility tools

Rate limits

Billing

Error codes

FAQ

Sales Support

Live-chat with our sales team or get in touch with a business development professional in your region.

Contact Sales

Technical Support

Open a ticket and get quick help from our technical team.

Open a Ticket >

We look forward to your suggestion.

Post a Suggestion > Report Abuse >

\ \ Hi, I'm Alibaba Cloud AI Assistant!\ \ I can help with questions and solutions.

Why Alibaba Cloud

About Alibaba Cloud

Asia Accelerator

Our Global Network

Global Offices

Trust Center

Case Studies

Analyst Reports

Products & Pricings

Pricing Calculator

ECS

SAS

Model Studio

Database

Security

SMS

Solutions

Financial Services

Retail Services

Media Services

Gaming Services

ISV Solutions

Engage

Developer Community

Partner Network

Startups

Marketplace

Join Alibaba Cloud

Resources & Support

Developer Learning Hub

Documentation Center

Training & Certification

Service Notices

Submit a Ticket

Security Report

Qwen Cloud

Careers About Us Privacy Policy Legal Integrity Compliance Reporting Channel Service Notices Links

Facebook
Linkedin
Twitter
YouTube
TikTok
contact.us@alibabacloud.com
Call Us Now
Discord

Careers About Us Privacy Policy Legal Integrity Compliance Reporting Channel Service Notices Links

OpenAI Batch API ​

Models ​

Models ​

GenAI Application ​

AI Service ​

AI Use Case ​

Overview ​

Why Alibaba Cloud ​

Customers and Insights ​

What's New ​

Products ​

Featured Products ​

Related Programs ​

Solutions ​

Pricing ​

Overview & Tools ​

Optimize your cost ​

Resources ​

Technical Resources ​

Training&Certification ​

Developer Hub ​

Partners ​

Marketplace ​

Find a Partner ​

Become a Partner ​

Support ​

Support & Professional Services ​

Contact us ​

Language ​

Locale ​

Workflow ​

Prerequisites ​

Scope ​

Getting started ​

Step 1: Prepare the input file ​

Step 2: Run the code ​

Step 3: Verify test results ​

Run a formal task ​

Input file requirements ​

1. Modify the input file ​

2. Modify the Getting Started code ​

3. Run the code and wait for results ​

Detailed procedure ​

1. Upload file ​

Request example ​

Request example ​

Request example ​

Request example ​

Response example ​

2. Create a batch task ​

Request example ​

Request example ​

Request example ​

Request example ​

Input parameters ​

Response example ​

Response parameters ​

3. Query and manage batch tasks ​

Query specific task status ​

Request example ​

Request example ​

Request example ​

Request example ​

Response example ​

Query task list ​

Request example ​

Request example ​

Request example ​

Request example ​

Input parameters ​

Response example ​

Response parameters ​

Cancel batch task ​

Request example ​

Request example ​

Request example ​

Request example ​

Response example ​

4. Download Batch result file ​

Request example ​

OpenAI Batch API

Models

Models

GenAI Application

AI Service

AI Use Case

Overview

Why Alibaba Cloud

Customers and Insights

What's New

Products

Featured Products

Related Programs

Solutions

Pricing

Overview & Tools

Optimize your cost

Resources

Technical Resources

Training&Certification

Developer Hub

Partners

Marketplace

Find a Partner

Become a Partner

Support

Support & Professional Services

Contact us

Language

Locale

Workflow

Prerequisites

Scope

Getting started

Step 1: Prepare the input file

Step 2: Run the code

Step 3: Verify test results

Run a formal task

Input file requirements

1. Modify the input file

2. Modify the Getting Started code

3. Run the code and wait for results

Detailed procedure

1. Upload file

Request example

Request example

Request example

Request example

Response example

2. Create a batch task

Request example

Request example

Request example

Request example

Input parameters

Response example

Response parameters

3. Query and manage batch tasks

Query specific task status

Request example

Request example

Request example

Request example

Response example

Query task list

Request example

Request example

Request example

Request example

Input parameters

Response example

Response parameters

Cancel batch task

Request example

Request example

Request example

Request example

Response example

4. Download Batch result file

Request example