生成上传预签名

POST/v2/storage/buckets/{bucket}/objects/presign

签发一次性直传 URL，浏览器可跳过业务后端直接上传。

预签名 URL 默认 15 分钟有效，且限定了 HTTP 方法与 Content-Length 上限。超过 max_size 的上传会被对象存储以 403 拒绝。

Bearer Token storage:write api.demo.acme-cloud.dev

请求参数

共 1 项

bucket 必填路径

string

桶名称

请求体

application/json

key 必填

string

对象键（路径）

method 可选

string · 默认 PUT

预签名允许的方法

可选值PUTPOST

content_type 可选

string · 默认 image/png

上传时须匹配的 Content-Type

max_size 可选

integer · 默认 10485760

允许的最大字节数

expires_in 可选

integer · 默认 900

有效期（秒），上限 3600

响应

3 种状态

200 OK

响应示例

{
  "url": "https://acme-assets.ap-east-1.acme-cloud.dev/uploads/2026/avatar.png?X-Amz-Signature=9f2c...",
  "method": "PUT",
  "headers": {
    "Content-Type": "image/png"
  },
  "expires_at": "2026-10-16T07:45:00Z"
}

代码示例

cURL

curl -i -X POST 'https://api.demo.acme-cloud.dev/v2/storage/buckets/acme-assets/objects/presign' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "uploads/2026/avatar.png",
  "method": "PUT",
  "content_type": "image/png",
  "max_size": 10485760,
  "expires_in": 900
}'

注意事项

前端拿到 URL 后需原样带上 headers 中返回的头部，否则签名校验失败。