Skip to main content
Alibaba Cloud Model Studio home pageAlibaba Cloud Model Studio
Toolkit/Framework

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

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
  • For batch processing
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 

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

Sample response 

{
    "id": "file-fe-xxx",
    "bytes": 2055,
    "created_at": 1729065448,
    "filename": "test.txt",
    "object": "file",
    "purpose": "file-extract",
    "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
  • OpenAI Java SDK
  • HTTP

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
}

Query a list of files

This operation returns all file information, including uploaded files and batch result files.
This operation supports more filtering parameters. For more information, see Parameter description.
  • OpenAI Python SDK
  • OpenAI Java SDK
  • HTTP

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
}

Delete a file

Delete a file by file_id. Use Query a list of files API to find file IDs.
  • OpenAI Python SDK
  • OpenAI Java SDK
  • HTTP

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

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

CategoryParameterTypeRequiredDescriptionExample
File uploadfileFileYesThe file to upload.Path("test.txt")
purposeStringYesSpecifies 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 queryfile_idStringYesThe ID of the file to query."file-fe-xxx"
afterStringNoThe 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_beforeStringNoTimestamp (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_afterStringNoTimestamp (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"
purposeStringNoFor Query a list of files: filters by purpose (file-extract or batch)."batch"
limitIntegerNoNumber of files per query in Query a list of files. Range: 1-2,000. Default: 2,000.2000
File deletionfile_idStringYesThe ID of the file to delete."file-fe-xxx"
Response parameters
Common response parametersidString\The ID of the file.For Delete a file: the deleted file ID."file-fe-xxx"
bytesIntegerThe size of the file in bytes.81067
created_atIntegerThe UNIX timestamp in seconds when the file was created.1617981067
filenameStringThe name of the uploaded file."text.txt"
objectStringThe object type. Always "list" for Query a list of files, "file" for other operations."file"
purposeStringThe purpose of the file. The valid values are batch, file-extract, and batch_output."file-extract"
statusStringThe current status of the file."processed"
Query file listhas_moreBooleanIndicates whether there is a next page of data.false
dataArrayList of files. Each element follows common response parameter format.
[{
 "id": "xxx",
 "bytes": 27,
 "created_at": 1722480543,
 "filename": "test.txt",
 "object": "file",
 "purpose": "batch",
 "status": "processed",
 "status_details": null
 }]
Delete filedeletedBooleanIndicates deletion success. Returns true if successful.true

Error codes

If the model call fails and returns an error message, see Error codes for resolution.
Alibaba Cloud Model Studio home pageAlibaba Cloud Model Studio
API Usage
Text Generation
Image Generation
  • FAQ
Video Generation
Audio
Real-time Multimodal
Realtime API
Text Embedding
More Models
Toolkit/Framework
Model Production
File Management
More
OpenAI compatible file interface - Alibaba Cloud Model Studio