OpenAI compatible file interface

Usage

Call the File API through the OpenAI SDK (Python or Java) or HTTP. Supported operations: upload, query, and delete.

Prerequisites

An Alibaba Cloud Model Studio API key: Create an API key and Export the API key as environment variable.
To use the OpenAI SDK, install the OpenAI SDK.

Alibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing), Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:

China (Beijing): from https://dashscope.aliyuncs.com to https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapore: from https://dashscope-intl.aliyuncs.com to https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} is your workspace ID, which can be found on the Workspace Details page in the Alibaba Cloud Model Studio console. The existing domain remains fully functional.

Supported models

File IDs apply to the following scenarios:

Qwen-Long: Answer questions about a long document by specifying its file ID
Qwen-Doc-Turbo: Extract data and perform Q&A on files.
Batch processing: Upload batch files.

Getting started

Upload a file

Model Studio allows up to 10,000 files totaling 100 GB. Files do not expire. Uploads fail when either limit is reached. Delete unused files to free quota.

For document analysis
For batch processing

Set purpose to file-extract. Supported formats: text (TXT, DOCX, PDF, XLSX, EPUB, MOBI, MD, CSV, JSON) and image (BMP, PNG, JPG/JPEG, GIF, scanned PDF). Maximum file size: 150 MB.

Document analysis with a file_id: long context (Qwen-Long).

Request examples

import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    # If you have not configured an environment variable, replace the following line with api_key="sk-xxx" and use your Model Studio API key.
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

# test.txt is a local sample file.
file_object = client.files.create(file=Path("test.txt"), purpose="file-extract")

print(file_object.model_dump_json())

Sample response

{
    "id": "file-fe-xxx",
    "bytes": 2055,
    "created_at": 1729065448,
    "filename": "test.txt",
    "object": "file",
    "purpose": "file-extract",
    "status": "processed",
    "status_details": null
}

Set purpose to batch. The input must be a JSONL file conforming to the Input file size and format requirements. Maximum file size: 500 MB.

Batch call details: OpenAI compatible - Batch.

Request examples

import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    # If you have not configured an environment variable, replace the following line with api_key="sk-xxx" and use your Model Studio API key.
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

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

print(file_object.model_dump_json())

Sample response

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

Query file information

Retrieve file details by file_id.

OpenAI Python SDK
OpenAI Java SDK
HTTP

Request examples

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

file = client.files.retrieve(file_id="file-batch-xxx")

print(file.model_dump_json())

Sample response

{
  "id": "file-batch-xxx",
  "bytes": 27,
  "created_at": 1722480306,
  "filename": "test.txt",
  "object": "file",
  "purpose": "batch",
  "status": "processed",
  "status_details": null
}

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.FileObject;
import com.openai.models.FileRetrieveParams;

public class Main {
    public static void main(String[] args) {
        // Create a client and use the API key from the environment variable.
        OpenAIClient client = OpenAIOkHttpClient.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .baseUrl("https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1")
                .build();
        // Create file query parameters. Replace the fileId as needed.
        FileRetrieveParams params= FileRetrieveParams.builder()
                .fileId("file-batch-xxx")
                .build();
        //Query the file.
        FileObject fileObject = client.files().retrieve(params);
        System.out.println(fileObject);
    }
}

Endpoints to configure

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/files/{file_id}

Request examples

curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"

Sample response

{
    "id": "file-batch-xxx",
    "object": "file",
    "bytes": 499719,
    "created_at": 1715935833,
    "filename": "test.txt",
    "purpose": "batch",
    "status": "processed"
}

Query a list of files

Returns all your files, including uploaded files and batch result files.

Additional filtering parameters are available. Parameter description.

OpenAI Python SDK
OpenAI Java SDK
HTTP

Request examples

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

file_stk = client.files.list(after="file-batch-xxx",limit=20)
print(file_stk.model_dump_json())

Sample response

