language-swap

/pika:language-swap

以下工具均为 Pika MCP 工具，名称不带前缀——请使用当前会话为 Pika MCP 提供的任意前缀来调用。

将视频翻译并配音成另一种语言，同时保留原说话人的声音。流程：配音（一次工作器调用）→ 对口型（默认开启）→ 烧录目标语言字幕或双语字幕。

配音工作器会在一次调用中完成繁重工作：转录、翻译、在服务端保留每位说话人的声音（无需单独克隆），并返回音视频完全同步的视频——因此无需管理手动转录/克隆/TTS/替换流程，也无需手动处理时长漂移。

分段／多语言配音（按范围指定语言）

当用户希望在同一视频的不同片段使用不同语言（例如前半段为西班牙语、后半段为日语），或希望只翻译部分片段并保留其余部分的原声时，请使用此方式。这两种情况本质相同：由多个片段组成的时间线，每个片段都标记一种语言；未覆盖的范围保留原音频。

dub_video 接受 segments 方案，而不是 target_language（只能传入其中一个，两者不能同时使用）：

dub_video(source_video_url=<video_url>, segments=[
  {start_s: 0,  end_s: 30, target_language: "es"},
  {start_s: 30, end_s: 60, target_language: "ja"}
])

如何构建方案：用户需要先了解内容所在位置，才能选择范围，因此应先转录——使用 extract_audio_from_video 提取音频，然后调用 transcribe_audio(audio=<audio_url>, timestamps=true)，向用户展示带时间戳的片段，让他们指定每个时间范围对应的语言。接着组装 segments[]（以秒为单位，按顺序排列且不重叠），并调用一次 dub_video。没有单独的“视频理解”工具——带时间戳的转录内容就是理解步骤。

分段流程的行为：

• 所有片段共用同一声音。 源说话人的声音只克隆一次，随后每个片段——无论使用何种语言——都会以同一个克隆声音说出，然后回收该克隆声音，所有操作都在一次 dub_video 调用中完成。你无需自行克隆或删除声音。
• 未覆盖范围保留原音。 未被片段覆盖的任何时间范围都会原样播放原音频（人声 + 背景音）。若只想翻译视频的部分内容，只需列出要翻译的片段。
• 锁定时长。 输出时长与源视频完全一致（每个配音片段都会调整语速以适配其时间窗口），因此边界与原时间线对齐。
• 提供方。 按范围混合多种语言时，始终自动使用声音克隆路线；单次调用的整段视频配音路线无法按范围混合语言，因此不要为分段方案强行指定单次调用提供方。所有被覆盖的语言都必须受声音克隆路线支持——如果有一种语言不受支持，请显示错误并查阅 references/language-coverage.md。
• 结果。 返回相同类型的配音视频结果；target_language 会以逗号分隔的形式列出所有被覆盖的语言（例如 "spa,jpn"），且不会返回单一的 transcript_language（因为音轨包含多种语言）。对口型（步骤 2，默认开启，≤5 分钟）仍会处理整个配音视频。对于字幕（步骤 3），请在 caption_mode="manual" 中使用返回的多语言 subtitles[]；自动重新转录无法为混合语言音轨选择单一语言。

如果 dub_video 不接受 segments（较旧的部署版本不支持分段），则改为分别对每个范围进行单语言配音，然后拼接——但只要支持，就应优先使用一次调用的分段流程。

默认行为

• 目标语言：必须通过 --to <language> 指定。优先使用语言代码：es、fr、ja、de、pt-BR、zh-Hans。配音工作器接受类似 ISO/BCP-47 的标签，并会在调用 ElevenLabs 前规范化脚本和地区子标签（例如，zh-Hans → zh；zh-Hant-TW → zh）。
• 口型同步：默认开启——让说话者的嘴型与翻译后的音频重新匹配（fal sync-lipsync；这是全视频口型匹配功能，与肖像图像动画器不同）。如果源视频中没有出镜人物，或想避免较高的费用（sync-2-pro 级别约为每分钟 4 美元），请传入 --no-lipsync 跳过。仅适用于时长不超过 5 分钟的视频——上游的 edit_lipsync 将时长硬性限制为 300 秒，因此更长的源视频会自动跳过口型同步（见步骤 2）；配音本身没有时长限制。
• 背景音乐：默认保留——配音会将翻译后的语音叠加到原始音乐／音效轨上。传入 --no-bgm 可生成仅含翻译内容的输出：工作器会丢弃原始音乐，只保留翻译后的语音（drop_background_audio=true）。
• 字幕：默认烧录目标语言字幕。用户要求双语／双语种字幕时，将目标语言（译文）行烧录在上方，将源语言（原文）行烧录在下方——配音后实际说出的是译文，因此译文应作为主行；原文则作为辅助参考。
• 双语字幕：用户传入 --bilingual-subtitles，或提出“bilingual subtitles”“dual subtitles”“two-language captions”“original + translated subtitles”“双语字幕”或“原文+译文字幕”时启用。
• 语言支持范围：如果用户询问语言支持情况，或上游发生与语言相关的错误，请查阅 references/language-coverage.md。在正常回复中不要主动列出特定提供商支持的语言详情。

