agent-skills/autonomous-ai-agents/hermes-agent/references/qqbot-media-api.md

QQ Bot Rich Media API Reference

Source: https://bot.q.qq.com/wiki/develop/api-v2/server-inter/message/send-receive/rich-media.html

Endpoints

Scope	Endpoint	Method
单聊	/v2/users/{openid}/files	POST
群聊	/v2/groups/{group_openid}/files	POST

Parameters

Field	Type	Required	Description
file_type	int	Yes	1=图片, 2=视频, 3=语音, 4=文件
url	string	Yes*	媒体资源 URL（*url 或 file_data 二选一）
file_data	string	No	base64 二进制数据
srv_send_msg	bool	Yes	true=直接发送（占用主动消息频次），false=仅上传获取 file_info
file_name	string	No	文件名（file_type=4 时建议传）

Supported Formats

• 图片: png/jpg
• 视频: mp4
• 语音: silk/wav/mp3/flac
• 文件: 无限制（群场景暂不开放 file_type=4）

Response

{
  "file_uuid": "...",
  "file_info": "...",   // 用于发送消息接口的 media 字段
  "ttl": 3600           // 剩余秒数，0=长期有效
}

Sending with file_info

{
  "msg_type": 7,
  "media": {"file_info": "<file_info_from_upload>"},
  "msg_seq": 1
}

Notes

• file_info 不受目标端影响，可复用到多个群/用户
• 用 /v2/users/{openid}/files 上传的仅能发单聊，群上传的仅能发群聊
• 建议 srv_send_msg=false，先获取 file_info 再发送
• 文件大小限制：~100MB（分块上传），~10MB（inline base64）

Hermes Adapter Implementation

• Gateway adapter: gateway/platforms/qqbot/adapter.py → _send_media() (line ~2690)
• Chunked upload: gateway/platforms/qqbot/chunked_upload.py
• Media types defined in gateway/platforms/qqbot/constants.py (MEDIA_TYPE_IMAGE=1, VIDEO=2, VOICE=3, FILE=4)
• send_message tool gap: _send_qqbot() in tools/send_message_tool.py:1677 is text-only