加字幕｜美图开拍出品

概述

加字幕｜美图出品

能力与准备

使用 subtitle 为视频制作动态字幕或更新字幕样式，提升信息传达与观看体验，输出新视频并保留原素材。依赖 meitu-kaipai-cli，已验证目标版本 0.1.14，兼容 >=0.1.11 <0.2.0。

首次执行先按[平台接入](references/platform.md)运行[CLI 准备脚本](scripts/ensure-cli.mjs)：缺失时默认全局安装，兼容时复用。目标、必要素材和授权齐全后沿用返回入口直接调用 CLI，不主动校验输入或运行独立预检；调用格式不明确时再按平台说明查询 help／contracts。遇到 CLI 输入错误、输出解析、服务端问询或执行异常时读取[运行与恢复](references/runtime.md)。

• 直接提交用户选定的视频制作字幕，是否存在可用语音或字幕时间轴由服务判断；收到缺少字幕来源的实际反馈后再请求补充。
• 字幕素材 ID（样式 ID）可选，可不指定或留空；未提供、为 null、空字符串或仅含空白时，告知采用随机样式并省略 --subtitle-material-id（参数文件中也省略 subtitleMaterialId），不要求用户补填、不阻塞任务。仅在用户提供或已有配置中包含非空真实样式 ID 时传入，与会话媒体 ID 分开记录。
• 用户提出字幕文字、翻译、重点词或位置等编辑要求时，先核对当前命令和可用样式，按平台说明承接具体需求。画面中原有字幕的消除使用视频去字幕能力，与动态字幕制作按用户目标衔接。
• 明确的加字幕请求直接执行；“增强表达”等目标不明的请求只补问处理方式。混剪或原字幕清理按用户实际需要安排。

收集输入

1. 使用当前请求中的真实视频文件或 URL；信息齐全时不重复询问。多个候选且目标不明时请用户选择，不自动代选。
2. 本地视频使用用户提供或上下文取得的真实路径；所有远程视频先按[平台接入](references/platform.md)下载原资源，再作为本地文件上传。下载失败时请用户自行下载并提供本地原文件，收到后继续原字幕需求。
3. 继续任务时添加 -r '<session_id>'，新任务省略。可选 --lang / --detach / --subtitle-material-id 按当前 help 传入，未指定时省略；默认值及登录按平台说明处理。
4. 接续混剪时保留原会话，取得本次 Artifact 或 Message Part 的完整视频 URL，先下载再上传至自有 CDN。缺少、过期或只有媒体 ID 时先查询 Task／历史。保存原始来源与实际本地路径，不先 create-room / add-media，不使用 --item-id。

上传与提交

使用已解析的 CLI 入口，将准备好的本地视频作为独立参数传入：

kaipai subtitle --video-file '<本地视频路径>'

CLI 校验本地视频后，先上传取得自有 CDN URL，再提交字幕任务并默认等待本次执行结束。复杂输入按需使用参数文件；收到 CLI 输入错误后再针对性处理；原始视频与会话保留用于恢复，安全传参与临时文件清理见平台说明。

跟进与交付

• 保存真实 session_id / room_url、全部 Task ID、产物 viva.short_id 和完整 URL；分别读取原命令 stdout 与 stderr，不同时另开轮询。
• TASK_STATE_COMPLETED 且取得本次可用视频 URL 才交付成片。HTTP 200、流结束、退出码 0、Session idle 或 end.reason=result 都不单独证明完成；未知状态不能视为成功。
• 优先提供可播放视频或完整可点击链接，保留查询参数；有实际 room_url 时追加会话入口。不把封面或输入视频当成字幕结果。
• 断线、超时或受理未知时先查询原任务，不自动重新生成。仅在失败原因已修复且用户授权后重试；字幕失败时交付已成功的混剪视频并说明字幕未完成，输出产物下载失败只处理下载。详细恢复与保存方式见运行说明。