> ## 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 真人与虚拟人素材 API

> 用老张API密钥调用 yingtu.ai 的 Seedance 素材 API：真人认证、创建真人或虚拟人素材、查询状态，并在 Seedance 视频任务中引用。

用老张API密钥调用 Seedance 素材 API，创建真人或虚拟人素材。素材状态变为 `Active` 后，把返回的 `asset://...` URI 加入 [Seedance 视频生成 API](/api-capabilities/seedance2-video-generation) 的任务即可。

| 项目 | 内容 |
| - | - |
| Base URL | `https://yingtu.ai` |
| 认证 | 老张API密钥 Bearer 认证；不要求 YingTu 或 Google 登录态，也不需要单独创建 YingTu API Key |
| 虚拟人素材 | 可用：从一张公网 HTTPS 图片创建可复用的 Asset ID |
| 真人素材 | 可用：真人本人完成官方 H5 授权与活体认证后创建 Asset ID |
| 素材状态查询 | 可用：使用创建响应返回的公开 `id` 查询，直到 `Active` 或 `Failed` |
| Seedance 视频生成 | 可用：将 `asset://...` URI 作为 `reference_image` 加入视频任务 |
| 接口参考 | 请求字段、响应对象、错误码和限流规则以 YingTu 接口参考为准：[真人素材 API（中文）](https://yingtu.ai/zh/docs/seedance-assets/real-person)、[虚拟人素材 API（中文）](https://yingtu.ai/zh/docs/seedance-assets/virtual-human) |

<Warning>
  真人素材必须由本人完成官方 H5 身份、授权与活体认证。基于真实人物制作的虚拟形象也必须取得相应的肖像、声音、姓名、商标和使用授权。
</Warning>

## 认证

所有素材接口都使用老张API密钥：

```http theme={null}
Authorization: Bearer <LAOZHANG_API_KEY>
Content-Type: application/json
```

调用方不需要 YingTu 登录态、Google 登录态或 Cookie。API Key 用于验证老张API账户与可用额度；认证记录和素材记录会绑定到创建它们的同一个 API Key，后续查询或创建真人素材时必须继续使用该 Key。

认证会话、素材创建与状态查询是否单独计费，以[控制台](https://api.laozhang.ai/account/pricing)和[调用日志](https://api.laozhang.ai/log)为准；引用素材生成视频时，按 [Seedance 视频生成的计费规则](/api-capabilities/seedance2-video-generation#计费与价格)扣费。

下面的 cURL 示例从环境变量读取密钥，先在终端中设置：

```bash theme={null}
export LAOZHANG_API_KEY="替换为你的老张API密钥"
```

<Tip>
  API Key 应从服务端环境变量读取，例如 `LAOZHANG_API_KEY`。完整 API Key
  不得写入浏览器代码、URL、日志或技术支持消息。
</Tip>

## 接口一览

虚拟人素材：

| Method | Path | 用途 |
| - | - | - |
| `POST` | `/api/seedance-assets/virtual-humans` | 从公网 HTTPS 图片创建虚拟人素材 |
| `GET` | `/api/seedance-assets/virtual-humans/{id}` | 查询素材处理状态 |

真人素材：

| Method | Path | 用途 |
| - | - | - |
| `POST` | `/api/seedance-assets/real-persons/verifications` | 创建官方 H5 真人认证会话 |
| `GET` | `/api/seedance-assets/real-persons/verifications/{verification_id}` | 查询认证状态 |
| `POST` | `/api/seedance-assets/real-persons` | 认证成功后创建真人素材 |
| `GET` | `/api/seedance-assets/real-persons/{id}` | 查询素材处理状态 |

## 虚拟人素材接入

虚拟人素材适用于数字人、品牌角色、虚拟主播和企业形象等场景。创建时提交一张无需认证即可读取的公网
HTTPS 图片；私网、环回地址和需要 Cookie 或签名登录的图片地址会被拒绝。

```bash theme={null}
curl --request POST \
  --url https://yingtu.ai/api/seedance-assets/virtual-humans \
  --header "Authorization: Bearer $LAOZHANG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "image_url": "https://cdn.example.com/avatar.webp",
    "name": "brand-avatar"
  }'
```

创建成功会返回公开查询 `id`、素材 `uri` 和初始状态：

```json theme={null}
{
  "request_id": "req_01JZEXAMPLE",
  "id": "ast_eyJvcGFxdWUiOiJleGFtcGxlIn0",
  "object": "seedance.asset",
  "kind": "virtual_human",
  "name": "brand-avatar",
  "status": "Processing",
  "uri": "asset://asset-20260729-example"
}
```

<Note>
  `id` 用于 YingTu 素材状态查询；`uri` 用于 Seedance 视频任务。两个字段都应原样保存，不应根据示例拼接或解析内部标识。
</Note>

## 真人素材接入

真人素材比虚拟人素材多一个授权与活体认证步骤。API 调用者可以在自己的产品中发起流程，但
`verification_url` 必须交给被展示的真人本人完成。

<Steps>
  <Step title="创建认证会话">
    调用 `POST /api/seedance-assets/real-persons/verifications`，提交认证完成后的
    HTTPS `callback_url`。

    可选 `language` 取值：

    * `zh`（默认）
    * `en`
    * `zh-Hant`
  </Step>

  <Step title="由真人本人完成官方认证">
    将响应中的一次性 `verification_url` 安全地交付给本人。认证链接有效期为 30
    分钟，不应写入日志或长期保存。
  </Step>

  <Step title="查询认证结果">
    从回调地址的 `verification_id` 查询认证状态。`pending` 查询仍返回 HTTP
    200；只有状态变为 `verified` 后才能创建真人素材。
  </Step>

  <Step title="创建并查询真人素材">
    提交同一人物的清晰正面公网 HTTPS 图片。创建后使用返回的公开 `id`
    查询素材，直到状态变为 `Active`。
  </Step>
</Steps>

创建认证会话：

```bash theme={null}
curl --request POST \
  --url https://yingtu.ai/api/seedance-assets/real-persons/verifications \
  --header "Authorization: Bearer $LAOZHANG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "callback_url": "https://customer.example.com/seedance/verified",
    "language": "zh"
  }'
```

认证成功后创建真人素材：

```bash theme={null}
curl --request POST \
  --url https://yingtu.ai/api/seedance-assets/real-persons \
  --header "Authorization: Bearer $LAOZHANG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "verification_id": "ver_eyJvcGFxdWUiOiJleGFtcGxlIn0",
    "image_url": "https://cdn.example.com/presenter.webp",
    "name": "presenter-a"
  }'
```

<Warning>
  真人人脸图片不能作为普通 `image_url` 输入来替代真人素材流程。需要保持真人身份或人物一致性时，必须先完成专用认证并获得
  `Active` 的真人素材 URI。
</Warning>

## 查询素材状态

虚拟人和真人素材都使用创建响应中的公开 `id` 查询。例如：

```bash theme={null}
curl --request GET \
  --url https://yingtu.ai/api/seedance-assets/virtual-humans/ast_eyJvcGFxdWUiOiJleGFtcGxlIn0 \
  --header "Authorization: Bearer $LAOZHANG_API_KEY"
```

| 状态 | 含义 | 下一步 |
| - | - | - |
| `Processing` | 上游正在处理素材 | 稍后继续查询；此状态不可提交视频任务 |
| `Active` | 素材可用 | 将响应中的 `asset://...` URI 用于 Seedance |
| `Failed` | 素材处理失败 | 读取 `failure` 对象，修正图片或授权问题后重新创建 |

素材处理失败时，查询接口可能仍返回 HTTP 200，并通过
`status=Failed` 和 `failure` 对象表达业务失败。因此不能只用 HTTP
状态码判断素材是否可用。

## 在 Seedance 视频任务中引用素材

拿到 `Active` 的真人或虚拟人素材后，把响应中的完整 `asset://...` URI 作为 `reference_image` 加入 `content`。视频生成仍调用老张API的 [Seedance 视频生成 API](/api-capabilities/seedance2-video-generation)：

```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
}
```

<Info>
  素材创建与状态查询使用 `https://yingtu.ai/api/seedance-assets/...`；视频任务创建与结果查询继续使用 `https://api.laozhang.ai/seedance/api/v3/...`。两个域名承担不同步骤，但都使用老张API密钥。
</Info>

## 限制、错误与验收

* 每个 API Key 每小时最多 12 次创建类 `POST` 请求；素材状态 `GET`
  查询不计入。若返回 `429`，按 `Retry-After` 等待。
* 真人认证链接有效期为 30 分钟。过期后返回 `410 verification_expired`，需要创建新会话。
* 认证仍为 `pending` 时提前创建真人素材会返回 `409 verification_pending`。
* `403 capability_unavailable` 表示服务端账户未开通私域人物素材权益，更换图片无法解决该错误。请联系支持团队申请开通（邮件 [hi@laozhang.ai](mailto:hi@laozhang.ai)，或 Telegram @laozhang\_cn），并附上响应中的 `request_id`。
* 所有成功和错误响应都包含 `request_id`。排障信息应包含该值，但不得包含完整 API Key。
* 接入验收以素材查询结果为
  `Active`，并且其 `asset://...` URI 能在 Seedance 任务中正常引用。

## 常见问题

### 能直接用真人照片作参考图吗？

不可以。火山方舟说明 Seedance 2.0 系列和 2.5 都不支持直接上传含真人人脸的参考图或视频，这类请求会被上游内容审核拦截。

需要真人出镜时，由本人完成认证后创建[真人素材](#真人素材接入)；只需要真人风格的人物而不指定具体某个人时，用[虚拟人素材](#虚拟人素材接入)。

两种素材都要等状态变为 `Active`，再把 `asset://...` URI 作为 `reference_image` 提交。

### 虚拟人素材和真人素材怎么选？

看视频里是否必须是某个真实的人。数字人、品牌角色、虚拟主播等不对应具体真人的形象，用虚拟人素材，一张公网 HTTPS 图片即可创建。

需要保留某位真人的身份和相貌时，用真人素材：被展示的本人必须在 30 分钟内完成官方 H5 授权与活体认证，调用方无法代为完成。

基于真实人物制作的虚拟形象不能绕开授权要求，仍需取得相应的肖像、声音、姓名等使用授权。

### 更换 API Key 后还能查询原来的素材吗？

不能。认证记录和素材记录绑定创建它们的 API Key，用其他 Key 查询或基于该认证创建真人素材会返回 `403 resource_not_owned`。轮换或停用 Key 前，先确认不再需要查询这些素材；说明见[认证](#认证)。

## 相关文档

* [真人素材 API 完整参考](https://yingtu.ai/zh/docs/seedance-assets/real-person)
* [虚拟人素材 API 完整参考](https://yingtu.ai/zh/docs/seedance-assets/virtual-human)
* [Seedance 视频生成 API](/api-capabilities/seedance2-video-generation)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.