≡ 全部文档

模型 API / 素材库

素材库

更新时间：2026-08-21

接口说明

素材库用于把图片 / 视频 / 音频登记到平台，之后在视频生成里用 asset://<素材ID> 引用，不必每次重传大文件。素材分「素材组」和「素材」两级：先建组，再往组里加素材。

素材库接口只需 API Key 鉴权，不消耗额度。

素材组分两类：aigc 用于普通 / AI 生成素材，real_person 用于真人素材。真人素材涉及人脸信息，必须先完成人脸授权与活体校验，见下文「真人素材」。

关于 external_user_id

素材组与素材接口都接受可选的 external_user_id，用于在你自己的账号内再按终端用户分隔素材。平台会自动为该值加上你的账号前缀后再存储，所以响应里的 ExternalUserId 会比传入的长；不同账号之间即使传相同的值也互不可见。不传则落到你账号的默认命名空间。

external_user_id 只能包含字母、数字、下划线、连字符、点和冒号，长度 1～64，否则返回 400。同一终端用户请始终传同一个值，否则查不到此前建的素材。

素材组

创建素材组

POST/asset-groups

参数	类型	必需	说明
name	string	必需	素材组名称
description	string	可选	素材组描述
type	string	可选	aigc（默认）= 普通 / AI 生成素材；real_person = 真人素材，需先通过人脸授权与活体校验
external_user_id	string	可选	终端用户标识，用于在你的账号内再分隔素材；不传则用账号默认命名空间

curl -X POST "https://www.wangyidaai.com/v1/asset-groups" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "我的AIGC素材",
    "description": "风格参考图",
    "type": "aigc",
    "external_user_id": "user_12345"
  }'

JSON

{
  "Id": "group-20260526175953-z9nfc",
  "Name": "我的AIGC素材",
  "Description": "风格参考图",
  "GroupType": "aigc",
  "ExternalUserId": "bm-u1024-user_12345",
  "CreateTime": "2026-05-26T17:59:53Z"
}

查询素材组列表

GET/asset-groups

支持 type（aigc / real_person）与 external_user_id 两个查询参数，均可省略；省略 external_user_id 时返回账号默认命名空间下的素材组。

cURL

curl "https://www.wangyidaai.com/v1/asset-groups?type=aigc&external_user_id=user_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "Result": {
    "Items": [
      {
        "Id": "group-20260526175953-z9nfc",
        "Name": "我的AIGC素材",
        "Description": "风格参考图",
        "GroupType": "aigc",
        "ExternalUserId": "bm-u1024-user_12345",
        "CreateTime": "2026-05-26T17:59:53Z"
      }
    ]
  }
}

重命名素材组

PUT/asset-groups/{group_id}

cURL

curl -X PUT "https://www.wangyidaai.com/v1/asset-groups/group-20260526175953-z9nfc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "重命名后的素材组",
    "external_user_id": "user_12345"
  }'

删除素材组

DELETE/asset-groups/{group_id}

删除素材组会连同组内全部素材一起删除，不可恢复。

cURL

curl -X DELETE "https://www.wangyidaai.com/v1/asset-groups/group-20260526175953-z9nfc?external_user_id=user_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

素材

添加素材

POST/assets

参数	类型	必需	说明
group_id	string	必需	目标素材组 ID
url	string	必需	素材地址：公网 HTTP/HTTPS 链接，或上传接口返回的平台地址；也可用 asset://<素材ID> 引用已有素材
asset_type	string	可选	素材类型：Image（默认）/ Video / Audio
name	string	可选	素材名称
external_user_id	string	可选	终端用户标识，与所属素材组保持一致

curl -X POST "https://www.wangyidaai.com/v1/assets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "group-20260526175953-z9nfc",
    "url": "https://example.com/reference.jpg",
    "asset_type": "Image",
    "name": "风格参考图",
    "external_user_id": "user_12345"
  }'

JSON

{
  "Id": "asset-20260528191439-8grtf",
  "Name": "风格参考图",
  "URL": "https://cdn.wangyidaai.com/assets/xxx.jpg",
  "AssetType": "Image",
  "GroupId": "group-20260526175953-z9nfc",
  "Status": "Active",
  "CreateTime": "2026-05-28T19:14:39Z"
}