生成和使用的状态变量

• video_url：输入——来自位置参数
• source_input_url：原始位置参数 URL——如果 video_url 经重新托管，则保留此值用于诊断
• target_language：文本——来自 --to <language>
• with_lipsync：布尔值——默认为 true；仅在使用 --no-lipsync 时为 false
• no_bgm：布尔值——使用 --no-bgm 时为 true（映射到 drop_background_audio=true）
• bilingual_subtitles：布尔值——用户要求双语／双语种字幕时为 true
• dubbed_video_url：已配音且音视频同步的视频——由步骤 1 生成
• dub_subtitles：配音结果中可选的目标语言定时字幕——由步骤 3 使用
• source_subtitles：配音结果中可选的源语言定时字幕——由步骤 3 用于双语字幕
• dub_transcript_srt：配音结果中可选的目标语言 SRT——供审核／调试使用
• source_transcript_srt：配音结果中可选的源语言 SRT——供审核／调试使用
• source_transcript_language：配音结果中可选的源语言代码
• lipsynced_video_url：口型已重新匹配的配音视频——由步骤 2 生成（运行口型同步时）
• caption_target_video_url：烧录字幕前的最终画面视频 URL
• final_video_url：已烧录目标语言字幕的视频——由步骤 3 生成

步骤 0 — 解析输入

必填：

• 位置参数 video_url — 必须为 https://...
• --to <language> — 目标语言（自由文本或 BCP-47 代码）

可选：

• --no-lipsync — 跳过默认的口型匹配步骤。
• --no-bgm — 仅输出翻译内容；移除原始背景音乐和音效。
• --bilingual-subtitles — 同时烧录源语言和目标语言字幕行。

即使用户未提供明确标志，也要根据用户的表述推断 bilingual_subtitles=true。

如果缺少 --to，则停止并提示用户——除非用户希望不同片段使用不同语言，或只翻译某些片段：这种情况属于按范围分段处理路径（见上文“分段／多语言配音”），该路径使用 segments 计划，而不是 --to。

对于分段处理路径，先制定时间范围计划：使用 extract_audio_from_video 提取音频，然后通过 transcribe_audio(audio=<audio_url>, timestamps=true) 转录音频并获取时间戳，向用户展示带时间戳的片段，并将各时间范围对应的语言记录到 segments[] 中。

输出：video_url、target_language、with_lipsync（默认值为 true）、no_bgm（默认值为 false）、bilingual_subtitles（默认值为 false）。

步骤 1 — 为视频配音（状态：dubbed_video_url）

调用 dub_video，并传入：

• source_video_url — <video_url>
• target_language — <target_language>（类似 ISO/BCP-47 的标记，例如 es、pt-BR、zh-Hans）
• source_language — "auto"
• drop_background_audio — 仅当设置了 no_bgm 时设为 true；否则省略（保留原始背景音乐）

dub_video 是仅限插件的 Pika MCP 工具：claude.ai 连接器界面可能落后于插件版本，因此连接器会话可能完全不提供此工具。如果工具列表中没有该工具，请如实告知，不要用其他工具替代。

dub_video 由工作进程处理：如果响应返回 {task_id, status}，则轮询 task_status，直到状态变为 completed，然后从结果中读取配音视频（视频源对应 video_url；音频源对应 audio_url）。同时获取可选的 subtitles[]、transcript_srt 和 transcript_language——这些是配音工作进程生成的目标语言转录元数据，将在步骤 3 中使用。

对于双语字幕，还要获取可选的 source_subtitles[]、source_transcript_srt 和 source_transcript_language。这些源语言转录字段尽力提供。即使缺少转录字段，配音媒体仍然有效。

**源内容无法由工作进程获取：**如果 dub_video 因无法获取源 URL 而失败，尤其是遇到 HTTP 403／4xx、防盗链、按 UA 限制访问的主机（Wikimedia／新闻 CDN）或“Access Denied”错误时，不要继续重试同一个调用。请先重新托管：

