Skip to main content
POST
/
api
/
upload
/
presign
上传图片
curl --request POST \
  --url https://api.example.com/api/upload/presign \
  --header 'Content-Type: application/json' \
  --data '
{
  "file_name": "<string>",
  "content_type": "<string>",
  "expires_in": 123,
  "prefix": "<string>"
}
'
{
  "success": true,
  "message": "",
  "data": {
    "method": "PUT",
    "upload_url": "https://storage.example.com/uploads/user/12/20260519-abcdef.png?signature=...",
    "object_key": "uploads/user/12/20260519-abcdef.png",
    "public_url": "https://cdn.example.com/uploads/user/12/20260519-abcdef.png",
    "expires_in": 900,
    "content_type": "image/png"
  }
}

Documentation Index

Fetch the complete documentation index at: https://mercury-eab3b728.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
上传图片

这个接口不直接接收文件内容，而是先签发一个对象存储 PUT 地址。客户端拿到地址后再自行上传文件。
  • 适合图片、视频首帧和其他媒体素材的预上传。
  • 使用 API Key 认证，但返回结构是 /api/* 的 success/message/data 包装。
  • 默认过期时间为 900 秒，最短 60 秒，最长 3600 秒。
  • 未显式传 prefix 时，会按当前用户自动生成 uploads/user/{id} 前缀。

​
方法与路径

POST /api/upload/presign

​
请求示例

curl -X POST https://www.geeknow.top/api/upload/presign \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "input.png",
    "content_type": "image/png",
    "expires_in": 900
  }'

​
响应示例

{
  "success": true,
  "message": "",
  "data": {
    "method": "PUT",
    "upload_url": "https://storage.example.com/uploads/user/12/20260519-abcdef.png?signature=...",
    "object_key": "uploads/user/12/20260519-abcdef.png",
    "public_url": "https://cdn.example.com/uploads/user/12/20260519-abcdef.png",
    "expires_in": 900,
    "content_type": "image/png"
  }
}

​
认证

Authorization: Bearer YOUR_API_KEY

​
Body

​
file_name
string
原始文件名。服务端会根据扩展名生成对象键。未传时也可以正常工作，但通常建议显式传入。
​
content_type
string
文件 MIME 类型，例如 image/png、image/jpeg、video/mp4。
​
expires_in
integer
预签名 URL 有效期，单位秒。服务端会自动限制在 60 到 3600 之间。
​
prefix
string
对象键前缀。未传时默认使用 uploads/user/{id}。

​
Response

​
success
boolean
是否成功。/api/* 接口优先用这个字段表示业务结果。
​
data.method
string
上传方法，当前固定为 PUT。
​
data.upload_url
string
带签名的对象存储上传地址。
​
data.public_url
string
上传成功后可直接传给图像、视频和任务接口的公网 URL。

​
使用场景

​
上传后再做图生视频

  1. 调用 /api/upload/presign 取得 upload_url 与 public_url。
  2. 对 upload_url 发起 PUT 上传文件。
  3. 在 /v1/video/generations 或 /v1/videos 请求体中把 public_url 传给 image。

​
注意事项

这个接口只负责签发上传地址，不会替你上传文件本身。真正的文件上传需要客户端对 upload_url 再发一次 PUT 请求。

​
相关接口