上传文件-阿里云帮助中心

请求头

头部	必选	说明
`Authorization`	是	`Bearer`
`Content-Type`	是	`multipart/form-data`

请求体（multipart/form-data）

字段	类型	必选	说明
`file`	file	是	要上传的文件二进制内容
`purpose`	string	否	文件用途，值为 `user_upload`。不传时默认为 `user_upload`
`metadata`	JSON string	否	自定义元数据，JSON 对象格式

示例请求

curl -X POST "https://api.qoder.com.cn/api/v1/cloud/files" \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./my-document.txt" \
  -F "purpose=user_upload" \
  -F 'metadata={"project":"demo"}'

示例响应

HTTP 201 Created

{
  "created_at": "2026-05-18T15:33:44Z",
  "file_id": "file_019e3bb8c1387743bf4ef115aae5acb1",
  "filename": "my-document.txt",
  "metadata": {
    "project": "demo"
  },
  "mime_type": "text/plain",
  "purpose": "user_upload",
  "size_bytes": 110,
  "status": "ready",
  "updated_at": "2026-05-18T15:33:44Z"
}

响应字段

字段	类型	说明
`file_id`	string	文件唯一标识，前缀 `file_`
`filename`	string	原始文件名
`size_bytes`	integer	文件大小（字节）
`mime_type`	string	MIME 类型，服务端自动检测
`purpose`	string	文件用途
`status`	string	文件状态，上传成功后为 `ready`
`metadata`	object	自定义元数据
`created_at`	string	创建时间（ISO 8601）
`updated_at`	string	更新时间（ISO 8601）

错误码

HTTP	type	触发条件
400	`invalid_request_error`	缺少 `file` 字段或 `purpose` 值无效
401	`authentication_error`	缺少或无效的认证令牌

错误响应示例：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Field 'file' is required."
  }
}

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Field 'purpose' must be one of: user_upload."
  }
}

完整错误信封说明详见错误参考。