1. 在客户端／主机环境中，通过常规浏览器／下载方式或使用真实 user-agent 的 HTTP 客户端下载源文件。
2. 使用下载文件的文件名、MIME 类型和精确字节大小调用 upload_asset，然后将文件字节上传到返回的预签名 URL。
3. 设置 source_input_url = <original URL>，并将 video_url 替换为返回的 Pika CDN public_url。不要手动构造 CDN URL。
4. 使用 Pika CDN URL 重试一次步骤 1。后续所有步骤都必须使用更新后的 video_url。

如果客户端／主机也无法下载源文件字节，则停止并告知用户该主机阻止了直接获取；请用户上传文件或提供其他 URL。

输出：dubbed_video_url、dub_subtitles、source_subtitles、dub_transcript_srt、source_transcript_srt、source_transcript_language。

第 2 步 — 唇形同步（状态：lipsynced_video_url）

默认开启。传入 --no-lipsync 时完全跳过（此时第 3 步直接为 dubbed_video_url 添加字幕）。

严格限制为 5 分钟——调用前检查时长。 edit_lipsync 在上游（sync.so）强制执行 300 秒（5 分钟）的音频限制，任何更长的内容都会在计费前因 invalid_input 被拒绝；所有 variant 档位都受相同限制，因此逐档回退也无济于事。如果配音视频的 duration_seconds（由第 1 步返回）> 300，则完全跳过唇形同步，直接进入第 3 步为 dubbed_video_url 添加字幕，并告知用户超过 5 分钟的视频无法进行唇形同步（配音本身不受时长限制）。只有当 duration_seconds ≤ 300 时，才运行下面的唇形同步调用。

先提醒费用。 唇形同步是主要成本（v2-pro 档位约为 $4/分钟）。调用前，根据配音视频的 duration_seconds（由第 1 步返回）估算费用：cost_usd = duration_seconds / 60 * 4。不要把短片时长向上取整到整分钟：7 秒的片段约为 $0.47，而不是约 $4。向用户发送一行提醒，包含实际时长和按比例计算的预估费用，例如：“正在进行唇形同步——视频约 7 秒，按 $4/分钟估算，费用约 $0.47（传入 --no-lipsync 可跳过）。现在开始。”如果缺少 duration_seconds，且无法可靠获取媒体时长，请说明费率为 $4/分钟，不要编造费用估算。然后直接开始调用；这只是费用提醒，不需要用户批准。

调用 edit_lipsync(video_url=<dubbed_video_url>)，不要传入 audio_url——工作程序会将唇形同步到配音视频内嵌的翻译音频。不要为了重新传入音频而提取音频。（variant 默认为 v2-pro，并以 sync-3 / v2 作为回退选项。）

输出：lipsynced_video_url（从响应的 url 读取）。运行此步骤时，第 3 步应为此视频添加字幕，而不是 dubbed_video_url，否则会丢失唇形匹配效果。

步骤 3 — 烧录目标语言字幕（状态：final_video_url）

为最终视频添加字幕，使输出视频带有易读的字幕（符合常见的“翻译 + 字幕”需求）。如果运行了 lipsync（默认情况），将 caption_target_video_url 设为 lipsynced_video_url；如果使用 --no-lipsync 跳过了 lipsync，则设为 dubbed_video_url。

如果此请求属于 Double 视频／分屏对比流程，请先构建 Double 视频，并将 caption_target_video_url 设为最终合成视频的 URL。不要在合成 Double 视频之前只为其中一个画面板烧录字幕；应在最终视觉输出上一次性烧录双语字幕。

对 caption_target_video_url 调用一次 add_captions。

当 bilingual_subtitles=true 时，如果两条字幕轨道都可用，请使用手动双语模式：调用 add_captions(video_url=<caption_target_video_url>, caption_mode="manual", subtitles=<dub_subtitles>, secondary_subtitles=<source_subtitles>, language=<target_language>, secondary_language=<source_transcript_language if available>, secondary_subtitles_position="below", style="branded-space-mono", position="bottom")。目标语言（译文）字幕行是主要的 subtitles，显示在上方；源语言（原文）字幕行是次要参考，显示在下方（secondary_subtitles_position="below"）——配音后实际说出的是译文，因此译文应放在上方。只要 dub_video 返回了两条字幕轨道，此方法就适用于所有配音工作器提供方分支。

如果 bilingual_subtitles=true 但缺少 source_subtitles，则回退为仅显示目标语言字幕，并告知用户配音提供方未提供源语言转录。不要通过重新转录最终配音音频来编造源语言字幕行；该音频已经是目标语言。

