upload_group_image

上传图片并取得可用于发送消息的 image 消息段。上传完成不会自动发送消息。支持当前框架内的在线 Android 与 Linux QQ 账号。

适用协议

Android（手机 / 平板）/ Linux QQ。

调用方式

先将示例文件放入框架的允许目录，再向已认证 WebSocket 发送：

{
  "type": "action",
  "id": "upload_group_image-1",
  "action": "upload_group_image",
  "params": {
    "self_id": 123456789,
    "protocol_id": 0,
    "group_id": 987654321,
    "file_path": "data/media-downloads/example.png"
  }
}

收到 ok: true 后，把响应的 data 原样放入 send_group_msg 的 message 数组，并使用相同 self_id、protocol_id 和目标：

// uploadResult 为上面上传请求对应的 action_result。
if (uploadResult.ok) {
  ws.send(JSON.stringify({
    type: "action",
    id: "send-media-1",
    action: "send_group_msg",
    params: {
      self_id: 123456789,
      protocol_id: 0,
      group_id: 987654321,
      message: [uploadResult.data]
    }
  }))
}

参数

参数	类型	必填	说明
self_id	integer	是	当前框架内的在线 QQ 账号。
protocol_id	integer	是	账号协议 ID，须显式提供；0 是有效 ID。
group_id	integer	是	目标群号。
file_path	string	是	本地允许目录中的文件、HTTP(S) URL、file:// 路径，或本插件服务已经完成的 transfer:// 引用。

文件来源

本地相对路径以框架工作目录为基准，不是插件进程目录。允许读取的目录是 data/media-downloads、data/plugin-downloads 和 data/stream-temp；文件必须已经存在，不能读取其他框架数据或系统文件。

外部插件不方便写入这些目录时，可先用 file_transfer 上传，完成后将返回的 file（transfer:// 引用）作为 file_path。此引用只能由创建它的同一插件服务使用。

使用可解析的真实图片文件，建议 JPEG、PNG 或 GIF。此接口没有独立 base64 参数，需要先把 Base64 解码并通过 file_transfer 上传。

返回值

成功响应的 data 本身就是消息段：

字段	类型	说明
type	string	固定为 image
data.file_id	string	本次上传取得的媒体引用，不是 file_transfer 的 token

错误通过外层 ok: false 和 error 返回。媒体引用绑定当前账号、协议和目标会话；不能跨账号、跨协议或跨目标复用，也不能将群媒体用于好友消息。账号重连或缓存失效后应重新上传。