62 lines
1.9 KiB
Markdown
62 lines
1.9 KiB
Markdown
# 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
|
||
|
||
```json
|
||
{
|
||
"file_uuid": "...",
|
||
"file_info": "...", // 用于发送消息接口的 media 字段
|
||
"ttl": 3600 // 剩余秒数，0=长期有效
|
||
}
|
||
```
|
||
|
||
## Sending with file_info
|
||
|
||
```json
|
||
{
|
||
"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
|