Skip to main content
Qwen Cloud home page
Docs
File

File

File management API

Upload files for document analysis or batch processing using the OpenAI-compatible Files API.

Usage

Use the OpenAI SDK (Python/Node.js) or HTTP to upload, query, list, and delete files. Prerequisites:

Model availability

File IDs work with:

Endpoints

EndpointDescription
Upload fileUpload a file for document analysis or batch processing
Retrieve fileRetrieve file details by ID
List filesList all files in your account
Delete fileDelete a file by ID

Getting started

Upload a file

You can store up to 10,000 files and 100 GB total. Files never expire.

For document analysis

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

Request examples

  • Python
  • Node.js
  • cURL
import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  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
}

For batch processing

Set purpose to batch. Upload a JSONL file conforming to Batch file requirements. Maximum file size: 500 MB.
For batch calls, see OpenAI compatible - Batch.

Request examples

  • Python
  • Node.js
  • cURL
import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  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())

Sample response

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

Billing

File operations (upload, storage, query, delete) are free. You are charged only for model inference tokens (input + output).

Rate limits

Rate limits: upload (3 QPS), query/list/delete (10 QPS combined).

Going live

  • Periodic cleanup: Delete unused files to stay under the 10,000-file limit.
  • Status verification: Confirm status="processed" before using uploaded files.
  • Rate limit awareness: Upload (3 QPS), query/list/delete (10 QPS). Implement retry with exponential backoff.
  • Error handling: Handle network timeouts, API errors (invalid format, size exceeded), and file limit errors. See Error codes.

FAQ

1. What if file status stays "processing" after upload?

Processing typically completes in seconds. If it persists:
  • Verify the file format is supported.
  • Verify the file size is within limits (file-extract: 150 MB, batch: 500 MB).
  • Poll status with the retrieve API.

2. Can file IDs be shared across accounts?

No. File IDs are scoped to the Qwen Cloud account that created them.

3. Are uploaded files stored permanently?

Yes. Files persist until you delete them.

4. Why did file upload fail?

  • Invalid or missing API key ($DASHSCOPE_API_KEY not set).
  • Unsupported file format.
  • File size exceeds limit (file-extract: 150 MB, batch: 500 MB).
  • Storage limit reached (10,000 files or 100 GB total).
  • Rate limit exceeded (3 QPS for upload).

5. When should I use file-extract vs batch?

  • file-extract: Document analysis and data extraction.
  • batch: Batch inference tasks (requires JSONL format).