媒体 API

上传内容

POST /_matrix/media/v3/upload

上传媒体内容。返回 content_uri 用于消息中引用。

curl -X POST http://localhost:8899/_matrix/media/v3/upload \
  -H "Authorization: Bearer syt_xxx" \
  -H "Content-Type: image/png" \
  --data-binary @image.png

响应：

{
  "content_uri": "mxc://localhost/abc123",
  "content_type": "image/png",
  "content_length": 12345,
  "media_id": "abc123"
}

带文件名上传

POST /_matrix/media/v3/upload?filename=document.pdf

下载内容

GET /_matrix/media/v3/download/{mediaId}
GET /_matrix/media/v3/download/{mediaId}/{fileName}

返回原始媒体内容及适当的 Content-Type。

创建缩略图

GET /_matrix/media/v3/thumbnail/{mediaId}?width=64&height=64&method=crop

参数	说明
`width`	期望宽度（像素）
`height`	期望高度（像素）
`method`	`crop`（填充并裁剪）或 `scale`（适应边界）

缩略图缓存在磁盘上，文件名格式为 thumb_{mediaId}_{w}x{h}_{method}.jpg。

URL 预览

POST /_matrix/media/v3/preview_url

{
  "url": "https://example.com/article",
  "ts": 1625000000000
}

响应：

{
  "og:title": "文章标题",
  "og:description": "文章描述...",
  "og:image": "mxc://localhost/thumb123",
  "og:image:width": 1200,
  "og:image:height": 630,
  "og:url": "https://example.com/article"
}

SSRF 防护

URL 预览会验证目标 URL 不是内部/私有地址：

阻止 localhost、127.x.x.x、10.x.x.x、192.168.x.x、172.16-31.x.x
阻止 IPv6 回环地址
违规时返回 M_FORBIDDEN，HTTP 400

预览缓存

URL 预览结果缓存在 media_url_preview 表中，TTL 为 3600 秒。

媒体元数据

上传的媒体元数据存储在 media_metadata 表中：

列	类型	说明
`media_id`	VARCHAR	唯一标识符
`content_type`	VARCHAR	MIME 类型
`content_length`	BIGINT	文件大小（字节）
`file_name`	VARCHAR	原始文件名
`upload_name`	VARCHAR	上传名称

远程媒体

当联邦服务器发送媒体引用时，Firmiana 会下载并在本地缓存内容。连接失败返回 HTTP 502（Bad Gateway）。

#媒体 API

#上传内容

#带文件名上传

#下载内容

#创建缩略图

#URL 预览

#SSRF 防护

#预览缓存

#媒体元数据

#远程媒体