aiogram InlineQueryResultVideo 类型详解：实现嵌入式视频的内联查询结果

• 后端
• 即时通讯
• API设计

导读

本文围绕 aiogram 框架中InlineQueryResultVideo类型展开，深入讲解如何用它向 Telegram 用户返回"嵌入式视频播放页链接"或"视频文件链接"这类内联查询结果。你将掌握该类型的全部必填与可选字段、text/html与video/mp4两种 MIME 类型的差异、input_message_content的强制替换规则，以及如何与answerInlineQuery方法、Default默认值机制配合，写出可直接运行的内联视频查询机器人。

一、InlineQueryResultVideo 是什么

InlineQueryResultVideo是 Telegram Bot API 中 20 种内联查询结果类型之一，官方语义为：表示一个指向包含嵌入式视频播放器页面或视频文件的链接。用户点击该结果后，默认会直接发送视频文件（可附带可选 caption）；或者，开发者可以通过input_message_content让用户发送一个自定义内容的消息，而非视频本身。

在 aiogram 中，该类型的完整定义位于 aiogram/types/inline_query_result_video.py，其 API 参考文档由 docs/api/types/inline_query_result_video.rst 通过 Sphinxautomodule指令自动生成。类型继承自 aiogram/types/inline_query_result.py 中的InlineQueryResult（其本身继承MutableTelegramObject，支持字段赋值），因此它和其他 19 种结果类型一样，可以放入answerInlineQuery的results列表中使用。

一个特别需要记住的约束（来自源码 docstring）：

如果InlineQueryResultVideo消息包含嵌入式视频（例如 YouTube），必须使用input_message_content替换其内容。

这是因为 Telegram 客户端无法直接发送 HTML 播放页本身，只能发送可下载的视频文件，因此这类结果必须换用自定义消息内容。

二、必填字段：构造一个合法结果的基石

InlineQueryResultVideo有 6 个必填字段，缺一不可，它们是 Telegram 服务器校验合法性的最低要求。

2.1 type

type: Literal[InlineQueryResultType.VIDEO] = InlineQueryResultType.VIDEO

结果类型，固定为字符串"video"。aiogram 使用Literal类型结合 aiogram/enums/inline_query_result_type.py 中的InlineQueryResultType.VIDEO枚举来约束该字段，构造时通常无需显式传入，默认值即已正确。

2.2 id

id: str

结果唯一标识符，1-64 字节。它用于在分页（next_offset）或客户端收藏等场景中标识同一结果，应在你的机器人内保持唯一。建议使用递增数字、UUID 或哈希值生成。

2.3 video_url

video_url: str

视频的有效 URL。注意官方文档的提示——所有内联查询结果中出现的 URL 对最终用户都是公开可见的，因此不要把私有地址或带敏感 token 的链接放进这里。

2.4 mime_type

mime_type: str

video_url内容的 MIME 类型，只有两种合法取值：

两种取值对应完全不同的行为：video/mp4时 Telegram 可以直接把视频文件发给用户；text/html时客户端无法发送页面本身，因此必须配合input_message_content提供可发送的替代内容。

2.5 thumbnail_url

thumbnail_url: str

视频缩略图 URL，仅支持 JPEG 格式。该缩略图会在内联查询结果列表中作为预览展示，请确保 URL 可公开访问且为 JPEG 图片。

2.6 title

title: str

结果标题，将显示在内联结果列表中供用户选择。

三、可选字段：丰富结果展示与行为

除必填字段外，InlineQueryResultVideo还提供了一批可选字段，覆盖说明文字、尺寸信息与交互扩展。

3.1 视频说明文本

caption: str | None = None parse_mode: str | Default | None = Default("parse_mode") caption_entities: list[MessageEntity] | None = None show_caption_above_media: bool | Default | None = Default("show_caption_above_media")

• caption：随视频一起发送的说明文字，实体解析后 0-1024 字符；
• parse_mode：caption 的实体解析模式，可选HTML、MarkdownV2、Markdown（见 aiogram/enums/parse_mode.py）。它的默认值是Default("parse_mode")，含义是"沿用机器人在Bot构造时设置的全局默认解析模式"，而非固定值——具体机制见本文第五节；
• caption_entities：当需要精确控制实体时，可传入 MessageEntity 列表替代parse_mode的文本标记解析；
• show_caption_above_media：传True时 caption 显示在媒体上方。与parse_mode相同，它也是Default型字段，会回退到机器人全局设置。

3.2 视频尺寸与时长

video_width: int | None = None video_height: int | None = None video_duration: int | None = None

分别表示视频宽度、高度和时长（秒）。这些信息会显示在内联结果列表中，帮助用户判断视频内容。对于video/mp4类型的文件结果，建议填写真实尺寸与时长以获得更好的展示效果。

3.3 description

description: str | None = None

结果的简短描述，显示在列表中辅助用户快速了解内容。

3.4 reply_markup

reply_markup: InlineKeyboardMarkup | None = None

附加在发送消息上的内联键盘，类型为 InlineKeyboardMarkup。常用于给视频结果附带"打开频道""分享"等快捷按钮。

3.5 input_message_content

input_message_content: InputMessageContentUnion | None = None

用于指定"用户点击结果后实际发送的消息内容"，取值来自 InputMessageContentUnion（文本、富文本、位置、地点、联系人、发票等）。如前所述，当mime_type为text/html（如 YouTube 视频）时该字段必填。

四、源码结构：字段定义与类型约束

从实现细节看，aiogram/types/inline_query_result_video.py 具有鲜明的 aiogram 风格：

