TokenLab Seedance Materials：用于生产工作流的可复用视频参考

如果您的团队曾经将同一个换脸 URL 粘贴到三个不同的 API 调用中，那么您就已经明白为什么需要 Seedance 素材库了。可复用视频参考作为具有生命周期状态的资产，比作为从电子表格复制到每个生成请求中的一次性 URL 效果更好。TokenLab 将这些资产限定在您的组织内，因此您可以在多次调用中存储、验证和复用这些参考。我们测试了工作流的形态：组（groups）用于组织真人素材，资产（assets）持有实际的参考内容，生成调用仅在状态达到 ACTIVE 后才消耗 ID。例如，一个曾经维护着包含图像链接的电子表格并五次上传同一个参考视频的团队，现在可以用一个素材资产 ID 来替代这种习惯。

关键要点

• 素材资产（material asset）是可直接用于生成的参考对象；素材组（material group）是组织相关资产的容器，特别适用于真人工作流。
• 仅在素材资产的状态达到 ACTIVE 后，才将其 id 用作 material_asset_id（或放入 material_asset_ids 中）。
• 存在两种库类型：用于虚拟化身及其他非真人可复用参考的 aigc_avatar，以及用于需要验证的真人素材组的 liveness_face。
• TokenLab 可以自动将兼容的图像输入（image, image_url, image_urls, reference_images, start_image, end_image）转换为素材资产，无需单独的上传步骤。
• 如果准备过程超过 60 秒，API 将返回 409 seedance_material_preparing 以及您可以轮询并重试的 auto_material_asset_ids。
• Seedance 是该素材系统当前支持的公共模型系列。在构建对特定层级的依赖之前，请务必在文档中核实每个模型的具体能力细节。

Seedance 素材库：资产与组

Seedance 素材是一种可复用的参考（图像、视频或音频），TokenLab 将其存储为组织范围内的资产，而不是请求范围内的 URL。您无需将原始文件链接传入每个 create-video 调用，只需上传或导入一次参考内容，等待其变为可生成状态，然后在随后的任意多次调用中通过 ID 进行引用即可。

这在实际应用中有三个重要原因。首先，重复上传会浪费带宽并增加每个请求的延迟，尤其是对于大型参考视频而言。其次，原始 URL 可能会过期、轮换或被最初托管它们的存储系统撤销。而由 TokenLab 管理的素材资产则没有这种脆弱性。第三，对于构建角色一致或品牌一致的视频流水线的团队来说，素材提供了一个稳定的标识符，您可以对其进行版本控制、审计和替换，而无需每次都修改生成逻辑。

素材资产 vs. 素材组

该系统中的两个核心对象是素材资产和素材资产组。如果您没有仔细阅读 API 参考，很容易混淆它们。

素材资产是单个参考对象——一个化身图像、一个经过活体检测的真人面部、一个参考视频片段。创建它时，API 会返回一个 id。一旦资产达到 ACTIVE 状态，您最终传入视频生成调用的就是这个 id。

素材资产组是一个由 group_id 标识的容器。组将相关资产组织在一起。对于真人（liveness_face）工作流，它们在结构上是必需的，因为在将单个资产上传到组之前，必须在组级别进行验证。

简而言之：group_id 用于组织；material_asset_id 用于生成。您会在 API 的不同部分看到这两个字段。在错误的地方使用错误的字段是团队在使用该系统时最常犯的集成错误。

字段	标识内容	使用场景
group_id	素材资产组（容器）	创建或引用组，特别是在真人验证流程中
id (素材资产)	单个可复用参考	达到 ACTIVE 后成为 material_asset_id
material_asset_id	单个资产参考	传入 create-video 以用于一个参考槽位
material_asset_ids	资产参考数组	当需要多个可复用参考时传入 create-video

完整的字段定义和必需参数记录在 create material asset 和 create material asset group API 参考中。在将其写入生产代码之前，请阅读这些文档。文档涵盖了工作流的形态，而非每个请求参数。

虚拟化身与真人工作流

Seedance 素材支持两种库类型。这种区别并非仅仅是表面上的——它反映了两种不同的安全和授权立场。

aigc_avatar：虚拟化身与非真人参考

