# 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