金山云-文档中心-seedance 2.0真人人像素材使用指南

星流平台

查看更多结果

未找到含当前关键字的文档标题

页面目录

全部展开全部收起

产品更新动态

未找到含该关键词的产品

文档中心

星流平台

模型API服务

API文档

视频生成模型

seedance 2.0真人人像素材使用指南

最近更新时间：2026-07-28 10:32:20



Seedance 2.0 支持使用经过真人认证的人像素材生成视频。使用前需由人物本人完成 H5 活体认证，认证成功后上传人像素材，并通过 asset://<Asset_ID> 在视频生成任务中引用。

本文仅介绍真人人像素材相关接口。Seedance 2.0 的通用请求参数及其他生成方式，请参见《Seedance 2.0》接口文档。

接口说明

项目	说明
素材接口	`POST https://kspmas.ksyun.com/seedance/v1/asset`
接口版本	`2024-01-01`
鉴权方式	`Authorization: Bearer $KSC_API_KEY`
请求格式	`Content-Type: application/json`
视频任务接口	`https://kspmas.ksyun.com/seedance-2.0/v3/contents/generations/tasks`

CreateVisualValidateSession 在底层需要使用 AK/SK 调用上游服务，但用户仍通过金山云 API Key 调用，由平台完成签名转换。
项目参数和租户参数由平台统一处理，用户无需传入 ProjectName、租户 ID 等字段。

使用流程

创建 H5 真人认证会话。
由人物本人完成活体认证。
获取认证创建的素材组 ID（GroupId）。
向素材组上传人像素材。
查询素材状态，等待状态变为 Active。
使用 asset://<Asset_ID> 创建视频生成任务。

1. 拉起 H5 真人认证页

调用 CreateVisualValidateSession 创建认证会话，并将返回的 H5 页面地址提供给被认证人。

curl -X POST \
  'https://kspmas.ksyun.com/seedance/v1/asset?Action=CreateVisualValidateSession&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $KSC_API_KEY" \
  -d '{
    "CallbackURL": "https://example.callback.com"
  }'

接口返回认证页面地址和 BytedToken。用户完成认证后，页面将跳转至 CallbackURL。

回调中的主要参数：

参数	说明
`bytedToken`	本次真人认证凭证
`resultCode`	`10000` 表示认证成功
`algorithmBaseRespCode`	认证服务错误码
`verify_type`	认证类型，当前为 `real_time`

认证失败后，原 H5 地址将失效，需要重新创建认证会话。

2. 获取认证创建的素材组 ID

认证成功后，调用 GetVisualValidateResult 获取本次认证创建的 GroupId。

curl -X POST \
  'https://kspmas.ksyun.com/seedance/v1/asset?Action=GetVisualValidateResult&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $KSC_API_KEY" \
  -d '{
    "BytedToken": "<BYTED_TOKEN>"
  }'

BytedToken 有效期为 30 分钟，建议在认证成功后立即查询并保存 GroupId。

平台根据当前 API Key 自动完成租户隔离，用户无需传入租户信息。

3. 创建素材资产

将人像素材上传至认证产生的素材组。接口受理成功后返回素材 ID。

curl -X POST \
  'https://kspmas.ksyun.com/seedance/v1/asset?Action=CreateAsset&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $KSC_API_KEY" \
  -d '{
    "GroupId": "group-20260706210534-xxxxx",
    "URL": "https://example.com/portrait.png",
    "Name": "portrait-front",
    "AssetType": "Image"
  }'

Name 仅用于素材管理和搜索，不参与视频生成。

4. 查询素材列表

支持根据素材组、素材状态和素材名称查询素材。

curl -X POST \
  'https://kspmas.ksyun.com/seedance/v1/asset?Action=ListAssets&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $KSC_API_KEY" \
  -d '{
    "Filter": {
      "GroupIds": [
        "group-20260706210534-xxxxx"
      ],
      "GroupType": "LivenessFace",
      "Statuses": [
        "Active"
      ],
      "Name": "portrait"
    },
    "PageNumber": 1,
    "PageSize": 10,
    "SortBy": "CreateTime",
    "SortOrder": "Desc"
  }'

平台自动限制用户只能查询当前租户下的素材。

5. 查询单个素材

