接口文档

通用鉴权

业务服务调用 API 时必须传项目对应的 API key。每个 API key 只能操作所属项目目录，目录固定为 project-slug/。

Header:
X-API-Key: oss_live_xxx
Content-Type: application/json

获取上传 URL

POST /api/v1/uploads/presign

返回一个可直接 POST 到腾讯云 COS 的表单上传凭证。服务端会自动把文件放到当前 API key 所属项目的固定目录下，并在 COS policy 中限制文件大小。

请求体

{
  "filename": "demo.txt",
  "contentType": "text/plain",
  "key": "custom-name.txt",
  "expireSeconds": 180
}

filename 用于提取扩展名；key 可选，只能是项目目录内的相对文件路径，不需要包含 project slug。文件大小上限固定使用项目设置。

响应示例

{
  "url": "https://bucket.cos.region.myqcloud.com",
  "method": "POST",
  "key": "project-slug/2026/07/k7x4p9m2qa.txt",
  "publicUrl": "https://oss.example.com/project-slug/2026/07/k7x4p9m2qa.txt",
  "fields": {
    "key": "project-slug/2026/07/k7x4p9m2qa.txt",
    "Content-Type": "text/plain",
    "success_action_status": "200",
    "policy": "base64-policy",
    "q-sign-algorithm": "sha1",
    "q-ak": "AKID...",
    "q-sign-time": "1783524063;1783524243",
    "q-key-time": "1783524063;1783524243",
    "q-signature": "..."
  },
  "bucket": "bucket-1234567890",
  "region": "ap-chengdu",
  "expireSeconds": 180,
  "expiresAt": 1783524243,
  "contentType": "text/plain",
  "maxSize": 104857600
}

上传文件

curl -X POST "$url" \
  --form-string "key=$fields_key" \
  --form-string "Content-Type=text/plain" \
  --form-string "success_action_status=200" \
  --form-string "policy=$policy" \
  --form-string "q-sign-algorithm=sha1" \
  --form-string "q-ak=$q_ak" \
  --form-string "q-sign-time=$q_sign_time" \
  --form-string "q-key-time=$q_key_time" \
  --form-string "q-signature=$q_signature" \
  -F "file=@demo.txt;type=text/plain"

表单字段必须在 file 之前追加；超过 maxSize 的文件会被 COS policy 拒绝。

删除文件

POST /api/v1/files/delete

删除腾讯云 COS 中的单个对象。只能删除当前 API key 所属项目目录下的 key。

请求体

{
  "key": "project-slug/2026/07/k7x4p9m2qa.txt"
}

响应示例

{
  "deleted": true,
  "key": "project-slug/2026/07/k7x4p9m2qa.txt"
}

错误说明

401 invalid api key
403 key is not in this project directory
400 invalid key