流程

上传参考素材分三步：

1. POST /api/v1/upload/presign 申请上传凭证。
2. 用返回的 put_url 直传文件到 R2。
3. POST /api/v1/upload/{media_id}/complete 确认上传完成。

申请上传

POST /api/v1/upload/presign

Headers: X-API-Key: h3k_...

Body:

{
  "kind": "image",
  "filename": "ref.png",
  "content_type": "image/png",
  "size_bytes": 204800,
  "width": 1024,
  "height": 768
}

• kind：image / video / audio
• 图片支持 png/jpg/jpeg/webp，视频支持 mp4/webm/mov，音频支持 mp3/wav/flac/ogg/m4a
• size_bytes 必须和实际文件大小一致，上传完会校验

响应：

{
  "media_id": "uuid",
  "object_key": "refs/uuid.png",
  "put_url": "https://r2.example.com/..."
}

直传文件

用 put_url 发 PUT 请求，body 是文件内容。put_url 有效期约 600 秒，超时重新 presign。

确认完成

POST /api/v1/upload/{media_id}/complete

Headers: X-API-Key: h3k_...

确认后媒体状态变成 active，之后就能在 ref_media_ids 里引用。

如果浏览器直传因为 CORS 或网络问题失败，可以改用 POST /api/v1/upload/{media_id}/put 让塔台代传，再调 complete。