Seedance 真人人像认证与素材管理使用指南

概述

Seedance 真人人像功能允许用户通过 H5 活体认证后，在火山方舟平台上创建一个专属的「真人素材组」（LivenessFace 类型），随后可以将真人照片/视频上传到该组中作为素材，用于后续的 AI 视频生成（如 Seedance 数字人）。

完整流程

┌─────────────────────┐     ┌──────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
│ 1. 创建认证 H5 会话  │ ──> │ 2. 获取认证结果       │ ──> │ 3. 创建素材          │ ──> │ 4. 获取素材详情      │
│ CreateVisualValidate│     │ GetVisualValidate    │     │ CreateAsset          │     │ GetAsset            │
│ Session             │     │ Result               │     │ (使用真人组 GroupId) │     │                     │
└─────────────────────┘     └──────────────────────┘     └─────────────────────┘     └─────────────────────┘
        │                           │
        v                           v
  获得 BytedToken            获得 GroupId
  + H5Link                   (真人素材组 ID)
        │
        v
  用户打开 H5Link
  完成活体认证

前置条件

已在 Open Move 平台注册，并创建了属于 Seedance 供应商分组的令牌

令牌已生成 Access Key ID 和 Secret Access Key（用于 V4 签名）

认证方式

所有 API 使用火山 V4 签名认证（HMAC-SHA256），请求需携带以下 HTTP 头：

Header	说明
`Authorization`	`HMAC-SHA256 Credential={AccessKeyId}/{date}/{region}/ark/request, SignedHeaders=host;x-content-sha256;x-date, Signature={signature}`
`X-Date`	请求时间戳，格式 `yyyyMMddTHHmmssZ`（UTC），允许误差 ±15 分钟
`X-Content-Sha256`	请求体的 SHA256 哈希值
`Host`	请求目标主机

请求地址

所有 API 共用同一个路径，通过 Action 查询参数区分：

POST https://api.omove.ai/openapi/volcengine/?Action={Action}&Version=2024-01-01

响应格式

