Seedance 真人与虚拟人流程说明

当前真人素材与虚拟人素材接口正在开发兼容中，尚未正式上线。本文用于说明预期接入流程和上线前准备，不代表这些接口已经可以在生产环境调用。正式上线后会补充完整接口路径、字段、错误码与代码示例。

基础文生视频、图片参考、首尾帧、视频参考等能力仍使用 Seedance 2.0 视频生成 API。本页只说明真人素材和虚拟人素材上线后的额外素材流程。

能力状态

能力	当前状态	说明
普通文生视频 / 图生视频	已按基础 Seedance 接口提供	使用 `/seedance/api/v3/contents/generations/tasks` 创建任务
真人素材	开发兼容中，等待上线	预计需要真人授权、认证和素材状态校验
虚拟人素材	开发兼容中，等待上线	预计通过虚拟人素材库或已授权素材 ID 使用
真人 + 虚拟人组合任务	开发兼容中，等待上线	预计会在同一个视频任务中引用多个已通过校验的人物素材

流程总览

准备素材与授权

确认真人肖像、声音、服装形象或虚拟人形象拥有合法授权。真人素材需要完成授权确认和认证流程；虚拟人素材需要确认素材库使用权限。

创建或选择人物素材

真人素材预计通过认证后生成可引用的素材 ID；虚拟人预计从素材库选择或创建后获得素材 ID。接口上线前，素材 ID 的创建路径以实际开通能力为准。

提交 Seedance 视频任务

视频任务仍围绕提示词、模型、时长、比例、分辨率等 Seedance 参数组织；人物素材 ID 会作为 content 数组里的引用素材传入。不要把真人 ID 或虚拟人 ID 作为视频任务的顶层字段直接透传给上游。

查询与下载结果

任务创建后继续使用任务 ID 查询状态。成功后可读取结果 URL，或通过兼容下载接口 /v1/videos/{id}/content 下载视频文件。

真人素材流程

真人素材适用于需要保持指定真人形象、动作风格或人物一致性的场景。上线后预计会包含以下步骤：

上传或提交真人素材。
完成真人授权与必要的认证流程。
等待素材进入可用状态。
在 Seedance 视频任务中引用该真人素材。
查询视频任务状态并下载结果。

当前不要把真人人脸图片或真人视频直接作为普通 image_url / video_url 输入用于真人一致性生成。真人素材能力需要等待兼容接口上线后再按专用流程调用。

虚拟人素材流程

虚拟人素材适用于数字人、品牌角色、虚拟主播、企业形象代言人等场景。上线后预计会包含以下步骤：

在虚拟人素材库选择已授权素材，或按平台流程创建虚拟人素材。
获取可用于视频任务的人物素材 ID。
在提示词中描述虚拟人的动作、镜头、台词或场景。
在 Seedance 视频任务中引用虚拟人素材 ID。
查询任务状态并下载结果。

虚拟人素材不等于绕过真人授权。基于真实人物创建的虚拟形象，仍需要满足肖像、声音、姓名、商标和相关授权要求。

真人 + 虚拟人组合

当一个视频同时需要真人素材和虚拟人素材时，预计会采用“多个已校验人物素材引用 + 同一个 Seedance 任务”的方式：

阶段	真人素材	虚拟人素材
前置校验	真人授权、认证、素材状态	素材库授权、素材状态
任务引用	引用真人素材 ID	引用虚拟人素材 ID
提示词控制	描述真人动作、表情、镜头位置	描述虚拟人动作、互动关系、场景
结果获取	同一个任务 ID 查询和下载	同一个任务 ID 查询和下载

开发者集成路径

如果业务系统暂时不承接真人认证链接、真人图片提交、虚拟人创建和素材状态管理，可以把影图 AI Seedance 项目区作为 Asset ID 获取入口。开发者只需要在业务侧保存返回的 Asset ID，并在创建 Seedance 视频任务时把这些 ID 写入 content 引用项。推荐实现流程：

在业务前端放置“创建人物素材”入口，跳转或引导用户进入 laozhang.ai Seedance 项目区。
真人素材：用户先生成 H5 真人认证链接并完成认证，再提交真人图片，拿到真人 Asset ID。
虚拟人素材：用户填写虚拟人描述词，生成虚拟人 Asset ID。
业务系统保存返回的 asset-...，并绑定到自己的用户、项目或素材记录。
业务后端读取已保存的 Asset ID，创建 Seedance 视频任务。

普通业务流只需要保存用户自己的 Asset ID。素材库列表、素材详情列表等管理员接口不应暴露给终端用户；如果产品需要历史记录，应保存用户自己创建或申请返回的 Asset ID 列表。

ID 如何传入视频任务

真人素材 ID 和虚拟人素材 ID 都是人物素材的引用 ID。客户端可以把它们分开收集，但提交到 Seedance 视频任务时，推荐在中转层统一转换为 content 数组里的 image_url 引用项：

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "真人站在画面左侧，虚拟主持人站在画面右侧，一起介绍新品。镜头缓慢推进，高清无水印。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://asset-real-person-example"
      },
      "role": "reference_image"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://asset-virtual-human-example"
      },
      "role": "reference_image"
    }
  ],
  "ratio": "16:9",
  "duration": 4,
  "resolution": "720p",
  "watermark": false,
  "generate_audio": true
}