• 类使用 Pydantic 模型定义，字段带完整类型注解与 docstring，且模型配置extra="allow"、use_enum_values=True（见 aiogram/types/base.py），保证与 Telegram API 的 JSON 交互兼容；
• 文件末尾有一段标注"由butcher自动生成"的__init__签名（if TYPE_CHECKING:块内），其目的是在不引入任何运行时插件的情况下，为 IDE 和类型检查工具提供精确的构造参数提示。这意味着你在编写代码时可以直接获得完整的参数补全与类型校验；
• 类型本身被收录进 InlineQueryResultUnion（20 种结果的联合类型别名），因此它可以无缝放入answerInlineQuery的results: list[InlineQueryResultUnion]中。

五、Default 机制：parse_mode 为何是 Default("parse_mode")

这是 aiogram 中一个容易困惑却非常实用的设计。字段值Default("parse_mode")并非字符串，而是 aiogram/client/default.py 中定义的Default哨兵对象，它在请求真正发往 Telegram 前才被"解析"成实际值。

解析过程发生在会话层：BaseSession.prepare_value中（见 aiogram/client/session/base.py），当检测到值是Default实例时，会执行：

if isinstance(value, Default): default_value = bot.default[value.name] return self.prepare_value(default_value, bot=bot, files=files, _dumps_json=_dumps_json)

即从bot.default（一个DefaultBotProperties实例）中取出同名配置项的值。你可以这样在创建 Bot 时设置全局默认：

from aiogram import Bot bot = Bot( token="YOUR_TOKEN", default=DefaultBotProperties(parse_mode="HTML"), )

这样，所有使用Default("parse_mode")的字段（包括InlineQueryResultVideo.parse_mode）都会自动沿用HTML；若你在构造InlineQueryResultVideo时显式传了parse_mode="MarkdownV2"，则局部值优先。这一机制让内联查询结果可以集中管理格式化风格，无需逐个结果重复设置。

六、实战：在 inline_query 处理器中返回视频结果

6.1 注册处理器

aiogram 3.x 中，内联查询事件在 aiogram/dispatcher/router.py 上通过router.inline_query(...)装饰器注册。路由器中存在独立的TelegramEventObserver，事件名为inline_query。

from aiogram import Bot, Dispatcher, Router from aiogram.filters import CommandStart from aiogram.types import ( InlineQuery, InlineQueryResultVideo, InputTextMessageContent, ) router = Router() @router.inline_query() async def handle_inline_query(inline_query: InlineQuery, bot: Bot): query = inline_query.query.strip().lower() if not query: return if query == "youtube": # 场景一：嵌入式播放页（text/html），必须使用 input_message_content results = [ InlineQueryResultVideo( id="yt1", video_url="https://www.youtube.com/watch?v=example", mime_type="text/html", thumbnail_url="https://i.ytimg.com/vi/example/hqdefault.jpg", title="示例视频", caption="来自 YouTube 的示例视频", parse_mode="HTML", description="点击后发送文本消息替代视频", input_message_content=InputTextMessageContent( message_text="这里是一条替代视频的文本消息", ), ) ] else: # 场景二：直接指向 MP4 文件，可真正发送视频 results = [ InlineQueryResultVideo( id="mp41", video_url="https://example.com/videos/demo.mp4", mime_type="video/mp4", thumbnail_url="https://example.com/thumbs/demo.jpg", title="演示视频", video_width=1280, video_height=720, video_duration=15, caption="MP4 视频文件，可被直接发送", ) ] await bot.answer_inline_query( inline_query_id=inline_query.id, results=results, cache_time=30, is_personal=True, )

6.2 answerInlineQuery 与结果限制

上述bot.answer_inline_query(...)对应 AnswerInlineQuery 方法（API 方法名answerInlineQuery），其关键约束：

• 每次查询最多返回 50 条结果；
• cache_time：结果在服务器端的缓存秒数，默认 300；
• is_personal：为True时结果仅对当前查询用户缓存，适合带个性化排序的结果；
• next_offset：分页游标，长度不超过 64 字节，空字符串表示没有更多结果；
• button：可替换已弃用的switch_pm_text/switch_pm_parameter字段，用于在结果上方显示切换按钮。

需要说明的是，aiogram 也支持直接通过InlineQuery.answer帮助方法应答（无需显式传入inline_query_id），两种方式最终都调用同一个answerInlineQueryAPI。

七、常见问题与注意事项

1. HTML 页面结果忘记input_message_content：当mime_type="text/html"而未提供input_message_content时，Telegram 会报错。这是该类型最常见的构造错误，务必成对设置。
2. 缩略图必须为 JPEG：thumbnail_url只接受 JPEG 图片，其他格式可能导致结果不被接受或展示异常。
3. URL 公开性：所有 URL 对用户可见，切勿在video_url、thumbnail_url中携带私有凭证。
4. caption 长度：实体解析后的长度上限为 1024 字符，超长会被拒绝。
5. 结果 id 唯一性：同一查询返回的多个结果中id不能重复，且应控制在 1-64 字节。
6. Default字段的可覆盖性：parse_mode、show_caption_above_media是"全局默认优先、局部显式覆盖"的字段，理解这一点可以避免"为什么没生效"的困惑。
7. 参考实现：仓库中的 examples/web_app/routes.py 展示了InlineQueryResultArticle配合InlineKeyboardMarkup、InputTextMessageContent构造内联结果的完整模式，可作为编写InlineQueryResultVideo组合场景的参考。

八、小结

InlineQueryResultVideo是 aiogram 内联查询体系中用于"视频"这一内容形态的标准答案：通过mime_type区分 HTML 播放页与 MP4 文件两种投递方式，借助input_message_content兜底不可直接发送的页面类结果，并通过Default机制与机器人全局配置无缝衔接。掌握其字段语义与answerInlineQuery的配合方式，即可在自建 bot 中稳定、合规地返回视频类内联查询结果。

• 后端
• 即时通讯
• API设计