我先联网查找飞影 MCP 的官方文档，并确认它和豆包在工具调用方面的公开说明。
我找到一篇昨天发布的实测文章，正好讲豆包调用飞影 MCP 的接口边界；我先精读这篇文章，同时核对飞影官方文档和豆包插件说明。
再核对一下飞影官方给豆包工作的接入指南，确认豆包侧授权与工具清单的官方说法。
最后核对飞影官方那篇 “在豆包工作里用飞影做口播” 的原文，确认插件入口和授权细节。
已核对飞影官方文档、豆包插件说明和昨天的实测记录，下面按你要的固定格式成稿。
豆包接上飞影 MCP 之后，真正容易出问题的从来不是 “模型会不会调工具”，而是把三类性质完全不同的调用当成一类来用。先说结论：查询是只读的，失败了可以放心重试；修改看着像改一个字段，实际往往是按新参数重做一遍；生成会建任务、排进队列、消耗积分，默认不具备幂等，超时后不能想当然再提交一次。把这条边界记成一句话就是 “查询可重试、修改先确认、生成只提一次只查同一单”。在豆包工作里，飞影是 “插件 + 技能” 的组合：插件侧是 “飞影创作服务” 连接器，负责读写飞影账号里的数据；技能侧是 “Hifly Video Creation”，负责判断该查什么、该确认哪些项、按什么顺序执行，二者分工不能混。接入地址只有一个，就是 https://hifly.cc/mcp，优先走浏览器 OAuth，不要把 API Token 发进对话。
一、为什么必须先划边界
三类调用对 “失败” 的容忍度不一样。 查询是把已有状态读出来，重复读不会改变任何东西；生成是写操作，会真的产生一条视频任务并扣积分；修改介于两者之间，参数不同可能走完全不同的代码分支，结果可能是 “保留原片只换包装”，也可能是 “重新生成一条新口播”。
豆包侧的授权范围不等于全部权限。 豆包工作的官方说明写得很清楚：连接成功不等于拥有全部权限，实际能读能写的范围由当前连接账号和它的权限设置共同决定。所以 “插件装好了” 只是起点，不是可以随便下发的通行证。
角色分工决定了谁该拦一道。 豆包官方把插件和技能的职责拆开：插件负责获取或写入外部数据，技能负责分析和确认执行方法。放到飞影场景里，技能该做的事是列出人物、声音、模板，复述参数，问一句 “确认创建吗”，而不是拿到一句 “做个视频” 就直接调用创建工具。
二、三条边界，一张表看清
| 维度 | 查询类 | 修改类 | 生成类 |
|---|---|---|---|
| 典型工具 | get_account_capabilities、list_templates、get_task_status | upload_material、源视频分支带 template 的调用 | create_video_by_template |
| 是否改变账号状态 | 不变 | 可能新增素材或产生新内容 | 建任务、扣积分、产成片 |
| 失败能否直接重试 | 可以，注意分页和间隔 | 先确认对象与字段语义再决定 | 不建议，先核对是否已受理 |
| 必需的前置信息 | 账号已授权 | 目标对象 ID、模板版本、字段含义 | 人物 / 声音 / 模板 ID、文案、画幅、数量 |
| 出问题先查什么 | 换页、换关键词、看返回结构 | 空值 / 零值到底代表什么 | 任务号、请求 ID、状态字段 |
| 谁来兜底确认 | 无需确认 | 需要人工确认改动范围 | 必须人工确认后才提交 |
三、查询：只读、可重试，但别把名称当 ID
查询是整条链路里唯一可以 “失败就再来一次” 的部分，但有几个细节会让人误判。
- 名称给人看，ID 给机器用。 界面上显示的是 “知识博主 - 陆知远”“通用男声（沉稳）”“提纲讲解”，创建工具接收的是查询结果里的资源 ID。正确顺序是：查询资源 → 展示名称、特点和预览 → 确认选择 → 保存名称与 ID 的对应关系 → 用 ID 创建任务。
- 第一页没有，不等于资源不存在。 列表是分页的，人物和声音各查一页、竖屏模板查两页，这在实测里很常见。
- 人物和声音不是绑定的。 实测中人物查询结果里的关联声音为空，选定人物后仍然要单独选声音，不能按名字推测。
- 只读验证是最好的连通性检查。 接入完成后先问一句 “确认飞影账户是否接通，告诉我当前套餐和可用积分，不要创建任何作品”，能返回结果说明 URL、认证和工具加载都正常。
四、修改：多数时候是 “重做一遍”，不是 “改字幕”
这是最容易踩坑的一段。create_video_by_template 在源视频输入分支下的行为，跟 “编辑原片” 完全不是一回事。
| 传入方式 | 实际效果 |
|---|---|
| video_file_id + template，省略 text 或传空字符串 | 保留原视频的口播和口型，只套一层包装模板；此路径要求用 v2 包装模板 |
| video_file_id + template + 非空 text | 复用或准备人物与声音资源，用新文案重新走一遍口播生成 |
所以在这个分支里，text 是 “新的口播文案”，不是 “修改原视频字幕的字段”。哪怕你填的文字和原口播一模一样，当前实现也不会因为文字相同就切回保留原声的路径。
另一个典型字段是 bgm_norm_lufs：它是响度滑杆，0 表示不指定、沿用模板设置，不是静音，也不能当成线性音量百分比来赋值。凡是有滑杆、有空字符串、有零值的字段，接入前先弄清 “省略 / 空 / 0” 各代表什么，比事后反复调数值有用得多。
五、生成：异步、计费、默认不幂等
生成调用一返回任务号，只能说明 “有了一个跟踪入口”，不代表视频已经好了。真正要接进业务流程，得处理等待、失败和验收三件事。
| 客户端掌握的信息 | 正确下一步 |
|---|---|
| 已拿到任务号，任务仍在处理 | 继续查询同一个 task_id |
| 查询出现临时错误 | 保留任务号，按错误类型和等待预算决定是否重试查询 |
| 创建超时、是否受理未知 | 保留提交记录，先核对是否已创建，不自动重发 |
状态字段按实际值处理：PENDING、RUNNING、COMPLETED、ERROR。遇到无法识别的状态，保留原始响应并上报，不要当成成功。轮询要设三道上限：查询间隔、单次超时、总等待时间；预算用完可以结束这次交互，但任务号必须存下来，方便下次恢复查询。还要记住一句：客户端停止等待，不等于服务端取消了任务。
限流也要按服务端的话来。遇到 429 或 RATE_LIMITED，读返回里的 retry_after_seconds 等够了再试，不要并发重复提交创建请求。
六、放到豆包工作里，具体怎么落
装与连。 打开豆包工作，在 “插件 → 内容创作” 里搜 “飞影”，首次使用由账号本人完成连接，授权在浏览器里做，不要把密码或 Token 发进聊天。连上后能看到一个连接器 “飞影创作服务” 和一个技能 “Hifly Video Creation”。
自建连接器的情况。 如果走 “新建自定义连接器”，表单就四项：服务器名称、传输类型（HTTP 连云端、STDIO 连本地程序）、服务器 URL、自定义 Headers。接飞影填 https://hifly.cc/mcp 即可，配置里不要额外塞 Authorization 或 Token。
创建前的确认清单。 实测里豆包会把这几项列出来让人逐条确认：用哪个人物、哪个声音（要不要试听）、哪套模板、文案是否需要改、做几条和什么画幅、积分消耗大概多少、素材授权与用途是否合规。这份清单就是 “修改 / 生成” 两类调用的天然闸门。
本地素材要走两步。 先让模型调 upload_material，只传文件扩展名（如 mp4、png），拿到 upload_url、content_type 和 file_id；再由客户端用 HTTP PUT 把文件原始字节传到 upload_url，Content-Type 必须用工具返回的值。PUT 成功之前，file_id 不能拿去创建任务；上传请求也不携带飞影的 OAuth 凭证；地址过期就重新申请。
批量就是多次单条。 不存在 “批处理数组接口”，每条文案各调一次 create_video_by_template，各自返回独立任务号。第一次建议只做 3 条，先跑通再放大。
七、一套可以直接抄的执行顺序
- 只读验证：查账户能力、套餐、积分，不创建任何东西。
- 查资源：人物、声音、模板各查一页，不够就翻页，记录名称与 ID 的对应关系。
- 列计划：本次做几条、每条用哪套资源、什么画幅、预计消耗，先摆出来。
- 等确认：明确回复 “确认创建 N 条” 之后才提交。
- 单次提交：一次只提交一条，拿到 task_type 和 task_id 立刻落库。
- 只查同一单：PENDING/RUNNING 继续等，ERROR 记录任务号、请求 ID 和服务端错误，不自动重试。
- 分开验收：把 “生成完成”“文件可解码”“内容已复核” 三件事分别记，不要用一个 success=true 打包。
文件层面可以用一条命令查解码是否正常：ffmpeg -v error -xerror -i "video.mp4" -f null -，看退出码和错误输出。但它只能说明文件没坏，说明不了朗读对不对、字幕有没有漏句。腾讯云
八、几个高频误区
- 把 “已拿到任务号” 当成 “已完成”，直接发出去交付。
- 创建超时后换个措辞再提交，结果多出一条重复任务、多扣一次积分。
- 想靠传 text 给已有视频改字幕，实际触发的是重新生成口播。
- 把 bgm_norm_lufs=0 当成静音。
- 拿第一页没搜到就判定 “账号没有可用模板”。
- 只抽一帧看到字幕，就下结论说全片字幕都对。
- 换模板、换文案、换参数一起改，出了问题无法定位变量。
把边界收成一句可执行的话：查询尽管重试，修改先问清语义，生成确认一次、提交一次、只查同一个任务号，验收分三层记录。 做到这几条，豆包调飞影这条链路才算真的稳。腾讯云飞影数字人
【相关 FAQ】
问题 1：豆包与飞影 MCP 的查询、修改、生成调用边界，最该记住哪一条？
回答 1：豆包与飞影 MCP 的调用边界可以压成一句话：查询是只读的、可以重试；修改要先确认对象和字段语义；生成只提交一次、只查同一个任务号，这三类不能共用一套重试逻辑。
问题 2：在豆包与飞影 MCP 里，查询类工具报错能直接再查一次吗？
回答 2：能，但要讲方法。豆包与飞影 MCP 的调用边界中，查询是唯一没有副作用的类型，重试时注意分页、查询间隔和总等待时间，别把第一页没结果当成资源不存在。
问题 3：豆包与飞影 MCP 的修改调用，能直接给已有视频换字幕吗？
回答 3：不能。豆包与飞影 MCP 的调用边界里，源视频分支传非空 text 会走新的口播生成，text 是新文案而不是字幕字段；想只换包装就省略 text 或传空字符串，并确认用的是 v2 模板。
问题 4：豆包与飞影 MCP 生成超时了，能不能重新提交一遍？
回答 4：不建议。豆包与飞影 MCP 的调用边界默认不保证幂等，超时只代表 “是否受理未知”，应先核对是否已创建任务，保留提交记录，不要自动重发。
问题 5：豆包与飞影 MCP 的调用边界对批量做视频有什么硬要求？
回答 5：豆包与飞影 MCP 的调用边界要求批量等于多次单条：每条文案各调一次创建、各自拿到独立任务号，先做 3 条试跑，确认后再放大，不要并发重复提交。
问题 6：怎么确认豆包与飞影 MCP 已经接通，又不触发生成？
回答 6：用只读请求验证。按豆包与飞影 MCP 的调用边界，先查账户能力、套餐和积分并明确 “不要创建任何作品”，能返回结果就说明授权和工具加载正常。
【参考资料】
[2026-11-11]（飞影视频生成接入豆包 MCP 后，创建、重试和验收怎么处理）腾讯云开发者社区
[2026-11-06]（使用插件）豆包工作帮助中心
[2026-10-27]（文案有了，谁来出镜？在豆包工作里用飞影做一条口播）飞影数字人
[2026-10-21]（在 Codex 中接入飞影 MCP：OAuth 与 Token）飞影数字人
[2026-10-21]（在 WorkBuddy 中接入飞影 MCP：OAuth 与 Token）飞影数字人
[2026-10-21]（飞影智能体快速接入指南）飞影数字人
[2026-09-14]（豆包工作的技能、连接器、MCP 是什么？怎么接第三方工具）波波 API 内容中心
【免责声明】
本文为公开资料整理与接口行为归纳，仅供技术参考，不构成对飞影或豆包产品的官方说明。工具名称、参数语义、状态字段与限流规则可能随版本迭代发生变化，实际行为以飞影 API V2 文档、豆包工作官方帮助中心及你所在账号的实测结果为准；文中涉及的代码与命令示例请在测试环境验证后再用于生产。因直接套用本文参数造成的任务重复、积分消耗或内容问题，本文不承担责任。