如果用户界面里只保存 asset-...，中转层提交给 Seedance 前需要补成 asset://asset-...。真人 ID 和虚拟人 ID 可以一起传，和普通参考图一样计入 reference_image 数量限制；当前建议总数不超过 9 个。

表单字段如何映射

如果你的业务前端需要把 ID 传给自己的后端，可以把真人 ID 和虚拟人 ID 分成两个字段提交。多个 ID 重复追加同名字段即可：

for (const assetId of realAssetIds) {
  formData.append("realPersonAssetId", assetId);
}

for (const assetId of virtualAssetIds) {
  formData.append("virtualHumanAssetId", assetId);
}

业务后端收到后，不要把 realPersonAssetId / virtualHumanAssetId 原样作为 Seedance 任务顶层字段透传。后端应统一校验、规范化，然后加入 content：

const SEEDANCE_ASSET_ID_RE = /^asset-[A-Za-z0-9-]+$/;

function toSeedanceAssetUrl(value: string) {
  const assetId = value.trim().replace(/^asset:\/\//, "");

  if (!SEEDANCE_ASSET_ID_RE.test(assetId)) {
    throw new Error("Seedance asset ID must start with asset-.");
  }

  return `asset://${assetId}`;
}

const realPersonAssetIds = formData.getAll("realPersonAssetId").map(String);
const virtualHumanAssetIds = formData.getAll("virtualHumanAssetId").map(String);

const assetContentItems = [...realPersonAssetIds, ...virtualHumanAssetIds].map(
  (assetId) => ({
    type: "image_url",
    image_url: {
      url: toSeedanceAssetUrl(assetId),
    },
    role: "reference_image",
  }),
);

这样前端仍能区分“真人 ID”和“虚拟人 ID”，便于历史记录、权限和 UI 提示；但上游视频任务只看到统一的 content 引用素材列表，和普通参考图片保持同一套任务结构。

服务端调用示例

如果已经从 YingTu 项目区拿到真人 ID 或虚拟人 ID，服务端可以直接把它们组装为 content 引用项并调用 Seedance 创建任务接口：

const apiKey = process.env.LAOZHANG_API_KEY!;
const SEEDANCE_ASSET_ID_RE = /^asset-[A-Za-z0-9-]+$/;

function toSeedanceAssetUrl(value: string) {
  const assetId = value.trim().replace(/^asset:\/\//, "");

  if (!SEEDANCE_ASSET_ID_RE.test(assetId)) {
    throw new Error("Seedance asset ID must start with asset-.");
  }

  return `asset://${assetId}`;
}

const realPersonAssetIds = ["asset-real-person-example"];
const virtualHumanAssetIds = ["asset-virtual-human-example"];

const content = [
  {
    type: "text",
    text: "真人在画面左侧自然讲解，虚拟主持人在画面右侧互动补充，镜头缓慢推进，高清无水印。",
  },
  ...[...realPersonAssetIds, ...virtualHumanAssetIds].map((assetId) => ({
    type: "image_url",
    image_url: {
      url: toSeedanceAssetUrl(assetId),
    },
    role: "reference_image",
  })),
];

const response = await fetch(
  "https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify({
      model: "doubao-seedance-2-0-260128",
      content,
      ratio: "16:9",
      duration: 4,
      resolution: "720p",
      watermark: false,
      generate_audio: true,
      return_last_frame: true,
    }),
  },
);

if (!response.ok) {
  throw new Error(await response.text());
}

const task = await response.json();
console.log(task.id);

创建任务成功后，继续调用任务详情接口查询状态；任务完成后可以使用 /v1/videos/{id}/content 下载 MP4。

接入准备建议

业务侧先把真人授权、素材归属、虚拟人素材版权和使用范围整理清楚。
客户端预留“素材创建 / 素材选择 / 素材状态查询 / 视频任务提交”的分步流程。
普通用户不应调用管理员素材列表接口。创建或申请素材时返回的 Asset ID 建议保存在用户自己的浏览器、本地数据库或业务系统中。
上线后先在测试环境用短时长、低分辨率任务验证，再扩大到生产工作流。

该能力上线前，本页保留流程说明和当前联调约定。正式接口发布后，会在本页补充可调用接口、请求示例、响应字段、错误码和完整 Python 示例。

产品基础

核心 API

文本 API

视频生成 API

图像生成 API

AI 理解能力

Seedance 真人与虚拟人流程说明

能力状态

流程总览

真人素材流程

虚拟人素材流程

真人 + 虚拟人组合

开发者集成路径

ID 如何传入视频任务

表单字段如何映射

服务端调用示例

接入准备建议

​能力状态

​流程总览

​真人素材流程

​虚拟人素材流程

​真人 + 虚拟人组合

​开发者集成路径

​ID 如何传入视频任务

​表单字段如何映射

​服务端调用示例

​接入准备建议

能力状态

流程总览

真人素材流程

虚拟人素材流程

真人 + 虚拟人组合

开发者集成路径

ID 如何传入视频任务

表单字段如何映射

服务端调用示例

接入准备建议