如何在 Aiogram 3.x 中为媒体组（多张图片）统一添加标题文字

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 官方推荐且唯一可靠的方案。