对于仅显示目标语言字幕的情况，优先使用配音工作器已返回的目标语言字幕：如果 dub_subtitles 非空，则调用 add_captions(video_url=<caption_target_video_url>, caption_mode="manual", subtitles=<dub_subtitles>, language=<target_language>, style="branded-space-mono", position="bottom")。手动模式会跳过重复转录，并保留配音提供方提供的目标语言文本。

如果 dub_subtitles 缺失、为空，或被 add_captions 拒绝，则回退到自动模式：调用 add_captions(video_url=<caption_target_video_url>, caption_mode="auto", language=<target_language>, style="branded-space-mono", position="bottom")。自动模式会重新转录配音音频；仅将其用作回退方案，因为这会耗费额外时间，并可能导致中日韩字符／专有名词偏差。

除非用户要求更醒目的样式（tiktok / hormozi / karaoke），否则使用 style="branded-space-mono"。只有在用户明确要求仅配音且不加字幕时，才跳过此步骤。

输出：final_video_url（从响应的 url 中读取）。

步骤 4 — 返回结果

回复 final_video_url + 译文字幕稿（来自 dub_transcript_srt／配音结果），供用户审核。

提供双语字幕版本。 如果本次运行烧录的是仅含目标语言的字幕（bilingual_subtitles=false），且源语言字幕可用（source_subtitles 非空），请在回复结尾询问用户是否也需要双语字幕版本，例如：“想要原文和译文上下排列的双语版本吗？我可以为你添加。”如果用户同意，请在同一个 caption_target_video_url（添加字幕前的视觉视频）上以双语手动模式重新运行步骤 3——无需重新配音或重新执行 lipsync，只需更改字幕烧录，然后返回新的 final_video_url。如果已烧录双语字幕（bilingual_subtitles=true），或者缺少 source_subtitles，则跳过此询问——没有源语言转录就无法制作双语版本（配音音频已经是目标语言），因此不要提供无法交付的选项。

失败模式

类别	触发条件	缓解措施	后备方案
源 URL 无法由 worker 获取	dub_video 返回 403 / 4xx、因防盗链 / UA 限制导致获取失败，或公开 HTTPS URL 返回“Access Denied”	在客户端 / 宿主环境中下载源文件，将其字节数据通过 upload_asset 上传到 Pika，将 video_url 替换为 Pika CDN URL，然后重试一次步骤 1	如果本地下载也失败，请用户上传文件或提供其他 URL
额外的目标语言	目标语言为粤语（yue / cantonese / zh-HK）、泰语、希伯来语、波斯语、斯洛文尼亚语、加泰罗尼亚语、挪威语（尼诺斯克）或南非语	支持——照常将目标语言传给 dub_video；保留原说话者的声音	这些语言不会保留背景音乐（仅配音语音）
配音调用失败（非获取问题）	dub_video 因其他原因出错——目标语言不受支持、提供方 / worker 返回 5xx，或 task_status 返回 status: failed	向用户说明错误；如果错误信息指向语言问题，请查阅 references/language-coverage.md 并建议使用受支持的标签；否则建议重试。没有可用的手动处理链作为后备——配音是唯一处理路径	无——返回错误，不要默默生成未配音的视频
配音没有语音	视频静音——没有可翻译的内容	向用户说明：“视频中未检测到语音——没有可翻译的内容”	无
无法保留原声音	对于上述语言，源素材过短或噪声过大，无法保留原说话者的声音	说明错误，并请用户提供更清晰 / 更长的源片段	无——配音会失败，而不是改用其他声音
唇形同步源视频过长	配音后的视频时长超过 5 分钟——edit_lipsync 因 invalid_input 拒绝处理（sync.so 的上限为 300 s）；所有变体档位都有相同上限，因此重试无济于事	先检查步骤 1 的 duration_seconds；如果超过 300，则跳过唇形同步，直接为 dubbed_video_url 添加字幕，并告知用户唇形同步的上限为 5 分钟	配音视频，不匹配嘴型
唇形同步步骤失败	edit_lipsync 出错（无法清晰识别人脸轨迹、提供方返回 4xx）	依次尝试各个 variant 档位（v2-pro → sync-3 → v2）；如果全部失败，则返回未匹配嘴型的配音视频，并告知用户	替换了音频的视频，不匹配嘴型
字幕语言错误	步骤 3 的自动转录误判了语言	传入明确的 language 标签；如果存在 dub_subtitles，则改用 caption_mode="manual"，而不是自动模式	手动指定 subtitles[]
无法获取双语源字幕行	用户要求双语字幕，但缺少 source_subtitles	使用目标语言字幕，并说明源转录内容不可用	仅提供目标语言字幕