真人素材库 · 接口文档

真人素材库接口。用于上传真人素材、查询素材状态、修改描述、删除素材。上传成功后拿到平台中立的素材 ID（mat_xxx），在视频生成请求里引用即可。

本文档只包含真人素材相关接口，不含视频生成等其它接口。
该素材文档支持模型如下：
doubao-seedance-2-0-260128
doubao-seedance-2-0-fast-260128
doubao-seedance-2-0-mini-260615
doubao-seedance-2-5-260628
dreamina-seedance-2-0-hc
dreamina-seedance-2-0-fast-hc
dreamina-seedance-2-0-mini-hc
dreamina-seedance-2-5-hc

1. 鉴权与分组

所有接口都通过聚合 API 网关调用，请在请求头携带你的 API 令牌（sk- 前缀）：

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API 令牌无效、已停用或缺失时，请求会被网关拒绝。

所有素材接口均可传入 group_id（ak- 前缀），用于指定要操作的素材分组。

group_id 为可选参数。首次上传未传 group_id 时，系统会为当前用户自动创建素材分组；已有分组时会复用当前用户最早启用的分组。实际使用的 group_id 会随响应返回。

POST / PUT：group_id 放在 JSON 请求体中。

GET / DELETE：group_id 放在 URL 查询参数中。

分组不存在或已停用时返回 401 分组不存在或已停用。

传入 group_id 时，只能操作该分组下的素材；不传时，系统会按当前 API 令牌所属用户的素材空间查询或操作。

2. 通用约定

Base URL

https://<聚合 API 网关域名>

下文 cURL 示例使用以下变量：

响应结构

所有接口统一返回如下结构：

{
  "success": true,
  "message": "",
  "data": { ... }
}

success：布尔，true 表示成功，false 表示失败。

message：失败时的错误说明（成功时通常为空）。

data：业务数据，结构见各接口。

素材 ID

上传成功返回的 asset_id 形如 mat_ADyx4iQvkHUy7jDzPKqp，是平台中立的稳定标识。

在视频生成请求里用它引用素材（mat_xxx 或 asset://mat_xxx 均可）。

素材状态（status）

状态	含义	能否用于生成视频
`pending`	处理中（上传/审核未完成）	否，请稍后重试
`ready`	就绪，审核通过	是
`failed`	处理失败（如审核不通过）	否，见 `failure_reason`

状态由后台异步推进，上传后可能先是 pending，稍后通过查询接口变为 ready。

幂等

同一个 group_id 上传同一个 URL 是幂等的：不会重复创建，返回的是同一个 asset_id。（如需修改描述请用更新接口，而非重新上传。）

未传 group_id 时，上传会使用当前用户最早启用的素材分组；如果用户尚无可用分组，系统会自动创建。响应中的 group_id 可用于后续显式指定分组。

3. 接口列表

方法	路径	说明
POST	`/v1/assets/upload`	上传素材（单个或批量）
GET	`/v1/assets`	分页查询已就绪的素材
GET	`/v1/assets/{asset_id}`	查询单个素材状态
PUT	`/v1/assets/{asset_id}`	修改素材描述
DELETE	`/v1/assets/{asset_id}`	删除素材

4. 上传素材

POST /v1/assets/upload

把素材 URL 提交到素材库，返回素材 ID。支持单个 URL 或一次批量多个 URL。

请求参数

参数	类型	必填	说明
`group_id`	string	否	素材分组 ID，`ak-` 前缀；不传时复用用户最早启用的分组，无可用分组时自动创建
`url`	string	二选一	单个素材的公网 URL
`urls`	string[]	二选一	批量素材 URL 列表，单次最多 10 条
`purpose`	string	是	素材用途/描述（缺失时返回 `success=false`、`purpose is required`）
`type`	string	否	素材类型：`image` / `video` / `audio`，默认 `image`

url 与 urls 二选一；同时提供时以 urls 为准。

URL 要求

必须是公网可访问的 http(s) 地址，不支持 localhost、内网/回环 IP、本地文件。

扩展名须在支持范围内（须与 type 匹配）：

