Seedance 真人与虚拟人素材 API

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

项目	内容
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（中文）、虚拟人素材 API（中文）

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

认证

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

Authorization: Bearer <LAOZHANG_API_KEY>
Content-Type: application/json

调用方不需要 YingTu 登录态、Google 登录态或 Cookie。API Key 用于验证老张API账户与可用额度；认证记录和素材记录会绑定到创建它们的同一个 API Key，后续查询或创建真人素材时必须继续使用该 Key。认证会话、素材创建与状态查询是否单独计费，以控制台和调用日志为准；引用素材生成视频时，按 Seedance 视频生成的计费规则扣费。下面的 cURL 示例从环境变量读取密钥，先在终端中设置：

export LAOZHANG_API_KEY="替换为你的老张API密钥"

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

接口一览

虚拟人素材：

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 或签名登录的图片地址会被拒绝。

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 和初始状态：

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

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

真人素材接入

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

创建认证会话

调用 POST /api/seedance-assets/real-persons/verifications，提交认证完成后的 HTTPS callback_url。可选 language 取值：

zh（默认）
en
zh-Hant

由真人本人完成官方认证

将响应中的一次性 verification_url 安全地交付给本人。认证链接有效期为 30 分钟，不应写入日志或长期保存。

查询认证结果

从回调地址的 verification_id 查询认证状态。pending 查询仍返回 HTTP 200；只有状态变为 verified 后才能创建真人素材。

创建并查询真人素材

提交同一人物的清晰正面公网 HTTPS 图片。创建后使用返回的公开 id 查询素材，直到状态变为 Active。

创建认证会话：

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"
  }'

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

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"
  }'

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

查询素材状态

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

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：

{
  "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
}

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

限制、错误与验收

每个 API Key 每小时最多 12 次创建类 POST 请求；素材状态 GET 查询不计入。若返回 429，按 Retry-After 等待。
真人认证链接有效期为 30 分钟。过期后返回 410 verification_expired，需要创建新会话。
认证仍为 pending 时提前创建真人素材会返回 409 verification_pending。
403 capability_unavailable 表示服务端账户未开通私域人物素材权益，更换图片无法解决该错误。请联系支持团队申请开通（邮件 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

视频生成 API

文本 API

多模态与音频 API

Seedance 真人与虚拟人素材 API

认证

接口一览

虚拟人素材接入

真人素材接入

查询素材状态

在 Seedance 视频任务中引用素材

限制、错误与验收

常见问题

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

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

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

相关文档

​认证

​接口一览

​虚拟人素材接入

​真人素材接入

​查询素材状态

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

​限制、错误与验收

​常见问题

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

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

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

​相关文档

认证

接口一览

虚拟人素材接入

真人素材接入

查询素材状态

在 Seedance 视频任务中引用素材

限制、错误与验收

常见问题

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

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

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

相关文档