upload_group_voice

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

适用协议

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

调用方式

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

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

收到 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:// 引用。
base64	string	二选一	完整音频的 Base64，与 file_path 不能同时提供。支持纯 Base64、base64:// 前缀和 Base64 data URL。

文件来源

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

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

音频支持 MP3、WAV 和可解析的 SILK V3；MP3/WAV 会转换为语音所需的 SILK，并生成时长与波形。文件扩展名不能代替真实格式，不支持的音频会返回错误。file_path 也可使用 base64:// 或 Base64 data URL，此时不要再传 base64。

返回值

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

字段	类型	说明
type	string	固定为 voice
data.file_id	string	本次上传取得的媒体引用，不是 file_transfer 的 token
data.duration	integer	语音时长，单位秒

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