DocsICP FilingConsole
官方文档
首页

OpenAI compatible file interface

更新时间：
复制 MD 格式
产品详情
我的收藏

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

Important

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

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())
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://{WorkspaceId}.cn-beijing.maas.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://{WorkspaceId}.cn-beijing.maas.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://{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())
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://{WorkspaceId}.cn-beijing.maas.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://{WorkspaceId}.cn-beijing.maas.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

Retrieve file details by file_id.

OpenAI Python SDK

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
}

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://{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);
    }
}

HTTP

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.

Note

Additional 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://{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
}

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://{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);
    }
}

HTTP

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

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"
}

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()
                .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));
    }
}

HTTP

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

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, which can be either uploaded, processed, or error.

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