Alibaba AI Docs

Appearance

OpenAI compatible file interface ​

Upload files for document Q&A and data extraction with Qwen-Long and Qwen-Doc-Turbo. This interface also supports uploading input files for batch tasks.

Usage ​

Call the file interface using the OpenAI SDK (Python or Java) or HTTP API. The interface supports file upload, query, and deletion.

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 ​

Storage limits are 10,000 files maximum and 100 GB total. Files do not expire.

For document analysis ​

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

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

Request examples ​

Python

HELPCODEESCAPE-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",
)


file_object = client.files.create(file=Path("test.txt"), purpose="file-extract")

print(file_object.model_dump_json())

Java

HELPCODEESCAPE-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

HELPCODEESCAPE-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 ​

HELPCODEESCAPE-json
{
    "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 ​

Set `purpose` to batch. The input file must be in JSONL format and conform to Batch file requirements. The maximum file size is 500 MB.

For more information about batch calls, see OpenAI compatible - Batch (file input).

Request examples ​

Python

HELPCODEESCAPE-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

HELPCODEESCAPE-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

HELPCODEESCAPE-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 ​

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

Query file information ​

Specify the file_id in the retrieve or GET method to query file information.

OpenAI Python SDK ​

Request examples ​

HELPCODEESCAPE-python
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 ​

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

OpenAI Java SDK ​

HELPCODEESCAPE-java
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 ​

HELPCODEESCAPE-http
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 ​

HELPCODEESCAPE-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/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 ​

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

Query a list of files ​

This operation returns all file information, including uploaded files and batch result files. Note

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

OpenAI Python SDK ​

Request examples ​

HELPCODEESCAPE-python
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 ​

HELPCODEESCAPE-json
{
  "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 ​

HELPCODEESCAPE-java
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 ​

HELPCODEESCAPE-http
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 ​

HELPCODEESCAPE-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 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 ​

HELPCODEESCAPE-json
{
    "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 ​

Delete a file by file_id. Use Query a list of files API to find file IDs.

OpenAI Python SDK ​

Request examples ​

HELPCODEESCAPE-python
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 ​

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

OpenAI Java SDK ​

HELPCODEESCAPE-java
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 ​

HELPCODEESCAPE-http
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 ​

HELPCODEESCAPE-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/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 ​

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

Billing ​

File upload, storage, and query are free. Charges apply only to input and output tokens when calling models.

Rate limiting ​

The QPS limit for file upload is 3. The total QPS limit for query, list, and delete operations is 10.

Going live ​

  • Periodic cleanup: Delete unused files regularly to stay within the 10,000-file limit.

  • Status check : Verify status is processed before using uploaded files.

  • Rate limit check: Ensure compliance with QPS limits (upload: 3 QPS, query/list/delete: 10 QPS total).

  • Error handling: Implement exception handling for network errors, API errors, and other failures.

FAQ ​

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

File processing usually completes within 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. File IDs are valid only within the Alibaba Cloud account that created them and cannot be shared across accounts.

3. Are uploaded files stored permanently? ​

Yes. Files are permanently stored in your account unless deleted. Clean up unnecessary files periodically.

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")     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 (file input) jobs. The file must be in the format specified in OpenAI compatible - Batch (file input).   "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. Set `after` to the last \`file_id\` on the current page to retrieve the next page. Example: if the last \`file_id\` is \`file-batch-xxx\`, set `after="file-batch-xxx"` in the next query.   "file-fe-xxx"     create_before   *String*   No   Timestamp (string format) for Query a list of files. Returns file IDs created **before** the specified time.   `"20250306123000"`, `"2025-11-12 10:10:10"`, `"2025-11-12"`, `"20251112"`     create_after   *String*   No   Timestamp (string format) for Query a list of files. Returns file IDs created **after** the specified time.   `"20250306123000"`, `"2025-11-12 10:10:10"`, `"2025-11-12"`, `"20251112"`     purpose   *String*   No   For Query a list of files: filters by purpose (`file-extract` or `batch`).   "batch"     limit   *Integer*   No   Number of files per query in Query a list of files. 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. For Delete a file: the deleted file ID.   "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. Always "list" for Query a list of files, "file" for other operations.   "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     data   *Array*   List of files. Each element follows common response parameter format.
json
\[{
 "id": "xxx",
 "bytes": 27,
 "created_at": 1722480543,
 "filename": "test.txt",
 "object": "file",
 "purpose": "batch",
 "status": "processed",
 "status_details": null
 }\]
Delete file   deleted   *Boolean*   Indicates deletion success. Returns \`true\` if successful.   true

Error codes ​

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

Mirror of Alibaba Cloud Model Studio docs for reference and RAG. Not affiliated with Alibaba Cloud.

Source: alibabacloud.com/help/en/model-studio