上传图片

调用 /api/upload/presign 生成预签名上传地址，再把返回的 public_url 传给图像或视频接口。

POST /api/upload/presign

上传图片

cURL

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

200 - 预签名地址已创建

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

上传图片

这个接口不直接接收文件内容，而是先签发一个对象存储 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
  }'

响应示例

200 - 预签名地址已创建

{
  "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 请求。

相关接口

• 统一视频生成接口
• 图像系列概览