OpenAI file interface - Alibaba Cloud Model Studio - Alibaba Cloud Documentation Center

The file upload interface is used to upload files for document Q&A and data extraction with the Qwen-Long and Qwen-Doc-Turbo models. You can also use it to upload input files for batch tasks.

Usage

You can call the file interface using the OpenAI SDK in Python or Java, or by making HTTP API calls. Supported operations include uploading, querying, and deleting files.

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.

Model availability

You can use file IDs in the following scenarios:

Qwen-Long: Perform Q&A on long documents.
Qwen-Doc-Turbo: Extract data and perform Q&A on files.
Batch processing: Upload batch files.

Getting started

Upload a file

The Model Studio storage space supports a maximum of 10,000 files with a total size of up to 100 GB. The files do not expire.

For document analysis

Set `purpose` to file-extract. Supported file formats include text files (such as TXT, DOCX, PDF, XLSX, EPUB, MOBI, MD, CSV, and JSON) and image files (such as BMP, PNG, JPG/JPEG, GIF, and scanned PDFs). The maximum size for a single file is 150 MB.

For more information about document analysis using a file_id, see long context (Qwen-Long).

Request examples

Python

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 keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.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())

Java

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.FileCreateParams;
import com.openai.models.FileObject;
import com.openai.models.FilePurpose;

import java.nio.file.Path;
import java.nio.file.Paths;

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()
                // API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1
                .baseUrl("https://dashscope-intl.aliyuncs.com/compatible-mode/v1")
                .build();
        // Set the file path. Modify the path and filename as needed.
        Path filePath = Paths.get("src/main/java/org/example/test.txt");
        // Create file upload parameters.
        FileCreateParams params = FileCreateParams.builder()
                .file(filePath)
                .purpose(FilePurpose.of("file-extract"))
                .build();

        // Upload the file.
        FileObject fileObject = client.files().create(params);
        System.out.println(fileObject);
    }
}

curl

# ======= Important =======
# API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1/files
# === Delete this comment before running ===

curl -X POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
--form 'file=@"test.txt"' \
--form 'purpose="file-extract"'

Sample response

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

For batch processing

If you set `purpose` to batch, the input file must be a JSONL file and conform to the Batch file requirements. The maximum size for a single file for a batch task is 500 MB.

For more information about batch calls, see OpenAI compatible - Batch.

Request examples

Python

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 keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.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())

Java

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.FileCreateParams;
import com.openai.models.FileObject;
import com.openai.models.FilePurpose;

import java.nio.file.Path;
import java.nio.file.Paths;

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()
                // API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1
                .baseUrl("https://dashscope-intl.aliyuncs.com/compatible-mode/v1")
                .build();
        // Set the file path. Modify the path and filename as needed.
        Path filePath = Paths.get("src/main/java/org/example/test.txt");
        // Create file upload parameters.
        FileCreateParams params = FileCreateParams.builder()
                .file(filePath)
                .purpose(FilePurpose.of("batch"))
                .build();

        // Upload the file.
        FileObject fileObject = client.files().create(params);
        System.out.println(fileObject);
    }
}

curl

# ======= Important =======
# API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1/files
# === Delete this comment before running ===

curl -X POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
--form 'file=@"test.jsonl"' \
--form 'purpose="batch"'

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

Query file information by specifying the file_id in the retrieve or GET method.

OpenAI Python SDK

Request examples

import os
from openai import OpenAI

client = OpenAI(
    # API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.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
}

OpenAI Java SDK

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()
                // API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1
                .baseUrl("https://dashscope-intl.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);
    }
}

HTTP

Endpoint

Singapore region: GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files/{file_id}
China (Beijing) region: GET https://dashscope.aliyuncs.com/compatible-mode/v1/files/{file_id}

Request examples

# ======= Important =======
# API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx
# === Delete this comment before running ===
curl -X GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"

If you use a model in the China (Beijing) region, you must use an API KEY from the China (Beijing) region and replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx

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 information about all your files, including files uploaded through the upload interface and result files from batches.

Note

This operation supports more filtering parameters. For more information, see Parameter description.

OpenAI Python SDK

Request examples

import os
from openai import OpenAI

client = OpenAI(
    # API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
     # The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.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
}

OpenAI Java SDK

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()
                // API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1
                .baseUrl("https://dashscope-intl.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);
    }
}

HTTP

Endpoint

