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

当可重用视频参考资源作为具有生命周期状态的资产进行管理，而非作为复制到每个生成请求中的一次性 URL 时，它们会更容易管理。如果您曾经维护过包含图像链接的电子表格，多次重新上传同一个参考视频，或者在三个不同的 API 调用中重复输入同一个换脸 URL，那么您就已经理解了 Seedance materials 所要解决的问题。

TokenLab 的 Seedance material 库为视频团队提供了一种组织范围内的存储、验证和跨生成调用重用参考资源的方法。本文将解释什么是 material 资产，material 组如何与单个资产关联，自动准备功能的工作原理，以及真人验证在工作流中的位置。

关键要点

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

什么是 Seedance Material

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

这在实际应用中有三个重要原因。

首先，重复上传会浪费带宽并增加每个请求的延迟，尤其是对于大型参考视频而言。

其次，原始 URL 会过期、被轮换或被最初托管它们的存储系统撤销。由 TokenLab 管理的 material 资产不存在这种脆弱性。

第三，对于构建角色一致或品牌一致的视频流水线的团队来说，最相关的是，material 为您提供了一个稳定的标识符，您可以对其进行版本控制、审计和替换，而无需每次都触及您的生成逻辑。

Material 资产与 Material 组

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

material 资产是单个参考对象——一个化身图像、一张经过活体检测的脸、一个参考视频片段。当您创建它时，API 会返回一个 id。一旦资产达到 ACTIVE 状态，该 id 就是您最终传递给视频生成调用的内容。

material 资产组是一个由 group_id 标识的容器。组将相关资产组织在一起，它们在真人（liveness_face）工作流中是结构上必需的，在这种工作流中，验证是在组级别进行的，然后才能将单个资产上传到其中。

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

字段	标识内容	使用位置
group_id	material 资产组（容器）	创建或引用组，特别是用于真人验证流程
id (在 material 资产上)	单个可重用参考资源	一旦 ACTIVE 即成为 material_asset_id
material_asset_id	单个资产引用（单数）	传递给 create-video 用于一个参考槽位
material_asset_ids	资产引用数组	当需要多个可重用参考资源时传递给 create-video

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

虚拟化身与真人工作流

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

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

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

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

liveness_face：真人 Material 组

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

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

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

这意味着真人 material 本质上是“组优先”的：您不能像使用 aigc_avatar 那样直接跳到创建资产。组必须存在并通过验证，上传到其中的任何资产才有效。

清单：选择正确的库类型

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

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

自动 Material 准备的工作原理

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

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

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

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

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

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

409 seedance_material_preparing

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

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

实际上，这意味着您的生成流水线需要一个小型的重试循环，而不仅仅是一个简单的 try/catch。构建自动化视频流水线的团队应将此状态视为与速率限制退避（rate-limit backoff）相同的方式处理——这是预期的、暂时的，应在代码中处理，而不是作为面向用户的错误报告。

如何在生成中使用 Material

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

核心工作流如下所示：

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

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

有关 TokenLab 上当前可用的视频生成模型的更广泛比较，视频模型分类页面并排列出了当前选项。

实际后续步骤

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

您可以直接在 Seedance assets dashboard 中浏览 material 库，查看您已创建资产的状态、库类型和组关系。

在提交生产工作流之前，值得查看我们 AI video API pricing 2026 概览中的当前费率，以了解成本如何随使用量扩展。您还可以使用 TokenLab dashboard usage exports 中的指导来跟踪和导出您自己的使用数据。

常见问题解答

什么是 Seedance material 资产？ material 资产是一种可重用的视频生成参考资源（图像、视频或音频），存储为具有自身生命周期状态的组织范围对象。一旦达到 ACTIVE，您就可以在多次生成调用中通过 ID 引用它，而无需每次都重新提供原始 URL。

group_id 和 material_asset_id 有什么区别？ group_id 标识一个 material 资产组，该组主要用于组织真人（liveness_face）资产并在组级别管理验证。material_asset_id 标识单个可重用参考资源——即创建 material 资产时返回的 id——这是您传递给视频生成调用的内容。

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

seedance_material_preparing 是什么意思？ 这是一个 409 响应，当由生成请求中的兼容图像字段（如 image_url 或 start_image）触发的自动 material 准备时间超过 60 秒时返回。响应包含 auto_material_asset_ids，以便您可以轮询这些 ID，并在它们变为 ACTIVE 后重试生成。它表示一个暂时的进行中状态，而不是失败。

来源与时效性

• Seedance 2.0 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 — https://tokenlab.sh/en/dashboard/seedance-assets — 观察日期 2026-07-09

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

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