SKILL REVIEW · voiceover-digital-human-combo

数字人口播成片：从用户一句话到最终视频

这张图只讲 skill 应该怎么带用户走。核心不是让用户填字段，而是先补齐素材，再提交异步成片任务。

默认不是一轮完成

缺主播图或时间轴时，先准备素材。

不能编 JSON 路径

必须用真实 Mai file_id。

默认保留原视频声音

口播在上，BGM/SFX 在下面。

ONE SCREEN STORY

一句话流程

用户可以一次给齐，也可以只给一部分。 Skill 要做的是把缺的东西补齐，再开始真正的生成。

用户说要成片

可能只有视频、普通文案、voice_id，也可能素材全齐。

→

先补素材

缺时间轴就生成文案。缺主播图就准备主播图。

→

提交 Tobatsu

只在四件东西都齐了以后提交组合任务。

异步生成

口播、数字人、画中画/分屏、字幕一起跑。

→

回写 5 个文件

最终成片、数字人口播原片、口播音频、字幕、主播图。

→

告诉用户结果

用人话说，不把内部字段甩给用户。

INPUT DECISIONS

提交前先问四件事

这四件没齐，不应该开始 Tobatsu 组合任务。缺什么就补什么，别让用户硬填字段。

视频主视频必须是 Mai file_id，例如 KiwELW.mp4。

文案必须是时间轴 JSON file_id，例如 23LZ8I.json。

声音必须有 ElevenLabs voice_id。

主播图 必须先准备好最终可用的 16:9 主播图。

MAIN DECISION MAP

主决策图

左边是用户可能给的东西。右边是 skill 应该做的动作。

用户这次给了什么

输入侧

有没有主视频？

有：继续检查文案。

没有：请用户上传。

有没有时间轴 JSON？

有真实 file_id：继续。

只有普通文案：先生成。

像 artifacts/*.json：拒绝。

没有文案：问用户想讲什么。

有没有 voice_id？

有：继续。

没有：让用户选声音。

有没有主播图？

有合格图片：直接用。

有真人视频：抽帧后生成。

什么都没有：Mai 生成。

图片不合格：先清理或重做。

skill 应该怎么做

动作侧

视频缺失

停下来问用户要视频。不要猜。

文案缺失

调 generate_voiceover_script。拿返回的 script_id。

声音缺失

问用户用哪个 voice。不要自己填一个不存在的 ID。

主播图缺失

先生成或清理主播图。拿到 file_id 后再提交。

ANCHOR IMAGE

主播图有三条路

这个地方最容易被写成一轮游。正确做法是先把主播图做出来，再跑最终视频。

用户给的情况	skill 应该做什么	提交给 Tobatsu 的状态
给了可用主播图	检查是否单人、脸清楚、无水印、适合口播。	`anchor_image_mode="provided"`
给了真人视频	抽几帧，选一个主体，再生成干净 16:9 主播图。	`anchor_image_mode="extract_from_video"`
没给人像	根据视频、文案和 voice 生成一张主播形象图。	`anchor_image_mode="mai_generated"`

这里不要求画布只剩最终成片。抽帧图、主播图、最终成片都可以在画布上出现。重点是用户能分清哪个是中间素材，哪个是最终成片。

TIMELINE SCRIPT

文案不是随便写个 JSON 文件

这是这次 404 的根因。 skill 需要明确告诉 agent：只能用真实 Mai file_id。

正确

调用 generate_voiceover_script，使用返回的 23LZ8I.json。

错误

自己写 artifacts/timeline_script.json，再当作 file_id 提交。

正确

用户只给普通文案时，先生成时间轴文案。

错误

把普通文案直接塞进 V1 组合任务。

如果没有 timeline_script_id：
  先调用 generate_voiceover_script
  输入：source_video_id + 用户想讲什么 + 语言/风格
  输出：真实 script_id，例如 23LZ8I.json

如果 timeline_script_id 看起来像路径：
  artifacts/timeline_script.json
  ./script.json
  folder/name.json
  直接拒绝，不提交 Tobatsu

SUBMIT PAYLOAD

四件素材齐了，才提交

用户不用看到这些字段。这是内部提交时要满足的形状。

{
  "task_type": "voiceover_digital_human_pip_subtitle_mai",
  "payload": {
    "source_video_id": "KiwELW.mp4",
    "timeline_script_id": "23LZ8I.json",
    "voice_id": "EkK5I93UQWFDigLMpZcX",
    "anchor_image_id": "yeMFrT.png",
    "anchor_image_mode": "extract_from_video",
    "pip": {
      "layout": "overlay",
      "overlay_position": "tr",
      "overlay_shape": "circle"
    },
    "subtitle": {
      "enabled": true,
      "stage": "final_after_pip"
    },
    "audio_mix": {
      "source_audio_policy": "preserve",
      "source_audio_volume": 0.18,
      "voiceover_volume": 1.0
    }
  }
}

用户明确说不要原声时，才把 source_audio_policy 改成 mute。默认应该保留玩法视频的 BGM/SFX。

RESULTS

完成后应该怎么告诉用户

结果要讲人话，也要让用户拿得到所有文件。不要只给一个最终视频。

内部角色	对用户说	是否出现在画布/结果里
`out_primary`	最终成片	是，必须能识别它是最终结果。
`out_digital_human`	数字人口播原片	是，作为可复用中间文件。
`out_audio`	口播音频	是，用户可下载。
`out_subtitle`	字幕文件	是，用户可下载。
`out_anchor_image`	主播形象图	是，尤其是 Mai 生成或抽帧生成的图。

RED LINES

这几件事不要做

这块是给你核对 skill 有没有写偏。如果 skill 里还有这些倾向，就应该改。

不要一轮硬提交

缺主播图或时间轴时，先补素材。不要把不完整请求丢给 Tobatsu。

不要编 file_id

artifacts/*.json 不是 Mai file_id。看到路径就停。

不要默认静音原视频

除非用户明确要求，否则保留玩法 BGM/SFX。

不要只验有音轨

要确认最终成片里有生成的口播。

不要隐藏中间产物

口播音频、字幕、主播图、数字人原片都要能拿到。

不要跟用户说字段名

正常对话说最终成片、主播图、口播音频，不说 out_primary。

REVIEW NOTES

我建议你重点看这 6 点

如果这 6 点符合你的预期，skill 的大方向就是对的。

缺文案时先生成

使用 generate_voiceover_script，不是手写本地 JSON。

缺主播图时先准备

不要把缺 anchor 的任务直接提交。

真人视频要抽帧

先选人物，再生成干净 16:9 主播图。

默认保留原声

配音不能把玩法 BGM/SFX 整条替换掉。

结果返回 5 类文件

最终成片之外，中间产物也要可见可取。

正常说人话

用户不查问题时，不暴露内部字段。