DocsICP FilingConsole
Documentation
Home Page Alibaba Cloud Model Studio Model API Toolkit/Framework OpenAI compatible - File

OpenAI compatible file interface

Updated at:
Copy as MD
Product
My Favorites

Upload files for document Q&A and data extraction with Qwen-Long and Qwen-Doc-Turbo , or prepare input files for batch tasks.

Usage

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

Prerequisites

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 by file ID.
  • 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 before you can continue uploading.

For document analysis

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://dashscope.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())

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.files.*;

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()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .baseUrl("https://dashscope.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 -X POST https://dashscope.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

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://dashscope.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())

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.files.*;

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()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .baseUrl("https://dashscope.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 -X POST https://dashscope.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
}

For fine-tuning

Set purpose to fine-tune. The input must be a JSONL file conforming to the Input file size and format requirements. Maximum fine-tuning dataset/training set file size: 300 MB.

For more about fine-tuning models through the API, see Model fine-tuning.

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://dashscope.aliyuncs.com/compatible-mode/v1",
)

# file.jsonl is a local sample file.
file_object = client.files.create(file=Path("file.jsonl"), purpose="fine-tune")

print(file_object.model_dump_json())

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.files.*;

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()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .baseUrl("https://dashscope.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/file.jsonl");
        // Create file upload parameters.
        FileCreateParams params = FileCreateParams.builder()
                .file(filePath)
                .purpose(FilePurpose.of("fine-tune"))
                .build();

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

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

Query file information

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

OpenAI Python SDK

Request examples 

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.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()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .baseUrl("https://dashscope.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

Endpoints to configure 

GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files/{file_id}

Request examples 

curl -X GET https://dashscope.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.

NoteAdditional filtering parameters are available. Parameter description.

OpenAI Python SDK

Request examples 

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.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()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .baseUrl("https://dashscope.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

Endpoints to configure 

GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files

Request examples 

curl -X GET https://dashscope.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

Request examples 

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.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;

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

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

HTTP

Endpoints to configure 

DELETE https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files/{file_id}

Request examples 

curl -X  DELETE https://dashscope.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: Check the file status after upload. A status of processed means the upload is complete and the file can be referenced, but it does not mean parsing is complete. Before parsing completes, calls may return File parsing in progress; retry later.
  • 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 primary account that created them and cannot be shared across accounts.

3. Are uploaded files stored permanently?

Yes. Files are stored permanently under your Alibaba Cloud account unless 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.

6. Why does Qwen-Long still report that the file is being parsed after the status becomes "processed"?

A status of processed only means the file upload is complete and the file can be referenced. It does not mean parsing is complete. If Qwen-Long returns File parsing in progress, please try again later., retry later after the file has been parsed.

Parameter description

Interface CategoryParameterTypeRequiredDescriptionExample value

File upload

file

File

Yes

The file to upload.

Path("test.txt")

purpose

String

Yes

The intended use of the file. For the file format, size, and content requirements of each purpose, see the corresponding feature documentation. 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 processing), processing (being processed), processed (upload complete and ready to reference; this does not mean parsing is complete), or error (processing failed).

"processed"

Query file list

has_more

Boolean

Indicates whether there is a next page of data.

false

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.

Previous：OpenAI-compatible - VisionNext：OpenAI-compatible - Batch (file input)