> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedance 真人与虚拟人流程说明

> 说明 Seedance 2.0 真人素材、虚拟人素材与视频生成任务的预期接入流程。当前接口正在开发兼容中，等待上线。

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

<Info>
  基础文生视频、图片参考、首尾帧、视频参考等能力仍使用 [Seedance 2.0 视频生成
  API](/api-capabilities/seedance2-video-generation)。本页只说明真人素材和虚拟人素材上线后的额外素材流程。
</Info>

## 能力状态

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

## 流程总览

<Steps>
  <Step title="准备素材与授权">
    确认真人肖像、声音、服装形象或虚拟人形象拥有合法授权。真人素材需要完成授权确认和认证流程；虚拟人素材需要确认素材库使用权限。
  </Step>

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

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

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

## 真人素材流程

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

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

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

## 虚拟人素材流程

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

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

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

## 真人 + 虚拟人组合

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

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

## 开发者集成路径

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

推荐实现流程：

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

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

## ID 如何传入视频任务

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

```json theme={null}
{
  "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
}
```

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

## 表单字段如何映射

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

```ts theme={null}
for (const assetId of realAssetIds) {
  formData.append("realPersonAssetId", assetId);
}

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

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

```ts theme={null}
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",
  }),
);
```

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

## 服务端调用示例

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

```ts theme={null}
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
  建议保存在用户自己的浏览器、本地数据库或业务系统中。
* 上线后先在测试环境用短时长、低分辨率任务验证，再扩大到生产工作流。

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