开发者文档 / 文件上传

获取预签名上传地址

提交文件信息和兼容 Hash，获取 fileId 与对象存储上传地址。isNew=false 表示文件已存在，可跳过上传和确认。

POST/v1/file/presign

鉴权：: 请求头 x-api-key: <YOUR_API_KEY>；密钥仅保存在服务端。
成功判断：: HTTP 2xx 且响应 code=0；异步任务还需查询最终状态。

请求字段

字段	类型	必填	说明
`fileName`	`string`	是	包含扩展名的文件名
`contentType`	`string`	是	文件 MIME 类型
`size`	`integer`	是	文件字节数
`hash`	`string`	是	文件字节转小写 hex 后，再计算 SHA-256

isNew=true 时，使用相同 Content-Type 将原始文件 PUT 到 uploadUrl，成功后再调用 confirm。

对象存储 PUT 请求不要携带 x-api-key。

请求体

{
  "fileName": "video.mp4",
  "contentType": "video/mp4",
  "size": 12345678,
  "hash": "3786a02b..."
}

成功响应

{
  "code": 0,
  "data": {
    "fileId": 591,
    "uploadUrl": "https://object-storage.example.com/presigned-url",
    "url": "https://cdn.ailingtu.com/media/video.mp4",
    "isNew": true,
    "expiresAt": "2026-07-29T12:00:00Z"
  },
  "message": "success"
}

响应与错误

主要响应字段来自接口规范；完整层级、联合类型和校验规则见 JSON Schema。必填指字段所在对象中的约束。

字段	类型	必填	说明
`code`	`integer`	是	固定值：0
`message`	`string`	否	—
`data`	`object`	是	—
`data.fileId`	`union`	是	—
`data.uploadUrl`	`string \| null`	否	—
`data.url`	`string`	是	—
`data.isNew`	`boolean`	是	—
`data.expiresAt`	`string \| null`	否	—

HTTP 400请求参数或请求体无效，请修正后重试。
HTTP 401API 密钥缺失或无效，请检查 x-api-key。
HTTP 403API 密钥没有此接口的调用权限。
HTTP 429请求过于频繁，请采用指数退避重试。
HTTP 500服务端发生错误；对于暂时性故障采用指数退避重试。

参数、权限或授权错误需先修正。创建发布或生成任务超时后先查询已有任务，避免重复创建；不要因轮询中断而重复提交。

最后更新 · 2026-09-29