Aiogram 3.x 不支持 answer_media_group() 的 caption 或 text 参数，正确方式是使用 MediaGroupBuilder 在构建媒体组时统一设置 caption，且仅首张媒体生效。
aiogram 3.x 不支持 `answer_media_group()` 的 `caption` 或 `text` 参数，正确方式是使用 `mediagroupbuilder` 在构建媒体组时统一设置 caption，且仅首张媒体生效。
在 Aiogram 3.x（如 3.4.1）中，message.answer_media_group() 方法不接受 caption 或 text 参数——这是常见误区。直接传入 caption="Text123" 会被静默忽略，导致文字无法显示。根本原因在于 Telegram Bot API 对媒体组（media group）的规范：仅第一项媒体（InputMediaPhoto / InputMediaVideo 等）可携带 caption 字段，其余项必须为空；而 Aiogram 3+ 要求开发者显式构造符合该规范的媒体列表。
✅ 正确做法：使用 aiogram.utils.media_group.MediaGroupBuilder
该工具类会自动确保仅首个媒体项包含 caption，其余项保持 clean，完全兼容 Telegram API 规范。
✅ 完整示例代码
from aiogram import Router
from aiogram.types import Message, InputMediaPhoto
from aiogram.utils.media_group import MediaGroupBuilder
router = Router()
@router.message(lambda m: m.photo) # 示例：接收含照片的消息
async def handle_photo_group(message: Message):
# 获取所有照片的 file_id（推荐用最高分辨率，即最后一个 photo 对象）
photo_ids = [photo.file_id for photo in message.photo]
# 构建媒体组，统一设置标题（仅首张显示）
media_group = MediaGroupBuilder(caption="✨ 这是一组活动实拍图！")
for photo_id in photo_ids:
media_group.add_photo(media=photo_id)
# 发送 —— 注意：传入的是 media_group.build()，不是 media_group
await message.answer_media_group(media=media_group.build())
⚠️ 关键注意事项
- caption 必须在 MediaGroupBuilder(...) 初始化时传入，不能在 add_photo() 中重复设置；
- add_photo() 的 media 参数应为 file_id（字符串）或 InputFile（如本地路径），不可传 InputMediaPhoto 对象；
- 若需添加按钮（InlineKeyboard），answer_media_group() 不支持 reply_markup；如需交互，建议改用单图轮播 + 分页按钮，或在首图后追加一条带按钮的文本消息；
- MediaGroupBuilder 同样支持视频（.add_video()）、文档（.add_document()）等，但 caption 逻辑一致：仅首项生效。
? 补充技巧：获取高质量图片 ID
Telegram 每张照片会返回多个尺寸（按 photo 列表升序排列，小图→大图）。推荐取最后一个（最高清）：
def get_highest_res_photo_id(message: Message) -> str:
return message.photo[-1].file_id if message.photo else ""
通过 MediaGroupBuilder，你既能批量发送图片，又能确保标题语义清晰、格式合规——这是 Aiogram 3.x 官方推荐且唯一可靠的方案。