{
  "data": [
    {
      "id": "file-batch-xxx",
      "bytes": 27,
      "created_at": 1722480543,
      "filename": "test.txt",
      "object": "file",
      "purpose": "batch",
      "status": "processed",
      "status_details": null
    },
    {
      "id": "file-batch-yyy",
      "bytes": 431986,
      "created_at": 1718089390,
      "filename": "test.pdf",
      "object": "file",
      "purpose": "batch",
      "status": "processed",
      "status_details": null
    }
  ],
  "object": "list",
  "has_more": false
}

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.FileListPage;
import com.openai.models.FileListParams;

public class Main {
    public static void main(String[] args) {
        // Create a client and use the API key from the environment variable.
        OpenAIClient client = OpenAIOkHttpClient.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .baseUrl("https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1")
                .build();
        // Create file list query parameters.
        FileListParams params = FileListParams.builder()
                .after("file-batch-xxx")
                .limit(20)
                .build();
        //Query the file list.
        FileListPage file_stk = client.files().list(params);
        System.out.println(file_stk);
    }
}

Required Endpoints

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/files

Request examples

curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/files \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"

Sample response

{
    "object": "list",
    "has_more": true,
    "data": [
        {
            "id": "file-batch-xxx",
            "object": "file",
            "bytes": 84889,
            "created_at": 1715569225,
            "filename": "example.txt",
            "purpose": "batch",
            "status": "processed"
        },
        {
            "id": "file-batch-yyy",
            "object": "file",
            "bytes": 722355,
            "created_at": 1715413868,
            "filename": "Agent_survey.pdf",
            "purpose": "batch",
            "status": "processed"
        }
    ]
}

Delete a file

Deletes a file by file_id. To find file IDs, use the Query a list of files API.

OpenAI Python SDK
OpenAI Java SDK
HTTP

Request examples

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

file_object = client.files.delete("file-batch-xxx")
print(file_object.model_dump_json())

Sample response

{
  "object": "file",
  "deleted": true,
  "id": "file-batch-xxx"
}

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.FileDeleteParams;
import com.openai.models.FileListPage;
import com.openai.models.FileListParams;

public class Main {
    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .baseUrl("https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1")
                .build();
        FileDeleteParams params = FileDeleteParams.builder()
                .fileId("file-batch-xxx")
                .build();

        System.out.println(client.files().delete(params));
    }
}

Endpoints to configure

DELETE https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/files/{file_id}

Request examples

curl -X  DELETE https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"

Sample response

{
  "object": "file",
  "deleted": true,
  "id": "file-batch-oLIon7bzfxELqJBTS5okwC4E"
}

Billing

File upload, storage, and query operations are free. You are billed only for input and output tokens consumed by model calls.

Rate limiting

File upload: 3 QPS. File query, list, and delete combined: 10 QPS.

Production checklist

Periodic cleanup: Delete unused files regularly to stay within the 10,000-file limit.
Status check: Verify the status is processed before using a file.
Rate limit check: Upload: 3 QPS. Query, list, and delete combined: 10 QPS.
Error handling: Implement exception handling for network and API errors.

FAQ

1. What do I do if the file status remains "processing" after upload?

Files are usually processed within seconds. If the status stays at "processing":

Check whether the file format is supported.
Check whether the file size exceeds the limit.
Use the retrieve API to periodically query the status.

2. Can file IDs be used across different accounts?

No. File IDs are scoped to the Alibaba Cloud account that created them.

3. Are uploaded files stored permanently?

Yes. Files persist until you delete them. Clean up unused files periodically.

4. Why did my file upload fail?

The API key is invalid or missing.
The file format is not supported.
The file size exceeds the limit (file-extract: 150 MB, batch: 500 MB).
The maximum number of files (10,000) or the total size limit (100 GB) has been reached.
The file upload API has a QPS (Requests Per Second) limit of 3.

5. Which purpose value should I use?

