Skip to main content
阿里云百炼 home page阿里云百炼
工具包/框架

OpenAI文件接口兼容

文件上传接口用于上传文件，以便在 Qwen-Long 和 Qwen-Doc-Turbo 模型中进行文档问答与数据提取，或将其用作批量推理任务的输入文件。

使用方式

支持通过OpenAI SDK（Python、Java）或HTTP API调用文件接口，包括上传、查询、删除等操作。

前提条件

支持的模型

文件ID可用于以下场景：
  • Qwen-Long：通过文件ID进行长文档问答
  • Qwen-Doc-Turbo：通过文件ID进行文件内数据提取与问答
  • 批量推理：通过文件ID上传批量任务输入文件

快速开始

上传文件

百炼存储空间支持的最大文件数为10000个，总大小不超过100 GB，暂时没有有效期限制。当文件数量或总大小达到任一上限时，新的文件上传请求将会失败。请删除不再需要的文件以释放配额，然后才能继续上传。
  • 用于文档分析
  • 用于Batch调用
  • 用于创建调优任务
将purpose指定为file-extract，文件格式支持文本文件（ TXT、DOCX、PDF、XLSX、EPUB、MOBI、MD、CSV、JSON），图片文件（BMP、PNG、JPG/JPEG、GIF和PDF扫描件），单个文件最大为 150 MB。
关于通过file_id进行文档分析，请参考长上下文（Qwen-Long）。

请求示例 

import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

# test.txt 是一个本地示例文件
file_object = client.files.create(file=Path("test.txt"), purpose="file-extract")

print(file_object.model_dump_json())

响应示例 

{
    "id": "file-fe-xxx",
    "bytes": 2055,
    "created_at": 1729065448,
    "filename": "test.txt",
    "object": "file",
    "purpose": "file-extract",
    "status": "processed",
    "status_details": null
}

查询文件信息

通过在retrieve或GET方法中指定file_id来查询文件信息。
  • OpenAI Python SDK
  • OpenAI Java SDK
  • HTTP

请求示例 

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

返回示例 

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

查询文件列表

返回所有文件的信息，包括通过上传文件接口上传的文件以及batch任务的结果文件。
此接口支持更多筛选参数，详情请参见参数说明。
  • OpenAI Python SDK
  • OpenAI Java SDK
  • HTTP

请求示例 

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

返回示例 

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

删除文件

通过删除文件接口删除指定file_id的文件。可以通过查询文件列表接口查询文件信息。
  • OpenAI Python SDK
  • OpenAI Java SDK
  • HTTP

请求示例 

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

返回示例 

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

计费说明

文件上传、存储和查询操作不产生费用。仅在调用模型API时，根据实际使用的输入Token和输出Token进行计费。

限流

上传文件接口的QPS（每秒请求数）限制为3。查询文件信息、查询文件列表、删除文件接口的QPS总和限制为10。

应用于生产环境

  • 定期清理：定期删除不再使用的文件，避免达到10000个文件上限。
  • 状态检查：上传后检查文件状态，确保status为processed后再使用。
  • 限流检查：上传文件接口的QPS（每秒请求数）限制为3。查询文件信息、查询文件列表、删除文件接口的QPS总和限制为10。
  • 错误处理：实现完整的异常处理机制，包括网络错误、API错误等。

常见问题

1. 文件上传后状态一直是"processing"怎么办？

文件处理需要一定时间，通常几秒内完成。如果长时间处于"processing"状态：
  • 检查文件格式是否支持
  • 检查文件大小是否超过限制
  • 使用retrieve接口定期查询状态

2. 文件ID可以跨账号使用吗？

不可以。文件ID仅在生成它的阿里云主账号内有效，不支持跨账号共享。

3. 上传的文件会被永久保存吗？

是的，上传的文件会被永久保存在您的阿里云账号下，除非主动删除。建议定期清理不需要的文件。

4. 文件上传失败，可能的原因有哪些？

  • API Key无效或未配置
  • 文件格式不支持
  • 文件大小超过限制（file-extract: 150MB，batch: 500MB）
  • 已达到文件数量上限（10000个）或总大小上限（100GB）
  • 上传文件接口的QPS（每秒请求数）限制为3。

5. purpose参数应该如何选择？

  • file-extract：用于文档分析场景，配合Qwen-Long或Qwen-Doc-Turbo使用
  • batch：用于批量推理任务，文件必须是符合格式要求的JSONL文件

参数说明

接口类别参数名类型必选说明示例值
文档上传fileFile是用于指定待上传的文件。Path("test.txt")
purposeString是用于指定上传文件的用途。每种用途所需的文件格式、大小及内容规范，请参考对应功能文档中的详细要求。当前可选值如下：file-extract: 用于Qwen-Long与Qwen-Doc模型的文档理解与数据提取；batch: 用于OpenAI兼容-Batch（文件输入）任务；"file-extract"
文件查询file_idString是待查询的文件id。"file-fe-xxx"
afterString否查询文件列表任务中用于分页的游标。参数after的取值为当前分页的最后一个file_id，表示查询该ID之后下一页的数据。例如，若本次查询返回了20条数据，且最后一个file_id是file-batch-xxx，则后续查询时可以设置after="file-batch-xxx"，以获取列表的下一页。"file-fe-xxx"
create_beforeString否查询文件列表任务中，一个字符串格式的时间戳。用于筛选并返回创建时间早于该指定时间点的file_id。"20250306123000", "2025-11-12 10:10:10", "2025-11-12", "20251112"
create_afterString否查询文件列表任务中，一个字符串格式的时间戳。用于筛选并返回创建时间晚于该指定时间点的file_id。"20250306123000", "2025-11-12 10:10:10", "2025-11-12", "20251112"
purposeString否查询文件列表任务中根据文件的用途进行筛选，仅返回与指定 purpose（file-extract或batch）相匹配的file_id。"batch"
limitInteger否查询文件列表任务中每次查询返回的文件数量，取值范围[1,2000]，默认2000。2000
文件删除file_idString是待删除文件id。"file-fe-xxx"
响应参数
通用响应参数idString\文件的标识符删除文件任务中表示成功删除的文件的id。"file-fe-xxx"
bytesInteger文件大小，单位为字节。81067
created_atInteger文件创建时的 Unix 时间戳（秒）。1617981067
filenameString上传的文件名。"text.txt"
objectString对象类型查询文件列表任务中始终为"list"。其余类型任务中始终为"file"。"file"
purposeString文件的用途，取值有batch、file-extract、batch_output。"file-extract"
statusString文件的当前状态。可能的状态有：uploaded（已上传，等待解析）, processing（解析中，需等待解析完成后再引用）, processed（解析完成，可正常引用调用）, error（解析失败）。"processed"
查询文件列表has_moreBoolean是否还有下一页数据。false
dataArray返回的文件列表，列表中每个元素格式与通用相应参数一致。
[{
 "id": "xxx",
 "bytes": 27,
 "created_at": 1722480543,
 "filename": "test.txt",
 "object": "file",
 "purpose": "batch",
 "status": "processed",
 "status_details": null
 }]
删除文件deletedBoolean是否删除成功，true表示删除成功。true

错误码

如果模型调用失败并返回报错信息，请参见错误码进行解决。
阿里云百炼 home page阿里云百炼
使用 API
文本生成
图像生成
视频生成
3D模型生成
音频
实时多模态
Realtime API
  • 概述
向量与排序
更多模型
工具包/框架
模型生产
文件管理
更多