Doubao · 素材库

适用范围

本页介绍 GroupType=AIGC 的私有虚拟人像库。非虚拟人像参考素材通常不需要入库。虚拟人像须具有合法使用权，不能与自然人肖像雷同；真人肖像的授权流程请查看官方人像素材说明。

火山官方指南覆盖 Seedance 2.0 与 2.5 系列；平台模型的素材引用能力、可用项目与权限以账户配置为准。官方直连要求授权函和相关创作权益，平台上游配置不等同于客户需要自行开通火山账号。

平台地址与鉴权

素材管理走 app.ai.kedang.net/ark，请求头直接填写平台 API Key。官网直连示例使用火山 AK/SK 签名，不能把那套鉴权或其他接口的 Bearer 前缀套到本管理入口。

从建组到引用

1. 创建素材组，保存 Result.Id 作为后续的 GroupId。
2. 添加素材，传入公开可访问的文件 URL，保存返回的 Asset ID。
3. 查询素材状态，等待 Result.Status=Active；创建成功只代表请求已受理。
4. 在支持素材库引用的生视频接口中传入 asset://ASSET_ID，使用同一项目的素材和模型。

先检查请求是否成功

管理接口在请求失败时也可能返回 HTTP 200。先检查 ResponseMetadata.Error 是否非空，读取其中的 Code 与 Message；存在请求级错误时停止后续步骤，不把缺少 Result 当作正常结果。ResourceNotFound 表示指定资源不存在。

请求成功后再检查 Result.Status：Failed 是素材的异步处理失败，错误放在 Result.Error。两类错误分别处理，不能只依赖 HTTP 状态或 Error 字段是否存在。错误响应中的 RequestId、Version 可能省略。cURL 示例使用 jq 解析业务错误，运行前需安装。

平台分组与上游字段

平台素材组 ID 使用 CreateAssetGroup 返回的 Result.Id。ListAssets 返回平台的 GroupId 与 ProjectName；GetAsset 的对应字段可能保留上游值，不能直接回填为平台分组或管理项目。

后续管理请求沿用建组时的 ProjectName，默认 default。按组查询使用平台组 ID，素材详情、改名与删除使用素材本身的 ID；不要根据详情返回的上游组 ID 删除素材组。

素材管理接口

入库素材要求

CreateAsset 通过 URL 添加文件，不接收 Base64 或 multipart 文件。素材 URL 必须能被上游下载；签名链接应覆盖下载与排队时间。

图片规格中的边界不包含端点，视频和音频的闭区间包含端点。入库可接受的时长与模型推理限制分别核对，例如 30 秒素材并不表示每个 Seedance 型号都能使用。同一人物建议准备清晰的正面全身图及面部特写，并归入同一素材组。

异步处理与失败判断

GetAsset 的 HTTP 200 不代表操作成功；先检查 ResponseMetadata.Error，再检查 Result.Status。当状态为 Failed，读取 Result.Error.Code 和 Result.Error.Message。视频素材处理通常更慢，官方没有固定入库时限。

在视频中引用素材

官方原生格式将 asset://ASSET_ID 放在 content 对应模态的 url 字段；只使用状态为 Active 的素材。

{
  "content": [
    {
      "type": "text",
      "text": "图片1中的虚拟人物走进花园。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://ASSET_ID"
      },
      "role": "reference_image"
    }
  ]
}

提示词使用“图片1”“视频1”“音频1”，按各模态在请求中的出现顺序编号。素材名称只用于检索，不进入模型提示词，直接在提示词中写 Asset ID 也不能完成引用。

上方是官方原生 content 片段，不是发往 /ark 的请求。平台生视频请求中素材引用的字段映射尚未提供，请先确认所选型号的接入格式。

查看豆包视频接口与型号 → · 官方原生视频参数 ↗

查询与分页

ListAssetGroups 与 ListAssets 都要求 Filter.GroupType。本页新建虚拟人像使用 AIGC；查询接口还定义了 LivenessFace，不代表可用同样方式创建真人素材。

Filter.Name 使用完整名称，不要依赖名称前缀或片段匹配。Filter.GroupIds 填平台素材组 ID；列表为空只表示当前条件没有匹配资源。

推荐 MaxResults 与 NextToken 分页：第一页不填 token，有下一页时原样传回响应 token，响应不再返回 token 时结束。每页 1–100 条，不指定分页参数时默认为 10 条。

兼容分页需同时填写 PageNumber 和 PageSize，不能与 token 分页混用。素材组 PageNumber × PageSize > 10000、素材 > 20000 时改用 token 深翻页。token 分页响应不含 TotalCount、PageNumber、PageSize。

常见问题

LastInferenceTime 是最近一次提交生成任务的时间，后续任务失败也会更新；查询可能延迟 1–2 分钟。缺少该字段不代表素材从未使用。删除前核对业务引用；删除素材组会一并删除组内素材，无法恢复。

容量、费用与限流

平台素材容量、费用和账户限流尚未提供固定值，当前记为 —。下表仅列火山官方账号维度参考，不作为平台配额承诺。

参考资料

火山私有虚拟人像素材库指南 ↗ · 人像素材与授权说明 ↗