如何通过Matrix/Synapse客户端服务器API发送本地图片？

步骤1：上传图片到媒体服务器 #

Matrix发送图片需要先将本地文件上传到家庭服务器的媒体存储，获取mxc://格式的资源URI，才能在消息中引用。执行以下curl命令完成上传：

curl --header "Authorization: Bearer my_token" \
     -X POST \
     -F "file=@/path/to/your/image.jpg;type=image/jpeg" \
     "https://my_homeserver_url/_matrix/media/r0/upload"

• 替换/path/to/your/image.jpg为本地图片的实际路径
• type=image/jpeg需匹配图片的MIME类型，例如PNG图片对应image/png

执行后会返回包含资源URI的响应，示例如下：

{
  "content_uri": "mxc://your-homeserver-domain/abc123XYZ"
}

记录下这个content_uri，用于下一步发送消息。

步骤2：发送图片消息到目标房间 #

使用上一步获取的mxc://URI，构造m.image类型的消息请求：

curl --header "Authorization: Bearer my_token" \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{
           "msgtype": "m.image",
           "body": "图片描述文本",
           "info": {
             "mimetype": "image/jpeg",
             "size": 12345,
             "h": 1080,
             "w": 1920
           },
           "url": "mxc://your-homeserver-domain/abc123XYZ"
         }' \
     "https://my_homeserver_url/_matrix/client/r0/rooms/my_room_id/send/m.room.message"

• body为图片的 fallback 描述文本，客户端会显示该文本
• info字段为可选，其中size是图片文件的字节数，h和w为图片的高宽像素值，添加这些字段能让客户端更好地处理图片
• url字段填写第一步获取的content_uri

关键说明 #

Matrix不支持直接在消息中引用本地文件路径（服务器无法访问你的本地文件系统），必须通过「上传媒体文件→获取资源URI→发送引用URI的图片消息」两步流程完成。

内容的提问来源于stack exchange，提问作者Stephan Michard