Singapore region: GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files
China (Beijing) region: GET https://dashscope.aliyuncs.com/compatible-mode/v1/files

Request examples

# ======= Important =======
# API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1/files
# === Delete this comment before running ===
curl -X GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"

If you use a model in the China (Beijing) region, you must use an API KEY from the China (Beijing) region and replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1/files

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 with a specified file_id. You can query file information using the Query a list of files API.

OpenAI Python SDK

Request examples

import os
from openai import OpenAI

client = OpenAI(
    # API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.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"
}

OpenAI Java SDK

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()
                // API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1
                .baseUrl("https://dashscope-intl.aliyuncs.com/compatible-mode/v1")
                .build();
        FileDeleteParams params = FileDeleteParams.builder()
                .fileId("file-batch-xxx")
                .build();

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

HTTP

Endpoint

Singapore region: DELETE https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files/{file_id}
China (Beijing) region: https://dashscope.aliyuncs.com/compatible-mode/v1/files/{file_id}

Request examples

# ======= Important =======
# API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx
# === Delete this comment before running ===
curl -X  DELETE https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"

If you use a model from the China (Beijing) region, you must use an API KEY from the China (Beijing) region and replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx

Sample response

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

Billing

File upload, storage, and query operations are free of charge. You are charged only for the input and output tokens that are used when you call a model.

Rate limiting

The queries per second (QPS) limit for the file upload interface is 3. The total QPS limit for the query file information, query file list, and delete file interfaces is 10.

Going live

Periodic cleanup: Periodically delete unused files to avoid reaching the 10,000-file limit.
Status check: After you upload a file, check its status. Ensure that the status is processed before you use the file.
Rate limit check: The QPS limit for the file upload interface is 3. The total QPS limit for the query file information, query file list, and delete file interfaces is 10.
Error handling: Implement a comprehensive exception handling mechanism for network errors, API errors, and other issues.

FAQ

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

File processing takes time, but it is usually completed within a few seconds. If the status remains "processing" for an extended period:

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, they cannot. A file ID is valid only within the Alibaba Cloud account that generated it and cannot be shared across accounts.

3. Are uploaded files stored permanently?

Yes, they are. Uploaded files are permanently stored in your Alibaba Cloud account unless you delete them. Periodically clean up unnecessary files.

4. What are the possible reasons for a file upload failure?

The API key is invalid or has not been exported.
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 QPS limit for the file upload interface has been exceeded. The limit is 3 QPS.

5. Should I choose file-extract or batch for the purpose parameter?

file-extract: Use this for document analysis scenarios with Qwen-Long or Qwen-Doc-Turbo.
batch: Use this for batch tasks. The file must be a JSONL file that meets the format requirements.

Parameter description

Category	Parameter	Type	Required	Description	Example
File upload	file	File	Yes	The file to upload.	Path("test.txt")
File upload	purpose	String	Yes	Specifies the purpose of the uploaded file. Valid values: `file-extract`: For document understanding with the qwen-long model. `batch`: For OpenAI compatible - Batch jobs. The file must be in the format specified in Batch file.	"file-extract"
File query	file_id	String	Yes	The ID of the file to query.	"file-fe-xxx"
	after	String	No	The cursor used for pagination in the Query a list of files task. The value of the `after` parameter is the `file_id` of the last item on the current page. This retrieves the next page of data. For example, if a query returns 20 records and the last `file_id` is `file-batch-xxx`, set `after="file-batch-xxx"` in the next query to retrieve the next page of the list.	"file-fe-xxx"
	create_before	String	No	In a Query a list of files task, a timestamp in string format. Used to filter and return file IDs created before the specified time.	`"20250306123000"`, `"2025-11-12 10:10:10"`, `"2025-11-12"`, `"20251112"`
	create_after	String	No	In a Query a list of files task, a timestamp in string format. Used to filter and return file IDs created after the specified time.	`"20250306123000"`, `"2025-11-12 10:10:10"`, `"2025-11-12"`, `"20251112"`
	purpose	String	No	In a Query a list of files task, filters files by purpose. Returns only file IDs that match the specified purpose (`file-extract` or `batch`).	"batch"
	limit	Integer	No	The number of files returned for each query in the Query a list of files task, with a value range of 1 to 2,000 and a default value of 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. The valid values are `batch`, `file-extract`, and `batch_output`.	"file-extract"
	status	String		The current status of the file.	"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 a call fails, see Error messages for troubleshooting.