{
  "ResponseMetadata": {
    "RequestId": "string",
    "Action": "string",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": { ... }
}

步骤 1：创建真人人像认证 H5 会话

API：CreateVisualValidateSession

拉起一个 H5 真人活体认证会话。返回 BytedToken（认证令牌）和 H5Link（认证页链接），用户需在浏览器中打开 H5Link 完成人脸活体检测。

请求

{
  "CallbackURL": "https://your-app.com/face-verify/callback"
}

参数	类型	必填	说明
`CallbackURL`	string	是	客户自己的回调 URL。火山验证完成后，Open Move 会先接收回调并记录人脸 ID / GroupId，然后 302 重定向到此 URL，附带 `bytedToken`、`resultCode` 和 `groupId`（认证成功时）参数。

响应

{
  "ResponseMetadata": {
    "RequestId": "20260714150513F42FF1D7034AFA2FEC89",
    "Action": "CreateVisualValidateSession",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "BytedToken": "cv-token-20260714150513-abc123def456",
    "H5Link": "https://visual.volcengineapi.com/verify?token=cv-token-20260714150513-abc123def456"
  }
}

字段	说明
`BytedToken`	认证会话令牌，后续查询认证结果时使用。请妥善保存
`H5Link`	H5 认证页链接，引导用户在浏览器（推荐移动端）中打开完成活体认证

会话有效期

会话有效期 30 分钟，超时未完成认证将自动过期

用户完成认证后，火山回调到 Open Move，Open Move 自动获取结果并落库 GroupId，然后重定向到客户传入的 CallbackURL

重定向到客户回调 URL 时附带的参数：bytedToken、resultCode（成功为 10000），认证成功时额外附带 groupId

步骤 2：获取真人人像认证结果

API：GetVisualValidateResult

根据 BytedToken 查询真人活体认证结果。认证成功后返回 GroupId，该 ID 即为真人素材组（LivenessFace 类型），用于后续上传真人素材。

请求

{
  "BytedToken": "cv-token-20260714150513-abc123def456"
}

参数	类型	必填	说明
`BytedToken`	string	是	步骤 1 返回的认证会话令牌

响应（认证成功）

{
  "ResponseMetadata": {
    "RequestId": "20260714151000F42FF1D7034AFA2FEC90",
    "Action": "GetVisualValidateResult",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "GroupId": "group-20260714150513-livenessface-xyz",
    "BytedToken": "cv-token-20260714150513-abc123def456",
    "Status": "success"
  }
}

字段	说明
`GroupId`	真人素材组 ID（LivenessFace 类型）。认证成功后才有此字段。请妥善保存，后续 CreateAsset 使用
`BytedToken`	认证会话令牌（回显）
`Status`	认证状态：`success`（成功）、`pending`（进行中）、`failed`（失败）

轮询策略

调用时机：用户在 H5 页面完成认证后调用；也可在 H5 页面打开后立即开始轮询

轮询间隔：3-5 秒

最大等待：30 分钟（会话有效期）

终止条件：返回 GroupId（成功）或 Status 为 failed（失败）

注意事项

认证成功后，一个 BytedToken 对应一个真人素材组（GroupId），该组可反复使用上传多个素材

步骤 3：创建素材（使用真人人像组 ID）

API：CreateAsset

将真人照片或视频上传到步骤 2 获得的真人素材组（GroupId）。上传是异步的，返回素材 ID 后需要轮询 GetAsset 确认处理状态。

请求

{
  "GroupId": "group-20260714150513-livenessface-xyz",
  "URL": "https://example.com/my-photo.jpg",
  "AssetType": "Image",
  "Name": "我的真人照片"
}

参数	类型	必填	说明
`GroupId`	string	是	真人素材组 ID（来自步骤 2 的 `GetVisualValidateResult` 返回的 `GroupId`）。使用真人组 ID 时，Open Move 会自动将素材标记为 LivenessFace 类型
`URL`	string	是	素材的公网可访问 URL，火山会从该地址拉取素材
`AssetType`	string	是	素材类型：`Image`（图片）、`Video`（视频）、`Audio`（音频）
`Name`	string	否	素材名称

素材要求

图片：宽高比必须在 0.4~2.5 之间

URL：必须公网可访问，支持 HTTPS

火山会从 URL 拉取素材进行处理，处理完成后素材状态变为 Active

响应

{
  "ResponseMetadata": {
    "RequestId": "20260714151500BD40EA153193D54EB921",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260714151500-x8qmn"
  }
}

字段	说明
`Id`	新建的素材 ID。素材状态初始为 `Processing`，需轮询 `GetAsset` 确认处理完成

错误示例

{
  "ResponseMetadata": {
    "Action": "CreateAsset",
    "Error": {
      "Code": "InternalError",
      "Message": "素材宽高比必须在 0.4~2.5 之间，请更换符合比例的图片或视频"
    },
    "Region": "cn-beijing",
    "Service": "ark",
    "Version": "2024-01-01"
  }
}

步骤 4：获取素材详情

API：GetAsset

查询单个素材的详细信息，包括处理状态。素材上传后状态为 Processing，处理完成后变为 Active（成功）或 Failed（失败）。

请求

{
  "Id": "asset-20260714151500-x8qmn"
}

参数	类型	必填	说明
`Id`	string	是	步骤 3 返回的素材 ID

响应

{
  "ResponseMetadata": {
    "RequestId": "20260714151510BABDF5EA3CCE767701A7",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260714151500-x8qmn",
    "Name": "我的真人照片",
    "GroupId": "group-20260714150513-livenessface-xyz",
    "AssetType": "Image",
    "Status": "Active",
    "URL": "https://ark-media-asset.tos-cn-beijing.volces.com/...",
    "ProjectName": "Seedance默认",
    "CreateTime": "2026-07-14T07:15:00Z",
    "UpdateTime": "2026-07-14T07:15:02Z"
  }
}

字段	说明
`Id`	素材 ID
`Name`	素材名称
`GroupId`	所属素材组 ID
`AssetType`	素材类型：`Image` / `Video` / `Audio`
`Status`	素材状态：`Processing`（处理中）、`Active`（可用）、`Failed`（失败）
`URL`	火山签发的临时预览 URL，有效期 12 小时
`ProjectName`	供应商分组名称（已被 Open Move 替换为可读名称）
`CreateTime`	创建时间（UTC）
`UpdateTime`	更新时间（UTC）

轮询策略

轮询间隔：5 秒

最大等待：60 秒

终止条件：Status 变为 Active（成功）或 Failed（失败）

完整流程示例（Python）

常见问题

Q: 认证会话有效期是多久？

认证会话有效期为 30 分钟。超时未完成认证，会话自动过期，需重新创建。

Q: 一个真人素材组（GroupId）可以上传多少素材？

没有硬性上限。一个 GroupId 可以反复使用，上传多个真人照片或视频素材。

Q: 多次认证会创建多个 GroupId 吗？

是的，每次成功的真人认证都会创建一个新的 GroupId。你可以通过 Dashboard API GET /api/user/asset/visual/groups?provider=xxx 查看所有已认证的真人组。

Q: 素材的临时 URL 有效期多久？

火山签发的素材预览 URL 有效期为 12 小时。过期后需重新调用 GetAsset 获取新的 URL。

Q: CreateAsset 时不传 GroupId 会怎样？

如果不传 GroupId，Open Move 会自动创建/复用一个 AIGC 类型的素材组（非真人组）。上传真人素材时必须显式传入步骤 2 获得的 GroupId，Open Move 会据此识别为 LivenessFace 类型。

Q: 图片宽高比有什么限制？

素材图片的宽高比必须在 0.4~2.5 之间，超出范围会被火山拒绝。建议使用正面人脸照片，分辨率不低于 512x512。

Seedance 真人人像认证与素材管理使用指南

概述#

完整流程#

前置条件#

认证方式#

请求地址#

响应格式#

步骤 1：创建真人人像认证 H5 会话#

请求#

响应#

会话有效期#

步骤 2：获取真人人像认证结果#

请求#

响应（认证成功）#

轮询策略#

注意事项#

步骤 3：创建素材（使用真人人像组 ID）#

请求#

素材要求#

响应#

错误示例#

步骤 4：获取素材详情#

请求#

响应#

轮询策略#

完整流程示例（Python）#

常见问题#

Q: 认证会话有效期是多久？#

Q: 一个真人素材组（GroupId）可以上传多少素材？#

Q: 多次认证会创建多个 GroupId 吗？#

Q: 素材的临时 URL 有效期多久？#

Q: CreateAsset 时不传 GroupId 会怎样？#

Q: 图片宽高比有什么限制？#

概述

完整流程

前置条件

认证方式

请求地址

响应格式

步骤 1：创建真人人像认证 H5 会话

请求

响应

会话有效期

步骤 2：获取真人人像认证结果

请求

响应（认证成功）

轮询策略

注意事项

步骤 3：创建素材（使用真人人像组 ID）

请求

素材要求

响应

错误示例

步骤 4：获取素材详情

请求

响应

轮询策略

完整流程示例（Python）

常见问题

Q: 认证会话有效期是多久？

Q: 一个真人素材组（GroupId）可以上传多少素材？

Q: 多次认证会创建多个 GroupId 吗？

Q: 素材的临时 URL 有效期多久？

Q: CreateAsset 时不传 GroupId 会怎样？

Q: 图片宽高比有什么限制？