后端即时通讯API设计【免费下载链接】aiogramaiogram is a modern and fully asynchronous framework for Telegram Bot API written in Python using asyncio项目地址https://gitcode.com/gh_mirrors/ai/aiogram点击查看免费下载导读本文围绕 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 typetype: Literal[InlineQueryResultType.VIDEO] InlineQueryResultType.VIDEO结果类型固定为字符串video。aiogram 使用Literal类型结合 aiogram/enums/inline_query_result_type.py 中的InlineQueryResultType.VIDEO枚举来约束该字段构造时通常无需显式传入默认值即已正确。2.2 idid: str结果唯一标识符1-64 字节。它用于在分页next_offset或客户端收藏等场景中标识同一结果应在你的机器人内保持唯一。建议使用递增数字、UUID 或哈希值生成。2.3 video_urlvideo_url: str视频的有效 URL。注意官方文档的提示——所有内联查询结果中出现的 URL 对最终用户都是公开可见的因此不要把私有地址或带敏感 token 的链接放进这里。2.4 mime_typemime_type: strvideo_url内容的 MIME 类型只有两种合法取值MIME 值含义text/htmlURL 指向一个包含嵌入式播放器的 HTML 页面如 YouTube、Vimeo 等平台视频video/mp4URL 直接指向可下载播放的 MP4 视频文件两种取值对应完全不同的行为video/mp4时 Telegram 可以直接把视频文件发给用户text/html时客户端无法发送页面本身因此必须配合input_message_content提供可发送的替代内容。2.5 thumbnail_urlthumbnail_url: str视频缩略图 URL仅支持 JPEG 格式。该缩略图会在内联查询结果列表中作为预览展示请确保 URL 可公开访问且为 JPEG 图片。2.6 titletitle: 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_modecaption 的实体解析模式可选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 descriptiondescription: str | None None结果的简短描述显示在列表中辅助用户快速了解内容。3.4 reply_markupreply_markup: InlineKeyboardMarkup | None None附加在发送消息上的内联键盘类型为 InlineKeyboardMarkup。常用于给视频结果附带打开频道分享等快捷按钮。3.5 input_message_contentinput_message_content: InputMessageContentUnion | None None用于指定用户点击结果后实际发送的消息内容取值来自 InputMessageContentUnion文本、富文本、位置、地点、联系人、发票等。如前所述当mime_type为text/html如 YouTube 视频时该字段必填。四、源码结构字段定义与类型约束从实现细节看aiogram/types/inline_query_result_video.py 具有鲜明的 aiogram 风格类使用 Pydantic 模型定义字段带完整类型注解与 docstring且模型配置extraallow、use_enum_valuesTrue见 aiogram/types/base.py保证与 Telegram API 的 JSON 交互兼容文件末尾有一段标注由butcher自动生成的__init__签名if TYPE_CHECKING:块内其目的是在不引入任何运行时插件的情况下为 IDE 和类型检查工具提供精确的构造参数提示。这意味着你在编写代码时可以直接获得完整的参数补全与类型校验类型本身被收录进 InlineQueryResultUnion20 种结果的联合类型别名因此它可以无缝放入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, botbot, filesfiles, _dumps_json_dumps_json)即从bot.default一个DefaultBotProperties实例中取出同名配置项的值。你可以这样在创建 Bot 时设置全局默认from aiogram import Bot bot Bot( tokenYOUR_TOKEN, defaultDefaultBotProperties(parse_modeHTML), )这样所有使用Default(parse_mode)的字段包括InlineQueryResultVideo.parse_mode都会自动沿用HTML若你在构造InlineQueryResultVideo时显式传了parse_modeMarkdownV2则局部值优先。这一机制让内联查询结果可以集中管理格式化风格无需逐个结果重复设置。六、实战在 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( idyt1, video_urlhttps://www.youtube.com/watch?vexample, mime_typetext/html, thumbnail_urlhttps://i.ytimg.com/vi/example/hqdefault.jpg, title示例视频, caption来自 YouTube 的示例视频, parse_modeHTML, description点击后发送文本消息替代视频, input_message_contentInputTextMessageContent( message_text这里是一条替代视频的文本消息, ), ) ] else: # 场景二直接指向 MP4 文件可真正发送视频 results [ InlineQueryResultVideo( idmp41, video_urlhttps://example.com/videos/demo.mp4, mime_typevideo/mp4, thumbnail_urlhttps://example.com/thumbs/demo.jpg, title演示视频, video_width1280, video_height720, video_duration15, captionMP4 视频文件可被直接发送, ) ] await bot.answer_inline_query( inline_query_idinline_query.id, resultsresults, cache_time30, is_personalTrue, )6.2 answerInlineQuery 与结果限制上述bot.answer_inline_query(...)对应 AnswerInlineQuery 方法API 方法名answerInlineQuery其关键约束每次查询最多返回 50 条结果cache_time结果在服务器端的缓存秒数默认 300is_personal为True时结果仅对当前查询用户缓存适合带个性化排序的结果next_offset分页游标长度不超过 64 字节空字符串表示没有更多结果button可替换已弃用的switch_pm_text/switch_pm_parameter字段用于在结果上方显示切换按钮。需要说明的是aiogram 也支持直接通过InlineQuery.answer帮助方法应答无需显式传入inline_query_id两种方式最终都调用同一个answerInlineQueryAPI。七、常见问题与注意事项HTML 页面结果忘记input_message_content当mime_typetext/html而未提供input_message_content时Telegram 会报错。这是该类型最常见的构造错误务必成对设置。缩略图必须为 JPEGthumbnail_url只接受 JPEG 图片其他格式可能导致结果不被接受或展示异常。URL 公开性所有 URL 对用户可见切勿在video_url、thumbnail_url中携带私有凭证。caption 长度实体解析后的长度上限为 1024 字符超长会被拒绝。结果 id 唯一性同一查询返回的多个结果中id不能重复且应控制在 1-64 字节。Default字段的可覆盖性parse_mode、show_caption_above_media是全局默认优先、局部显式覆盖的字段理解这一点可以避免为什么没生效的困惑。参考实现仓库中的 examples/web_app/routes.py 展示了InlineQueryResultArticle配合InlineKeyboardMarkup、InputTextMessageContent构造内联结果的完整模式可作为编写InlineQueryResultVideo组合场景的参考。八、小结InlineQueryResultVideo是 aiogram 内联查询体系中用于视频这一内容形态的标准答案通过mime_type区分 HTML 播放页与 MP4 文件两种投递方式借助input_message_content兜底不可直接发送的页面类结果并通过Default机制与机器人全局配置无缝衔接。掌握其字段语义与answerInlineQuery的配合方式即可在自建 bot 中稳定、合规地返回视频类内联查询结果。赞分享后端即时通讯API设计【免费下载链接】aiogramaiogram is a modern and fully asynchronous framework for Telegram Bot API written in Python using asyncio项目地址https://gitcode.com/gh_mirrors/ai/aiogram点击查看免费下载相关推荐aiogram 内联查询结果 InlineQueryResultGif 类型详解GIF 结果字段、配置与实战用法aiogram 内联查询结果 InlineQueryResultGif 类型详解GIF 结果字段、配置与实战用法 导读 InlineQueryResultGi后端即时通讯API设计aiogram 内联查询缓存视频结果InlineQueryResultCachedVideo 完整指南aiogram 内联查询缓存视频结果InlineQueryResultCachedVideo 完整指南 本指南聚焦 aiogram 框架中 Telegram后端即时通讯API设计aiogram ChosenInlineResult 类型详解捕获用户选择的内联查询结果与反馈aiogram ChosenInlineResult 类型详解捕获用户选择的内联查询结果与反馈 导读 ChosenInlineResult 是 Telegra后端即时通讯API设计上一篇告别卡顿Yuedu书源加载慢、章节丢失问题深度优化指南下一篇Luxon源码深度剖析DateTime、Zone四大时区实现与Intl底层架构全解读创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/13 6:08:17 · 阅读 1.2k aiogram InlineQueryResultVideo 类型详解：实现嵌入式视频的内联查询结果
后端即时通讯API设计【免费下载链接】aiogramaiogram is a modern and fully asynchronous framework for Telegram Bot API written in Python using asyncio项目地址https://gitcode.com/gh_mirrors/ai/aiogram点击查看免费下载导读本文围绕 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 typetype: Literal[InlineQueryResultType.VIDEO] InlineQueryResultType.VIDEO结果类型固定为字符串video。aiogram 使用Literal类型结合 aiogram/enums/inline_query_result_type.py 中的InlineQueryResultType.VIDEO枚举来约束该字段构造时通常无需显式传入默认值即已正确。2.2 idid: str结果唯一标识符1-64 字节。它用于在分页next_offset或客户端收藏等场景中标识同一结果应在你的机器人内保持唯一。建议使用递增数字、UUID 或哈希值生成。2.3 video_urlvideo_url: str视频的有效 URL。注意官方文档的提示——所有内联查询结果中出现的 URL 对最终用户都是公开可见的因此不要把私有地址或带敏感 token 的链接放进这里。2.4 mime_typemime_type: strvideo_url内容的 MIME 类型只有两种合法取值MIME 值含义text/htmlURL 指向一个包含嵌入式播放器的 HTML 页面如 YouTube、Vimeo 等平台视频video/mp4URL 直接指向可下载播放的 MP4 视频文件两种取值对应完全不同的行为video/mp4时 Telegram 可以直接把视频文件发给用户text/html时客户端无法发送页面本身因此必须配合input_message_content提供可发送的替代内容。2.5 thumbnail_urlthumbnail_url: str视频缩略图 URL仅支持 JPEG 格式。该缩略图会在内联查询结果列表中作为预览展示请确保 URL 可公开访问且为 JPEG 图片。2.6 titletitle: 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_modecaption 的实体解析模式可选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 descriptiondescription: str | None None结果的简短描述显示在列表中辅助用户快速了解内容。3.4 reply_markupreply_markup: InlineKeyboardMarkup | None None附加在发送消息上的内联键盘类型为 InlineKeyboardMarkup。常用于给视频结果附带打开频道分享等快捷按钮。3.5 input_message_contentinput_message_content: InputMessageContentUnion | None None用于指定用户点击结果后实际发送的消息内容取值来自 InputMessageContentUnion文本、富文本、位置、地点、联系人、发票等。如前所述当mime_type为text/html如 YouTube 视频时该字段必填。四、源码结构字段定义与类型约束从实现细节看aiogram/types/inline_query_result_video.py 具有鲜明的 aiogram 风格类使用 Pydantic 模型定义字段带完整类型注解与 docstring且模型配置extraallow、use_enum_valuesTrue见 aiogram/types/base.py保证与 Telegram API 的 JSON 交互兼容文件末尾有一段标注由butcher自动生成的__init__签名if TYPE_CHECKING:块内其目的是在不引入任何运行时插件的情况下为 IDE 和类型检查工具提供精确的构造参数提示。这意味着你在编写代码时可以直接获得完整的参数补全与类型校验类型本身被收录进 InlineQueryResultUnion20 种结果的联合类型别名因此它可以无缝放入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, botbot, filesfiles, _dumps_json_dumps_json)即从bot.default一个DefaultBotProperties实例中取出同名配置项的值。你可以这样在创建 Bot 时设置全局默认from aiogram import Bot bot Bot( tokenYOUR_TOKEN, defaultDefaultBotProperties(parse_modeHTML), )这样所有使用Default(parse_mode)的字段包括InlineQueryResultVideo.parse_mode都会自动沿用HTML若你在构造InlineQueryResultVideo时显式传了parse_modeMarkdownV2则局部值优先。这一机制让内联查询结果可以集中管理格式化风格无需逐个结果重复设置。六、实战在 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( idyt1, video_urlhttps://www.youtube.com/watch?vexample, mime_typetext/html, thumbnail_urlhttps://i.ytimg.com/vi/example/hqdefault.jpg, title示例视频, caption来自 YouTube 的示例视频, parse_modeHTML, description点击后发送文本消息替代视频, input_message_contentInputTextMessageContent( message_text这里是一条替代视频的文本消息, ), ) ] else: # 场景二直接指向 MP4 文件可真正发送视频 results [ InlineQueryResultVideo( idmp41, video_urlhttps://example.com/videos/demo.mp4, mime_typevideo/mp4, thumbnail_urlhttps://example.com/thumbs/demo.jpg, title演示视频, video_width1280, video_height720, video_duration15, captionMP4 视频文件可被直接发送, ) ] await bot.answer_inline_query( inline_query_idinline_query.id, resultsresults, cache_time30, is_personalTrue, )6.2 answerInlineQuery 与结果限制上述bot.answer_inline_query(...)对应 AnswerInlineQuery 方法API 方法名answerInlineQuery其关键约束每次查询最多返回 50 条结果cache_time结果在服务器端的缓存秒数默认 300is_personal为True时结果仅对当前查询用户缓存适合带个性化排序的结果next_offset分页游标长度不超过 64 字节空字符串表示没有更多结果button可替换已弃用的switch_pm_text/switch_pm_parameter字段用于在结果上方显示切换按钮。需要说明的是aiogram 也支持直接通过InlineQuery.answer帮助方法应答无需显式传入inline_query_id两种方式最终都调用同一个answerInlineQueryAPI。七、常见问题与注意事项HTML 页面结果忘记input_message_content当mime_typetext/html而未提供input_message_content时Telegram 会报错。这是该类型最常见的构造错误务必成对设置。缩略图必须为 JPEGthumbnail_url只接受 JPEG 图片其他格式可能导致结果不被接受或展示异常。URL 公开性所有 URL 对用户可见切勿在video_url、thumbnail_url中携带私有凭证。caption 长度实体解析后的长度上限为 1024 字符超长会被拒绝。结果 id 唯一性同一查询返回的多个结果中id不能重复且应控制在 1-64 字节。Default字段的可覆盖性parse_mode、show_caption_above_media是全局默认优先、局部显式覆盖的字段理解这一点可以避免为什么没生效的困惑。参考实现仓库中的 examples/web_app/routes.py 展示了InlineQueryResultArticle配合InlineKeyboardMarkup、InputTextMessageContent构造内联结果的完整模式可作为编写InlineQueryResultVideo组合场景的参考。八、小结InlineQueryResultVideo是 aiogram 内联查询体系中用于视频这一内容形态的标准答案通过mime_type区分 HTML 播放页与 MP4 文件两种投递方式借助input_message_content兜底不可直接发送的页面类结果并通过Default机制与机器人全局配置无缝衔接。掌握其字段语义与answerInlineQuery的配合方式即可在自建 bot 中稳定、合规地返回视频类内联查询结果。赞分享后端即时通讯API设计【免费下载链接】aiogramaiogram is a modern and fully asynchronous framework for Telegram Bot API written in Python using asyncio项目地址https://gitcode.com/gh_mirrors/ai/aiogram点击查看免费下载相关推荐aiogram 内联查询结果 InlineQueryResultGif 类型详解GIF 结果字段、配置与实战用法aiogram 内联查询结果 InlineQueryResultGif 类型详解GIF 结果字段、配置与实战用法 导读 InlineQueryResultGi后端即时通讯API设计aiogram 内联查询缓存视频结果InlineQueryResultCachedVideo 完整指南aiogram 内联查询缓存视频结果InlineQueryResultCachedVideo 完整指南 本指南聚焦 aiogram 框架中 Telegram后端即时通讯API设计aiogram ChosenInlineResult 类型详解捕获用户选择的内联查询结果与反馈aiogram ChosenInlineResult 类型详解捕获用户选择的内联查询结果与反馈 导读 ChosenInlineResult 是 Telegra后端即时通讯API设计上一篇告别卡顿Yuedu书源加载慢、章节丢失问题深度优化指南下一篇Luxon源码深度剖析DateTime、Zone四大时区实现与Intl底层架构全解读创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考