Status 为 Active 表示素材可用；Processing 表示平台仍在处理，稍后重查；Failed 表示该素材不可用（例如源地址取不到）。

查询组内素材

GET/assets

group_id 必填。返回该组下 Active 与 Failed 的全部素材。

cURL

curl "https://www.wangyidaai.com/v1/assets?group_id=group-20260526175953-z9nfc&external_user_id=user_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "Result": {
    "Items": [
      {
        "Id": "asset-20260528191439-8grtf",
        "Name": "风格参考图",
        "URL": "https://cdn.wangyidaai.com/assets/xxx.jpg",
        "AssetType": "Image",
        "GroupId": "group-20260526175953-z9nfc",
        "Status": "Active",
        "CreateTime": "2026-05-28T19:14:39Z"
      }
    ]
  }
}

查询单个素材

GET/assets/{asset_id}

只能查自己名下的素材；素材不属于当前 API Key（或所传的 external_user_id 命名空间）时返回 404。

cURL

curl "https://www.wangyidaai.com/v1/assets/asset-20260528191439-8grtf?external_user_id=user_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

删除素材

DELETE/assets/{asset_id}

cURL

curl -X DELETE "https://www.wangyidaai.com/v1/assets/asset-20260528191439-8grtf?external_user_id=user_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

上传素材文件

本地文件没有公网地址时，先上传换取平台地址，再用该地址调「添加素材」。支持图片 / 视频 / 音频，单个文件不超过 200MB。

POST/material-files

cURL

curl -X POST "https://www.wangyidaai.com/v1/material-files" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/reference.jpg"

JSON

{
  "url": "https://cdn.wangyidaai.com/materials/reference.jpg"
}

真人素材

真人素材涉及人脸信息。接入前请确认已就人脸信息处理取得终端用户的单独同意，并在你自己的产品内留存授权记录。

真人素材组需依次完成三步：提交人脸授权 → 创建活体校验会话让用户扫码 → 轮询结果拿到真人素材组 ID。之后往该组加素材与普通素材组一致。

1. 查询并提交人脸授权

GET/face-consent

cURL

curl "https://www.wangyidaai.com/v1/face-consent" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "valid": false,
  "need_versions": {
    "policy": "2026-04-17",
    "volc": "v1-2025-09-01"
  }
}

valid 为 false 时，用响应里的 need_versions 提交授权。版本号请从响应中取，不要写死 —— 版本更新后写死的值会被拒绝。

POST/face-consent

cURL

curl -X POST "https://www.wangyidaai.com/v1/face-consent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_version": "2026-04-17",
    "volc_rule_version": "v1-2025-09-01"
  }'

2. 创建活体校验会话

POST/asset-groups/validate-session

返回二维码与 BytedToken。把 QRCodeDataURL（Base64 PNG）展示给用户扫码，或直接跳转 H5Link 完成活体采集。callback_url 可选，需提前在后台加白名单。

cURL

curl -X POST "https://www.wangyidaai.com/v1/asset-groups/validate-session" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user_12345"
  }'

JSON

{
  "Result": {
    "BytedToken": "20260607000000000000000000000000",
    "QRCodeDataURL": "data:image/png;base64,...",
    "H5Link": "https://kyc.byteintl.com/..."
  }
}

3. 轮询校验结果

POST/asset-groups/validate-result

用上一步的 BytedToken 轮询，建议每 3 秒一次、最多 2 分钟。status 为 active 且 GroupId 非空表示通过，该 GroupId 就是建好的真人素材组。

cURL

curl -X POST "https://www.wangyidaai.com/v1/asset-groups/validate-result" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bytedToken": "20260607000000000000000000000000"
  }'

JSON

{
  "GroupId": "group-20260526180000-abcde",
  "status": "active"
}

在视频生成中引用

拿到素材 ID 后，在视频生成请求的 content 数组里用 asset://<素材ID> 作为地址即可，无需再传公网 URL。

cURL

curl -X POST "https://www.wangyidaai.com/v1/video/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "让画面里的人物转身微笑，电影级镜头",
    "content": [
      {
        "type": "image_url",
        "image_url": { "url": "asset://asset-20260528191439-8grtf" }
      }
    ]
  }'

参数与轮询方式见「视频生成」一节，素材引用不改变其余字段的用法。

没有找到想看的内容？联系我们 →