在 HiAPI API 上使用 vidu-q4-preview 的参考生视频短视频工作流

为什么参考生视频改变了短视频工作流

仅靠提示词的生成要求模型自行创造一切：主体外观、服装、构图、动作和音频。对于一次性实验，这没问题。对于短视频制作——同一个角色或主播必须在几十个片段中出现——仅靠提示词的控制很快就会失效。措辞上的微小变化会产生巨大的视觉漂移，再多的提示词工程也无法可靠地固定一张脸、一套服装或一个声音。

参考生视频改变了这一约定。你不再用文字描述主体，而是交给模型一组参考素材——多张确立身份的图像，再加一个确立主体声音的语音参考——并让提示词描述应该发生什么，而不是里面是谁。创作控制从 token 级别的措辞转向素材级别的策划，素材准备成为工作流中的第一个工程步骤，而不是事后的补充。

这一转变与短视频内容的实际制作方式完美契合：

• 可复用的身份。一套经过审核的参考集可以在多个片段中复用，因此一个系列无需重新提示即可保持视觉一致。
• 关注点分离。编剧在提示词中负责动作和节奏；素材负责人负责参考集中的外观和声音。
• 可审查的输入。当输出看起来不对时，你可以对比不同运行之间的参考集，而不是猜测哪个形容词改变了结果。

短视频还提高了失败成本的门槛。片段分发成本低，重拍成本高，因此一个能从固定参考库产生可预测变化的流水线，比一个偶尔产生出色一次性成果的流水线更有价值。参考生视频正是使这种可预测性成为可能的机制。

保持不变的部分

你仍然需要编写提示词，仍然提交异步风格的请求，仍然对返回的视频进行后处理。不同之处在于，参考素材成为一等输入，你需要像提示词一样对它们进行版本管理、验证和存储。

vidu-q4-preview 参考模型如何融入 HiAPI

在 HiAPI 上，vidu-q4-preview/reference-to-video 作为模型标识符，在你用于其他生成任务的同一请求接口中寻址。你无需对接单独的供应商 SDK，也无需管理第二套凭证。你的应用调用 HiAPI API，平台将请求路由到参考生视频模型，响应带回生成的视频素材。

这种分层在两个方面具有实际意义：

1. 单一集成接口。身份验证、请求结构和错误处理在你使用的模型之间保持一致，因此添加或更换模型是配置变更，而不是新的客户端。
2. 统一运维工具。日志记录、重试、速率处理和响应解析集中在一处，避免参考生视频路径变成平行的代码库。

此端点的用途

参考生视频模型适用于主体身份必须由提供的素材锚定、而非从文本中虚构的片段——短促销片段、固定主播段落、有一致模特的产品镜头，以及类似的需要系列一致性的内容。它不是通用视频编辑器；它根据你的参考和提示词生成新片段。

将模型标识符视为配置

模型标识符及其支持的参数会随着模型的添加、预览和退役而随时间变化。不要将 vidu-q4-preview/reference-to-video 硬编码到十几个地方的业务逻辑中。将其保留在一个配置层中，并在发布前对照 HiAPI 的公开文档核实当前的标识符、支持的参数和预期输入形状。本指南中关于请求结构的任何内容都是形状的概述；文档才是精确字段名的权威来源。

本指南不涵盖的内容

定价有意不在范围内。HiAPI 上的计费根据你提交的模型和参数按任务计量，实时数字属于平台的价格面板，而不是会过时的教程。任何关于单个模型延迟或吞吐量的声明同样如此——在你自己的工作负载上测量它们，而不是相信从博客文章复制来的数字。

准备多图和语音参考

参考质量主导输出质量。为素材准备分配真正的工程时间，因为模型的一致性只能与您提供的参考一样好。

选择多图参考

使用多张描绘同一主体在不同但兼容条件下的图像——不同角度、略微不同的光照、特写和中景的混合。目标是给模型足够的覆盖范围，以便从多个视角解析身份而不引入矛盾。

实用的选择规则：

• 同一主体，同一时期。避免混合在发型、胡须或造型上不同的外观参考，除非你希望模型取平均。
• 一致的色彩处理。参考之间白平衡或调色差异过大会将模型推向不稳定的调色板。
• 没有竞争主体。包含两张突出面孔的参考集容易引发混合。每组一个主体。
• 足够的分辨率。缩小或严重压缩的参考会丢失模型所需的精确细节。