curl -X POST \
  'https://kspmas.ksyun.com/seedance/v1/asset?Action=GetAsset&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $KSC_API_KEY" \
  -d '{
    "Id": "asset-20260706230811-xxx"
  }'

素材状态说明：

状态	说明	是否可以生成视频
`Processing`	素材处理中	否
`Active`	素材处理成功	是
`Failed`	素材处理失败	否

6. 更新素材信息

curl -X POST \
  'https://kspmas.ksyun.com/seedance/v1/asset?Action=UpdateAsset&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $KSC_API_KEY" \
  -d '{
    "Id": "asset-20260706230811-xxx",
    "Name": "portrait-updated"
  }'

7. 删除单个素材

curl -X POST \
  'https://kspmas.ksyun.com/seedance/v1/asset?Action=DeleteAsset&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $KSC_API_KEY" \
  -d '{
    "Id": "asset-20260706230811-xxx"
  }'

8. 查询素材组列表

支持根据素材组名称模糊搜索，或通过多个 GroupId 查询。

curl -X POST \
  'https://kspmas.ksyun.com/seedance/v1/asset?Action=ListAssetGroups&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $KSC_API_KEY" \
  -d '{
    "Filter": {
      "Name": "portrait",
      "GroupType": "LivenessFace"
    },
    "PageNumber": 1,
    "PageSize": 10,
    "SortBy": "CreateTime",
    "SortOrder": "Desc"
  }'

平台自动限制用户只能查询当前租户下的素材组。

9. 查询素材组信息

curl -X POST \
  'https://kspmas.ksyun.com/seedance/v1/asset?Action=GetAssetGroup&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $KSC_API_KEY" \
  -d '{
    "Id": "group-20260706210534-xxxxx"
  }'

10. 更新素材组信息

curl -X POST \
  'https://kspmas.ksyun.com/seedance/v1/asset?Action=UpdateAssetGroup&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $KSC_API_KEY" \
  -d '{
    "Id": "group-20260706210534-xxxxx",
    "Name": "portrait-group-updated",
    "Description": "真人认证人像素材"
  }'

项目参数由平台设置，用户无需传入 ProjectName。

11. 删除素材组

curl -X POST \
  'https://kspmas.ksyun.com/seedance/v1/asset?Action=DeleteAssetGroup&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $KSC_API_KEY" \
  -d '{
    "Id": "group-20260706210534-xxxxx"
  }'

删除素材组前，请确认组内素材已不再被业务使用。

使用人像素材生成视频

素材状态变为 Active 后，可通过 asset://<Asset_ID> 在 Seedance 2.0 请求中引用。

curl -X POST \
  'https://kspmas.ksyun.com/seedance-2.0/v3/contents/generations/tasks' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $KSC_API_KEY" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "图片1中的美妆博主用中文介绍，并手持图片2中的面霜面向镜头展示。"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://asset-20260706230811-xxx"
        },
        "role": "reference_image"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/product.jpg"
        },
        "role": "reference_image"
      }
    ],
    "generate_audio": true,
    "ratio": "16:9",
    "duration": 11,
    "watermark": true,
    "resolution": "1080p"
  }'

提示词通过素材在 content 数组中的顺序引用素材：

真人人像素材是第一个图片，因此对应“图片1”。
产品图片是第二个图片，因此对应“图片2”。
不支持在提示词中使用 Asset ID 或素材名称指代素材。

查询视频任务

curl -X GET \
  'https://kspmas.ksyun.com/seedance-2.0/v3/contents/generations/tasks/<TASK_ID>' \
  -H "Authorization: Bearer $KSC_API_KEY"

任务状态及响应字段与《Seedance 2.0》接口文档一致。

使用限制

只有状态为 Active 的素材可以用于视频生成。
一个真人人像素材组只能绑定一个完成认证的真人。
同一真人可在同一素材组内继续上传不同妆造或景别的素材。
素材中应只包含一个清晰人脸，并与素材组认证的真人一致。
项目和租户参数由平台处理，用户不得自行传入。
请勿在代码、文档或日志中明文保存 API Key、BytedToken 等敏感信息。

文档导读

上一篇：Seedance 2.0 API文档

下一篇：图片生成模型

纯净模式常规模式

纯净模式

点击可全屏预览文档内容