aigc_avatar 类型涵盖了不与已验证真人绑定的可复用参考：插画角色、合成化身、风格化人物、品牌吉祥物及类似资产。您可以直接通过素材资产创建流程创建这些内容，无需验证步骤。

如果您的产品围绕虚构角色或品牌化身生成视频，这几乎肯定是您需要的库类型。它的创建路径更简单，因为没有相关的身份验证要求。

liveness_face：真人素材组

liveness_face 类型适用于围绕真人肖像构建的素材组。这是用于生成包含特定个人的面部一致性视频的参考类型。由于这涉及身份和授权，TokenLab 要求在将资产上传到组之前进行验证流程。

验证序列包含几个不同的步骤：

1. 会话创建 — 您的后端为该组请求一个验证会话。
2. H5 流程 — 被验证者通过托管的 Web 流程完成活体检测。H5 指的是移动端 Web 验证界面。
3. 回调 — 当验证会话结束时，TokenLab 会通知您的系统。
4. 绑定结果 — 将已验证的身份绑定到素材组。
5. 组内上传 — 只有在绑定成功后，才能将素材资产上传到该特定组中。

这意味着真人素材本质上是“组优先”的。您不能像使用 aigc_avatar 那样直接跳到创建资产。在将任何资产上传到组之前，该组必须存在并通过验证。

清单：选择正确的库类型

• 参考内容是真实、可识别的人脸或肖像吗？→ 使用 liveness_face 并规划验证流程。
• 参考内容是合成的、插画的或非真人的化身吗？→ 使用 aigc_avatar 并跳过验证。
• 您的产品是否需要在多次生成中保持同一个人的一致身份？→ 构建一次组，验证一次，并在未来复用该组。
• 您不确定客户提供的参考属于哪种类型吗？→ 在确认之前将其视为 liveness_face；请查阅文档，不要臆测。

不要假设每个生成模型或每个请求类型都以相同方式支持这两种库类型。在确定架构之前，请在 Seedance Video Models guide 中确认当前的支持情况。

自动素材准备的工作原理

并非每个参考都需要手动上传步骤。TokenLab 可以自动将兼容的图像输入作为生成请求的一部分准备为素材资产。这减少了简单情况下的往返次数。

它识别的自动准备字段包括：

• image
• image_url
• image_urls
• reference_images
• start_image
• end_image

如果您将其中任何一个直接传入生成调用，TokenLab 会在后台处理导入和准备工作。您无需先单独调用素材资产端点。

准备时间超过 60 秒时会发生什么

准备工作通常很快。较大或较复杂的参考图像可能需要更长时间才能处理为可生成的资产。如果准备时间超过 60 秒，API 将返回：

409 seedance_material_preparing

以及包含仍在准备中的资产 ID 的 auto_material_asset_ids 字段。

这在传统意义上不是错误。这是一个重试信号。您的集成应将 409 seedance_material_preparing 视为“稍后查询”的响应，而不是向最终用户报告的失败。轮询返回的资产 ID，等待 ACTIVE 状态，然后使用这些 ID 继续生成。

在我们的流水线中，我们将此状态视为速率限制退避：它是预期的、暂时的，应在代码中处理，而不是作为用户可见的错误报告。我们建议使用小的重试循环，而不仅仅是简单的 try/catch。

在生成中使用 Seedance 素材库

一旦素材资产（无论是手动上传还是自动准备）达到 ACTIVE 状态，其 id 即可在 create video 调用中用作 material_asset_id 或作为 material_asset_ids 中的条目。

核心工作流如下：

1. 决定参考内容是否为真人。相应地选择 liveness_face（需验证）或 aigc_avatar。
2. 如果是真人：创建素材组，运行验证会话和 H5 流程，接收回调，并绑定结果。
3. 创建或导入素材资产——通过直接上传调用，或让自动准备处理生成请求中的兼容图像字段。
4. 检查状态。在资产报告 ACTIVE 之前，不要将其 ID 传入生成调用。
5. 如果收到 409 seedance_material_preparing，轮询返回的 auto_material_asset_ids，并在它们变为 ACTIVE 后重试。
6. 在您的 create-video 调用中将 id 用作 material_asset_id 或放入 material_asset_ids 中，根据您的延迟和质量需求针对当前的 Seedance 模型进行调用。
7. 在未来的生成调用中复用相同的资产 ID，而不是重新上传参考内容。