准备语音参考

语音参考确立音色和表达方式。提供干净的音频——低本底噪声、无背景音乐、无重叠说话者。修剪到最能代表预期表达方式的片段，并保持足够短以具有代表性，而不是完整的独白。如果你计划用同一声音制作系列，锁定一个语音参考并复用它。

规范化素材

在任何内容到达请求构建器之前，让每个素材经过规范化步骤：一组内一致的图像格式和尺寸，一致的音频格式和采样率。规范化消除了一整类“昨天还能用”的故障，并使缓存键有意义。

版本化参考集

将参考集视为带有标识符的工件：

refsets/
  presenter-a/
    v1/  images/  voice.wav  manifest.json
    v2/  images/  voice.wav  manifest.json

清单应记录素材来源、应用了何种规范化以及每个文件的哈希值。当输出发生漂移时，你可以立即判断参考集是否发生了变化。当它发生漂移而参考集未变时，你知道应该检查提示词或模型版本。保持参考集小——少量精心挑选的图像胜过大量不一致的堆砌——并保持版本化，因为可复现性才是关键。

在代码库中组装请求

参考生视频调用的请求有三个概念部分：模型选择、描述动作的提示词，以及包含多图和语音素材的参考负载。将每个部分保持在各自的层中，这样更改一个不会迫使你触碰其他部分。

可行的结构

config/          模型 id、端点、默认参数
refsets/         版本化的参考素材 + 清单
builder/         将提示词 + 参考集 + 参数组装成请求
client/          HiAPI 调用、重试、错误映射
handler/         验证并存储返回的视频

这种形式的请求构建器大致执行以下操作：

1. 从配置中加载模型标识符（例如 vidu-q4-preview/reference-to-video），绝不从调用方中埋藏的字面量加载。
2. 从清单中按版本加载参考集，以便使用的确切素材随运行一起记录。
3. 附加描述场景、动作和节奏的提示词文本。
4. 将默认参数与任何每次运行的覆盖合并。
5. 生成一个请求对象，由客户端层提交给 HiAPI API。

保持接缝干净

构建器是唯一知道请求形状的地方。如果字段名发生变化，或者参考生视频模型添加了参数，更改落在构建器中，而不是其他地方。提示词文本应该是一个带有可变内容槽位（产品名称、场景节拍、行动号召）的模板，而不是散落在调用代码中的字符串拼接。

发送前验证

在构建器中快速失败：断言参考集可解析、存在预期数量的图像、音频非空、提示词在限制范围内。本地拒绝的格式错误请求只需毫秒；同样的请求被远程拒绝则需一次往返，并且取决于你如何计量，还可能产生失败任务。

记录来源

为每个提交的作业记录模型标识符、参考集版本、提示词模板版本以及任何参数覆盖。那一行日志是将“输出变差了”转变为可回答问题的关键。在接入时对照 HiAPI 的公开文档核实当前标识符和参数名，并在升级模型时重新检查。

处理响应和短视频后处理

返回的素材是起点，不是最终交付物。短视频平台施加自己的宽高比、时长、响度规范和字幕惯例，返回的视频及其原生音频需要被塑造成符合它们。

先存储，后转换

在触碰返回的原始视频之前，将其写入持久存储。转换是有损的，偶尔有缺陷；如果唯一的副本是被裁剪的那份，糟糕的裁剪意味着重新生成。用作业 id 加参考集版本作为存储对象的键，以便你可以将任何已发布的片段追溯到其输入。

后处理链

典型的短视频链如下所示：

• 检查。从返回的素材读取时长、尺寸、帧率和音频响度，并记录在你的作业元数据中。
• 修剪。剪切到目标时长，有意选择入点/出点，而不是在固定偏移处切割——生成往往在开头留下一拍的不稳定。
• 重新构图。缩放和裁剪到平台的宽高比。如果主体偏离中心，使用主体感知的裁剪而不是盲目居中切割。
• 音频规范化。对原生音轨应用响度规范化，并验证语音参考按预期贯穿。
• 字幕和品牌。将烧录字幕或叠加层作为单独步骤添加，这样它们可以在不重新编码基础视频的情况下更改。
• 编码。为每个目标平台生成最终配置文件，保留中间母版。

