scenario-video-to-motion

场景视频转动作

概述

视频转动作成员会观察片段中的人物，并返回 3D 动画：可以是自动绑定骨骼并动起来的角色网格，也可以是仅包含动作的标准骨架动画。它们属于 video23d 能力，但实际差异远大于名称上的相似：所需的角色输入、返回的骨架，以及生成的文件格式都不相同。

相关技能：scenario（连接、范围、上传、jobs_wait）、scenario-3d（先制作或绑定网格）、scenario-video（没有素材时生成参考表演），以及 scenario-video-editing（裁剪和调整片段大小）。如果下文提到的相关技能不在可用技能中，请让用户安装 （npx skills add scenario-labs/skills --skill <name>）；若无人值守，请根据工具架构继续操作，并标明缺少的技能。

快速参考

步骤	调用	注意事项
上传输入	使用 upload_asset，先设 kind: "video"，再为网格设 kind: "3d"	所有成员的网格输入都是可选的
调整片段	使用 asset_get，然后按照 scenario-video-editing 裁剪或调整大小	各成员对时长、大小和偶数尺寸有不同限制
选择成员	使用 recommend，设 capability: "video23d"，并输入用户自己的描述	根据 scenario 技能读取 next_step
读取输入要求	使用 model_schema_get	查看每个文件字段的 kind 和输出枚举值
先估价，再运行	使用 model_run，设 dry_run: true，然后设 wait: false	video 字段会影响 cost_impact
等待并检查	使用 jobs_wait，然后使用 asset_display	检查朝向、脚部接触情况和帧数

先选择输出，再选择成员

有三种输出结果，而不同成员支持的结果各不相同。请先与用户确认（无人值守时：如果项目依赖角色现有的绑定骨骼，就只生成动作；否则为网格制作动画）。

• 用户的角色，带动画。 某个成员接收网格，自动绑定骨骼并应用动作。骨架由该成员生成：它不会将动画重定向到网格已有的骨架，因此，为现有骨架制作的片段需要重新映射骨骼。
• 仅动作，使用指定骨架。 某个成员无需上传角色，即可返回基于 Mixamo 风格或 MetaHuman 骨架的动画。角色已有绑定骨骼时，选择此项。文件可能包含模板网格：先检查，然后在将动画重定向到用户的骨架时省略该网格。
• 仅动作，使用网格成员。 部分网格成员也提供仅生成动画的选项，可在下载时移除网格。

recommend 会根据实测成本和延迟为成员排序，并指出哪些成员需要角色输入。调用时应使用用户自己的描述，包括上述输出结果，而不要只提供能力名称。

逐字段阅读架构

不同成员中的字段名称可能重复，但含义不同，因此填写前请先查看每个字段的 kind：

• 某个成员的 characterFile 接受 3D 网格；另一个成员的 characterFile 接受角色参考图像，而其网格字段为 characterModel。决定字段接受哪种资产的是字段的 kind（3d 或 image），而不是字段名称。
• 输出格式各不相同：某个成员会写入特定引擎的 FBX 变体（fbx-blender、fbx-unreal、fbx-roblox、Maya 场景文件）；另一个成员会输出普通的 glb 或 fbx（其架构将 Unity 的格式命名为 fbx）；还有一个成员完全不提供格式字段。请在运行时选择目标引擎：文档并未说明 asset_download 的 format 转换会保留动画。
• FBX 导出文件可能是 ASCII 格式。Blender 的旧版 FBX 导入器不支持这种格式；请使用支持 ASCII 的新版导入器。确认导入后的动画无误，再称该文件已适用于 Blender。
• 如果存在，值得设置的控制项包括：用于由代码驱动游戏角色移动的 moveInPlace、用于循环播放的 loop、帧速率字段（名称为 frameRate、fps 或 targetFps）、关键帧清理，以及当动作导入后方向错误或角色倒地时使用的 forward 和 up 轴。
• 某些成员会追踪多个人物（numPeople）或捕捉面部；这两项都会产生 cost_impact。

拍摄效果良好的素材

• 画面中始终只有一个人，且全身入镜、双脚可见；使用固定摄像机，前方无人经过。宽松的衣物和道具会遮挡关节。
• 剪辑出最终要用的动作：价格取决于片段时长，而且各成员对输入都有上限。在编写时，其中一个成员将上限设为 30 秒左右、约 30 MB；另一个成员则要求宽度和高度均为偶数。若架构中提供了 max_duration 和 max_size，请查看这两个字段。未设置上限不代表可以无限输入。若片段超出上限，请先使用视频编辑工具处理，再估算价格。
• 没有素材？请按照 scenario-video 的说明，使用视频模型生成表演：单个全身角色置于纯色背景，摄像机固定，并逐个节拍描述动作。生成的片段随后可像其他素材一样作为输入。
• 动作提取针对人类动作。生物角色或非双足网格需要逐帧检查，而且通常还需要经过 DCC 流程处理。

示例：为游戏角色处理舞蹈片段

用户有一段手机拍摄的舞蹈片段和一个角色 GLB，希望制作适用于 Unreal 的循环动画。

1. 按照 scenario 技能，使用 upload_asset 上传片段（kind: "video"）和 GLB（kind: "3d"）。
2. 对片段调用 asset_get：查看时长和尺寸。使用视频剪辑工具裁出能循环播放的 8 秒片段；如果候选成员有要求，再将尺寸调整为偶数。
3. 使用 capability: "video23d" 调用 recommend，提示词可写成：“将这段视频中的舞蹈应用到我上传的角色网格，设置为循环播放，并导出为 Unreal 格式。”按照 scenario 技能处理 next_step：展示 ask_user 选项；用户选择 proceed 后，直接使用其选择，无需再次询问。
4. 对选定项调用 model_schema_get。将 GLB 放入 kind 为 3d 的字段。如果格式枚举中有 Unreal 输出目标，就设置该目标；设置 loop: true，并在游戏代码自行驱动角色移动时设置 moveInPlace: true。
5. 使用 dry_run: true 调用 model_run 并告知价格。然后使用 wait: false 运行：这些任务需要几分钟。使用 jobs_wait 等待任务完成；若超时，则通过 pending_job_ids 再次调用。
6. 使用 asset_display 查看结果，或在 DCC 中打开。检查角色朝向、双脚是否着地，以及循环衔接处是否突兀。如果朝向不正确，且架构提供了 forward 和 up，请先检查这两个字段，再判断是否为素材拍摄问题。仅有预览链接不算完成视觉检查。
7. 调用 asset_download，不传入 format，并将文件连同其使用的骨架一并交付。

常见错误

• 期待动作应用到角色现有的绑定上：网格成员会从头自动绑定。必须保留原有绑定时，请使用仅包含动作的成员并进行重定向。
• 仅凭字段名称填写字段：characterFile 在一个成员中表示网格，在另一个成员中表示图像。
• 发送完整的源视频：费用会随视频时长增加，超过上限的视频会失败。
• 将下载内容转换为其他 3D 格式，而不是在运行时设置导出目标。
• 在尝试轴向字段之前，就把侧向或倒置的结果视为捕获失败。
• 使用 job_get 轮询，而不是使用 jobs_wait；或仅因超时就重新运行任务。