这也是任务管理发挥作用的地方。基于复用素材资产的生成调用可能需要在运行中途停止。这可能是出于成本控制、创意简报变更或提示词不佳的原因。请参阅我们关于 Seedance task cancellation 的配套文章，了解取消操作如何与运行中的视频作业交互。

有关 TokenLab 上当前可用的视频生成模型的更广泛比较，请参阅 video models category page，其中列出了当前的选项。

实际后续步骤

• 如果您正在进行原型设计，请从 aigc_avatar 素材开始。创建路径更简单，且没有需要首先构建的验证依赖。
• 如果您的产品需要真人一致性，请将验证流程（会话 → H5 → 回调 → 绑定）构建为入职流程的一等公民，而不是附加组件。
• 在向生产环境发布任何内容之前，请为 409 seedance_material_preparing 添加重试循环。将其视为预期行为，而非边缘情况。
• 将素材资产 ID 与您自己的内部参考记录一起存储。这样您就不会重新推导哪个资产映射到哪个角色或产品。
• 直接查阅 material asset 和 material asset group API 参考。文档描述了工作流的形态，在编写集成代码之前，应根据当前文档确认确切的请求/响应字段。

Seedance assets dashboard 显示了您已创建资产的状态、库类型和组关系。

我们 AI video API pricing 2026 概览中的当前费率有助于您了解成本如何随使用量扩展。您还可以使用 TokenLab dashboard usage exports 中的指南来跟踪和导出您自己的使用数据。

常见问题解答

素材资产和素材组有何不同？

素材资产是单个可复用参考对象——一个化身图像、一个经过活体检测的真人面部、一个参考视频片段。一旦 ACTIVE，其 id 即可成为 material_asset_id。素材组是一个由 group_id 标识的容器。组用于组织相关资产，且对于 liveness_face 工作流是必需的。简而言之：group_id 用于组织；material_asset_id 用于生成。

为什么生成调用会返回 409 seedance_material_preparing？

由兼容图像字段（如 image_url 或 start_image）触发的自动素材准备可能需要超过 60 秒的时间。发生这种情况时，API 会返回 409 seedance_material_preparing 以及 auto_material_asset_ids。轮询这些 ID，等待 ACTIVE，然后重试生成。这标志着一个暂时的进行中状态，而非失败。

真人参考是否总是需要验证？

是的。每当参考内容涉及实际可识别的人脸或肖像时，请使用 liveness_face 类型及其验证流程。该流程要求在将任何资产上传到该组之前，先进行会话创建、H5 活体检测、回调和绑定步骤。非真人参考（如插画或合成化身）使用 aigc_avatar，不需要此路径。

我可以在多个 Seedance 视频作业中复用同一个素材资产吗？

可以，一旦资产达到 ACTIVE 状态。在 create-video 调用中将其 id 用作 material_asset_id 或放入 material_asset_ids 中。在未来的生成调用中复用相同的资产 ID，而不是重新上传参考内容。如果您需要停止运行中的作业，请参阅 Seedance task cancellation。

来源与时效性

• Seedance Video Models guide — https://docs.tokenlab.sh/guides/seedance-2-video — 观测日期 2026-07-09
• Create Seedance material asset (API reference) — https://docs.tokenlab.sh/api-reference/video/create-material-asset — 观测日期 2026-07-09
• Create Seedance material asset group (API reference) — https://docs.tokenlab.sh/api-reference/video/create-material-asset-group — 观测日期 2026-07-09
• Create video (API reference) — https://docs.tokenlab.sh/api-reference/video/create-video — 观测日期 2026-07-09
• TokenLab Seedance assets dashboard — /dashboard/seedance-assets — 观测日期 2026-07-09

此处描述的 API 行为、字段名称和状态语义反映了截至观测日期的公共文档和仪表板文案。TokenLab 的 Seedance 素材系统正处于积极开发中——在最终确定生产集成代码之前，请在链接的文档中确认当前的参数名称、状态值和特定模型支持情况。

如果您正在构建依赖于稳定、可复用参考的视频流水线，请从 Seedance Video Models guide 开始。这是查看当前参数名称并确认您的目标模型层级实际支持哪些功能的最佳方式。