显式处理音频

如果模型返回原生音频，将音轨视为独立工件。提取它、测量它、规范化它，然后重新封装。这样可以修复安静的轨道而无需重新运行生成，并使同步问题尽早可见。

验证失败时大声报错

处理后，运行自动检查：时长在范围内、宽高比正确、音频存在且高于响度下限、开头没有黑帧。任何失败的内容进入审查队列而不是分发。短视频的量级使得对每个片段进行人工审查不可能，因此验证关口是防止不良输出上线的关键。

成本、延迟和故障模式检查清单

生成按任务计量并消耗真实时间，因此运维问题与任何昂贵的异步作业相同：如何避免浪费运行，以及如何诊断失败的运行？在排查失败的参考生视频运行时，使用下面的检查清单。

输入原因

• 参考集是否可解析，是否是你想要的版本？
• 图像在主体、造型和色彩处理上是否一致？
• 语音参考是否干净、无音乐和重叠语音、非空？
• 尺寸、格式和采样率是否在文档限制范围内？

请求原因

• 模型标识符是否与文档完全一致地拼写，是否仍然有效？
• 参数名和值类型对此模型是否有效？
• 提示词是否在长度限制内，是否描述动作而不是重新描述参考已覆盖的身份？
• 你是否超出了自己客户端层施加的任何并发或速率限制？

响应原因

• 请求是否成功但返回了未通过验证关口的素材？先检查修剪和片段开头稳定性；更长的生成窗口通常能修复从动作中途开始的片段。
• 输出相对于参考是否偏离模型？这几乎总是参考一致性问题，而不是提示词问题。
• 你是否看到零星的超时？添加幂等作业跟踪，以便重试不会变成重复计费。

成本和延迟卫生

• 不要盲目重试。仅在传输错误或明确可重试状态时重试。内容失败会再次失败。
• 本地验证输入。每个本地捕获的错误都是你未付费的一次运行。
• 自己测量延迟。在你自己的工作负载上按模型和参数配置记录提交到就绪的时间，而不是假设一个数字。
• 积极缓存。经过审核的输出可以服务许多下游变体；仅在参考或场景实际变化时重新生成基础。
• 限制影响范围。批处理作业应设有最大失败阈值，在系统性故障时停止队列。

将此列表放在日志旁边。大多数失败的运行会在一分钟内归入上述三个分支之一。

将其整合为可重复的流水线

最后一步是将工作流转变为循环，按需从模板和参考库生成短视频片段，每个经过审查的输出反馈回库中。

循环

流水线有四个重复运行的阶段：

1. 模板 + 参考选择。模板保存提示词骨架、参数默认值和后处理配置。参考库保存版本化的素材集。作业将两者各配一个。
2. 生成。请求构建器组装调用，客户端提交它，返回的素材带着来源元数据落入存储。
3. 审查和后处理。片段自动通过验证关口；任何被标记的进入人工审查。批准的片段继续经过修剪、重新构图、音频规范化和编码。
4. 反馈。审查中的结构化笔记——“声音漂移”、“光照不一致”——成为参考库或模板的更改，而不是临时提示词编辑。提升版本号以便更改可追溯。

使其可重复的原因

• 模板优于提示词。任何在作业间重复的内容属于模板，而不是每次运行的代码。
• 版本化一切。参考集、模板、模型标识符、后处理配置。作业日志应让你能精确重建运行了什么。
• 确定性打包。从数据构建队列——场景电子表格、内容日历——让流水线将其扩展为作业。
• 将审查作为数据。将审查结果捕获在结构化存储中，以便你可以衡量哪些模板和参考集产生最多批准的片段。

从哪里开始

从一个模板和一个参考集开始，运行一小批，在扩展之前调整参考集。流水线的价值来自参考库随时间的复利：每个批准的片段验证其背后的素材，每个被拒绝的片段精确指出需要修复什么。

当你准备好接入时，在 HiAPI 关于 vidu-q4-preview/reference-to-video 的文档中检查当前模型标识符和请求形状，并将模型选择保留在配置中，以便流水线其余部分在下一个模型发布后仍能存活。