Upload file - 上传文件

更新时间：2026-06-24 20:12:57

功能说明

OpenAI 兼容 Files API，用于上传文件。当前支持 purpose=batch 用于批量任务输入文件。当前仅支持阿里云 qwen 系列模型。

前提条件

当 purpose=batch 时，您需要准备一个 JSONL 格式（.jsonl）的 Batch 输入文件。文件中每一行为一个独立的 JSON 对象，表示一次批量请求。准备要求如下：

每行必须是一个合法的 JSON 对象，行与行之间用换行符分隔。
建议一个 JSONL 文件中只使用同一个 model，以避免因模型不同导致批量任务处理异常。

每行 JSON 对象包含以下字段：

字段	说明
custom_id	自定义请求 ID，用于在批量结果中匹配对应的请求与响应。同一文件内不可重复。
method	请求方法，当前仅支持 `POST`。
url	请求路径，例如 `/v1/chat/completions`。
body	请求体，包含 `model`、`messages` 等参数，格式与对应的 Chat Completion 接口请求体一致。

以下为一个 test_model.jsonl 文件的示例：

{"custom_id":"1","method":"POST","url":"/v1/chat/completions","body":{"model":"batch-test-model","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"你好！有什么可以帮助你的吗？"}]}}
{"custom_id":"2","method":"POST","url":"/v1/chat/completions","body":{"model":"batch-test-model","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is 2+2?"}]}}

调用说明

接口约束

调用者需要拥有 API Key，详情请参见管理 AI API Key。
此 API 为通用 Files API，支持多种用途的文件上传。

请求路径

POST {BASE_URL}/api/v1/files

请求头

名称	是否必选	示例值	描述
Authorization	是	Bearer {token}	鉴权信息
Content-Type	否	multipart/form-data	请求体格式

请求参数

Path 参数

无

Query 参数

无

Body 参数

名称	类型	是否必填	示例值	描述
file	string	是	-	文件内容
purpose	string	是	batch	文件用途，当前支持 `batch`（批量任务输入文件）

返回结果

返回参数

名称	类型	描述
success	boolean	请求是否成功
code	string	返回码
message	string	返回信息
data	object	业务返回数据

data 字段说明

名称	类型	描述
id	string	文件唯一 ID
object	string	对象类型，例如 `file`
bytes	integer	文件大小（字节）
created_at	integer	文件创建时间戳
filename	string	文件名
purpose	string	文件用途

请求示例

curl --request POST '{BASE_URL}/api/v1/files' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=@"/path/to/test_model.jsonl"' \
  --form 'purpose="batch"'

返回示例

{
  "success": true,
  "code": "200",
  "message": "successful",
  "data": {
    "id": "file-123456",
    "object": "file",
    "bytes": 1024,
    "created_at": 1712736000,
    "filename": "your_file.jsonl",
    "purpose": "batch"
  }
}