file-extract: Document analysis with Qwen-Long or Qwen-Doc-Turbo.
batch: Batch processing. File must be JSONL and meet format requirements.

Parameter description

Interface Category	Parameter	Type	Required	Description	Example value
File upload	file	File	Yes	The file to upload.	Path("test.txt")
File upload	purpose	String	Yes	The intended use of the file. Format and size requirements vary by purpose. Valid values:`file-extract`: For document understanding and data extraction with the Qwen-Long and Qwen-Doc models.`batch`: For OpenAI compatible - Batch jobs.	"file-extract"
File query	file_id	String	Yes	The ID of the file to query.	"file-fe-xxx"
	after	String	No	Pagination cursor for the Query a list of files API.Set `after` to the `file_id` of the last item on the current page to fetch the next page.Example: if the last `file_id` is `file-batch-xxx`, set `after="file-batch-xxx"` to retrieve the next page.	"file-fe-xxx"
	create_before	String	No	Timestamp filter for the Query a list of files API. Returns files created before the specified time.	`"20250306123000"`, `"2025-11-12 10:10:10"`, `"2025-11-12"`, `"20251112"`
	create_after	String	No	Timestamp filter for the Query a list of files API. Returns files created after the specified time.	`"20250306123000"`, `"2025-11-12 10:10:10"`, `"2025-11-12"`, `"20251112"`
	purpose	String	No	Purpose filter for the Query a list of files API. Returns files matching the specified purpose (`file-extract` or `batch`).	"batch"
	limit	Integer	No	Number of files per page in the Query a list of files API. Range: 1-2,000. Default: 2,000.	2000
File deletion	file_id	String	Yes	The ID of the file to delete.	"file-fe-xxx"
Response parameters
Common response parameters	id	String	\	The ID of the file.In a Delete a file task, this is the ID of the successfully deleted file.	"file-fe-xxx"
	bytes	Integer		The size of the file in bytes.	81067
	created_at	Integer		The UNIX timestamp in seconds when the file was created.	1617981067
	filename	String		The name of the uploaded file.	"text.txt"
	object	String		The object type.For a Query a list of files task, the value is always "list".In other tasks, this is always "file".	"file"
	purpose	String		The purpose of the file. Valid values are `batch`, `file-extract`, `batch_output`.	"file-extract"
	status	String		The current status of the file: `uploaded` (uploaded, awaiting parsing), `processing` (being parsed; wait until parsing completes before referencing it), `processed` (parsing complete, ready to reference), or `error` (parsing failed).	"processed"
Query file list	has_more	Boolean		Indicates whether there is a next page of data.	false
Query file list	data	Array		The returned list of files. The format of each element in the list is consistent with the common response parameters.	`[{ "id": "xxx", "bytes": 27, "created_at": 1722480543, "filename": "test.txt", "object": "file", "purpose": "batch", "status": "processed", "status_details": null }]`
Delete file	deleted	Boolean		Indicates whether the deletion was successful. A value of true indicates success.	true

Error codes

If the model call fails and returns an error message, see Error codes for resolution.

​Usage

​Prerequisites

​Supported models

​Getting started

​Upload a file

Request examples

Sample response

​Query file information

Request examples

Sample response

​Query a list of files

Request examples

Sample response

​Delete a file

Request examples

Sample response

​Billing

​Rate limiting

​Production checklist

​FAQ

​1. What do I do if the file status remains "processing" after upload?

​2. Can file IDs be used across different accounts?

​3. Are uploaded files stored permanently?

​4. Why did my file upload fail?

​5. Which purpose value should I use?

​Parameter description

​Error codes

Usage

Prerequisites

Supported models

Getting started

Upload a file

Query file information

Query a list of files

Delete a file

Billing

Rate limiting

Production checklist

FAQ

1. What do I do if the file status remains "processing" after upload?

2. Can file IDs be used across different accounts?

3. Are uploaded files stored permanently?

4. Why did my file upload fail?

5. Which purpose value should I use?

Parameter description

Error codes