图片：jpeg / jpg / png / webp / bmp / tiff / gif / heic

视频：mp4 / mov

音频：wav / mp3

请求示例（单个）

{
  "group_id": "ak-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "url": "https://cdn.example.com/portrait.jpg",
  "type": "image",
  "purpose": "数字人形象"
}

响应示例（单个）

{
  "success": true,
  "message": "",
  "data": {
    "asset_id": "mat_ADyx4iQvkHUy7jDzPKqp",
    "status": "pending",
    "group_id": "ak-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

素材失败时会额外返回 failure_reason：

{
  "success": true,
  "message": "",
  "data": {
    "asset_id": "mat_ADyx4iQvkHUy7jDzPKqp",
    "status": "failed",
    "group_id": "ak-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "failure_reason": "素材审核不通过：图片可能涉及版权限制"
  }
}

failure_reason 只在 status = failed 时出现，给出对客户有意义的原因；若无具体审核原因，则给通用提示「素材处理失败，请稍后重试或更换素材」。

请求示例（批量）

{
  "group_id": "ak-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "urls": [
    "https://cdn.example.com/a.jpg",
    "https://cdn.example.com/b.png"
  ],
  "type": "image",
  "purpose": "批量数字人形象"
}

响应示例（批量）

逐条返回，坏的一条只标错、不影响其余：

{
  "success": true,
  "message": "",
  "data": {
    "assets": [
      { "url": "https://cdn.example.com/a.jpg", "asset_id": "mat_xxx1", "status": "pending" },
      { "url": "https://cdn.example.com/b.png", "error": "URL 文件类型不受支持，请确保 URL 以受支持的扩展名结尾" }
    ],
    "group_id": "ak-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

成功项：{ url, asset_id, status }

失败项：{ url, error }

5. 查询素材列表

GET /v1/assets

分页返回当前用户素材空间内**已就绪（可用于生成视频）**的素材。传入 group_id 时，仅返回指定分组的素材；不传时，返回当前用户全部启用分组中的素材。

查询参数

参数	类型	必填	说明
`group_id`	string	否	素材分组 ID，`ak-` 前缀；不传时查询当前用户全部启用分组
`page`	int	否	页码，默认 1
`page_size`	int	否	每页条数
`purpose`	string	否	按素材描述模糊查询
`sort_order`	string	否	`asc` / `desc`，默认 `desc`

请求示例：

响应示例

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "asset_id": "mat_ADyx4iQvkHUy7jDzPKqp",
        "group_id": "ak-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "type": "image",
        "purpose": "数字人形象",
        "original_url": "https://cdn.example.com/portrait.jpg",
        "status": "ready",
        "created_at": 1751270400
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10
  }
}

说明：列表只包含 ready 的素材。pending / failed 的素材请用「查询单个素材」接口按 asset_id 查看。

6. 查询单个素材

GET /v1/assets/{asset_id}?group_id={group_id}

group_id 可选。不传时，按当前 API 令牌所属用户的素材空间查询。

按素材 ID 查询聚合状态。

响应示例

{
  "success": true,
  "message": "",
  "data": {
    "asset_id": "mat_ADyx4iQvkHUy7jDzPKqp",
    "group_id": "ak-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "type": "image",
    "purpose": "数字人形象",
    "original_url": "https://cdn.example.com/portrait.jpg",
    "status": "ready",
    "created_at": 1751270400
  }
}

失败素材同样附 failure_reason：

{
  "success": true,
  "message": "",
  "data": {
    "asset_id": "mat_ADyx4iQvkHUy7jDzPKqp",
    "group_id": "ak-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "failed",
    "type": "image",
    "purpose": "数字人形象",
    "original_url": "https://cdn.example.com/portrait.jpg",
    "created_at": 1751270400,
    "failure_reason": "素材审核不通过：..."
  }
}

素材不存在或当前用户无权访问 → 404 asset not found。

7. 修改素材描述

PUT /v1/assets/{asset_id}

修改素材的描述（purpose）。不改变素材本身与其状态。

请求参数

参数	类型	必填	说明
`group_id`	string	否	素材分组 ID；不传时按当前用户素材空间操作
`purpose`	string	否	新的素材描述；省略或传空字符串会清空描述

请求示例

{
  "group_id": "ak-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "purpose": "更新后的用途说明"
}

响应示例

{
  "success": true,
  "message": "",
  "data": {
    "asset_id": "mat_ADyx4iQvkHUy7jDzPKqp",
    "group_id": "ak-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "type": "image",
    "purpose": "更新后的用途说明",
    "original_url": "https://cdn.example.com/portrait.jpg",
    "status": "ready",
    "created_at": 1751270400
  }
}

素材不存在或当前用户无权访问 → 404 asset not found。

8. 删除素材

DELETE /v1/assets/{asset_id}?group_id={group_id}

group_id 可选。不传时，按当前 API 令牌所属用户的素材空间操作。

删除素材。删除后该素材 ID 不可再用于生成视频。

响应示例

{
  "success": true,
  "message": "",
  "data": {
    "asset_id": "mat_ADyx4iQvkHUy7jDzPKqp",
    "group_id": "ak-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

素材不存在或当前用户无权访问 → 404 asset not found。

9. 在视频生成里引用素材

上传拿到 mat_xxx 后，在视频生成请求的素材字段里填入 mat_xxx（或 asset://mat_xxx）即可，系统会自动替换为可用引用。支持的承载字段：

顶层 image / images[]

content[] 中每项的 image_url.url / video_url.url / audio_url.url

metadata.first_frame_image / metadata.last_frame_image

metadata.reference_images[] / metadata.reference_videos[] / metadata.reference_audios[]

注意：first_frame_image / last_frame_image / reference_* 必须放在 metadata 下；字段名需与上述一致。
若只是一次性临时素材、无需审核复用，也可以直接把公网 URL 填进上述字段（须公网可达 + 扩展名受支持），无需先上传取 mat_xxx。

10. 错误处理

失败响应：

{
  "success": false,
  "message": "错误说明"
}

常见错误：

场景	HTTP	message
API 令牌无效	401	由聚合 API 网关返回
素材服务配置异常	500	素材服务暂不可用，请联系管理员
素材服务连接失败	502	素材服务连接失败，请稍后重试
分组不存在或已停用	401	分组不存在或已停用
用户身份无效	401	用户身份无效
缺少 `purpose`	200	purpose is required
`type` 非法	200	invalid type, must be image/video/audio
缺少 `url`	200	url is required
批量超过 10 条	200	批量上传单次最多 10 条 URL
URL 非公网地址	200	素材 URL 必须是公网可访问地址…
扩展名不支持	200	URL 文件类型不受支持…
素材不存在/无权访问	404	asset not found

业务参数错误沿用当前接口的统一响应约定：HTTP 状态为 200，通过响应体中的 success: false 和 message 判断失败。鉴权、分组校验及资源不存在等错误使用对应的 HTTP 状态码。

资源库 API 接入文档

真人素材库 · 接口文档#

1. 鉴权与分组#

2. 通用约定#

Base URL#

响应结构#

素材 ID#

素材状态（status）#

幂等#

3. 接口列表#

4. 上传素材#

请求参数#

URL 要求#

请求示例（单个）#

响应示例（单个）#

请求示例（批量）#

响应示例（批量）#

5. 查询素材列表#

查询参数#

响应示例#

6. 查询单个素材#

响应示例#

7. 修改素材描述#

请求参数#

请求示例#

响应示例#

8. 删除素材#

响应示例#

9. 在视频生成里引用素材#

10. 错误处理#

真人素材库 · 接口文档

1. 鉴权与分组

2. 通用约定

Base URL

响应结构

素材 ID

素材状态（status）

幂等

3. 接口列表

4. 上传素材

请求参数

URL 要求

请求示例（单个）

响应示例（单个）

请求示例（批量）

响应示例（批量）

5. 查询素材列表

查询参数

响应示例

6. 查询单个素材

响应示例

7. 修改素材描述

请求参数

请求示例

响应示例

8. 删除素材

响应示例

9. 在视频生成里引用素材

10. 错误处理