接口文档

通用鉴权

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

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

获取上传 URL

POST /api/v1/uploads/presign

返回一个可直接 PUT 到腾讯云 COS 的预签名 URL。服务端会自动把文件放到当前 API key 所属项目的固定目录下。

请求体

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

filename 用于提取扩展名；key 可选，只能是项目目录内的相对文件路径，不需要包含 project slug。未传 key 时路径规则为 project-slug/yyyy/mm/10位随机字符.扩展名。

响应示例

{
  "url": "https://bucket.cos.region.myqcloud.com/project-slug/2026/07/k7x4p9m2qa.txt?...",
  "method": "PUT",
  "key": "project-slug/2026/07/k7x4p9m2qa.txt",
  "publicUrl": "https://oss.example.com/project-slug/2026/07/k7x4p9m2qa.txt",
  "headers": {
    "Content-Type": "text/plain"
  },
  "bucket": "bucket-1234567890",
  "region": "ap-chengdu",
  "expireSeconds": 180,
  "expiresAt": 1783524243,
  "contentType": "text/plain",
  "maxSize": 104857600
}

上传文件

curl -X PUT "$url" \
  -H "Content-Type: text/plain" \
  --data-binary @demo.txt

PUT 到 COS 时必须带响应里的 headers，尤其是 Content-Type，否则签名可能不匹配。

删除文件

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