Media 接口
预留上传位、上传文件、查询和删除媒体资源。
媒体需要先创建占位，再上传二进制，最后在 Posts 中绑定。单个文件上限
10 MB，允许的 mime_type：image/png、image/jpeg、video/mp4、
video/quicktime。
接口列表
- GET
/api/v1/media— 列出工作区媒体。 - GET
/api/v1/media/{id}— 获取单个媒体。 - DELETE
/api/v1/media/{id}— 删除并解除绑定。 - POST
/api/v1/media/create-upload-url— 预留 ID，返回上传地址。 - PUT
/api/v1/media/upload/{id}— 将二进制上传到预留 ID。
GET /api/v1/media
查询参数：offset（默认 0）、limit（默认 10，最大 100）、post_id（数组，OR
逻辑）、type（数组枚举 image | video）。
响应：
{
"data": [
{
"id": "uuid",
"mime_type": "image/jpeg",
"type": "image",
"post_id": "post-uuid | null",
"status": "pending | uploaded",
"object": {
"isDeleted": false,
"url": "https://.../file.jpg" | null,
"size_bytes": 12345,
"name": "file.jpg"
}
}
],
"meta": { "offset": 0, "limit": 10, "total": 1 }
}示例：
curl "https://<host>/api/v1/media?offset=0&limit=10&type=image" \
-H "Authorization: Bearer YOUR_SECRET_TOKEN"GET /api/v1/media/{id}
路径参数：id（必填）。返回与列表项相同的结构；不存在时 404。
DELETE /api/v1/media/{id}
路径参数：id（必填）。删除成功返回 { "success": true }。
POST /api/v1/media/create-upload-url
Body（JSON，必填）：
mime_type:image/png|image/jpeg|video/mp4|video/quicktimename: 原始文件名size_bytes: 整数 > 0 且 ≤ 10_485_760
响应：
{ "media_id": "uuid", "upload_url": "https://<host>/api/v1/media/upload/<id>", "name": "file.jpg" }PUT /api/v1/media/upload/{id}
- 路径参数：预留的
id。 - 头：
Content-Type必须与预留时一致。 - Body：文件二进制。
响应：
{ "success": true, "media_id": "uuid", "url": "https://..." }若 Body 为空，将得到 { "error": "Request body is empty" } 与状态码 400。
推荐上传流程
// 1) 预留上传位
const reserve = await fetch('https://<host>/api/v1/media/create-upload-url', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: 'Bearer YOUR_SECRET_TOKEN',
},
body: JSON.stringify({
name: 'photo.jpg',
mime_type: 'image/jpeg',
size_bytes: file.size,
}),
}).then((res) => res.json());
// 2) 上传二进制
await fetch(reserve.upload_url, {
method: 'PUT',
headers: { 'Content-Type': 'image/jpeg', Authorization: 'Bearer YOUR_SECRET_TOKEN' },
body: file,
});
// 3) 在 Posts API 中引用 reserve.media_id备注
- 状态流转：
pending（已预留）→uploaded（已存储）。 - 删除媒体会同时解除与帖子资产的关联。
- 如果已有外部 URL，可在 Posts 接口使用
media_urls，无需上传文件。