火山方舟素材库使用指南
素材库用于把自有的图片、视频、音频提前入库，在生成请求中直接引用素材 ID。对于需要多次复用的虚拟人像形象，提前入库可以让同一形象在多次生成中保持面部、发型与服装等细节一致，也便于按素材组统一管理。
素材归属于上传它的账号，供你在生成请求中引用，具体可见范围以平台实际提供的能力为准。
- 上传素材是异步操作：接口返回成功只表示素材已受理，系统处理可能出现排队，入库完成时间以实际处理进度为准。
- 你需确保上传的素材符合以下条件：
- 素材不包含违反法律法规、违背公序良俗、危害国家安全的内容。
- 你合法拥有该素材，并享有相应的使用权限；素材不包含未获授权的第三方商标、标识类内容。
- 素材不得与任何自然人肖像或形象雷同，不存在抄袭、盗用情形，不侵害任何第三方的人格权、知识产权等合法权益。
整体流程：创建素材组（可选）→ 上传素材 → 等待入库完成 → 在生成时引用素材 ID。
使用前准备
- 开放 API 凭证：素材库接口使用开放 API 的 Access Key / Secret Key，不是控制台的普通 API Key。如需获取凭证或遇到凭证相关问题，请联系运营人员。详见火山方舟素材库 API 概览。
- 容量与配额：
- 入库范围：只入库推理时确实需要复用的素材。一次性参考的文件不必入库。
- 合规前置：素材需通过内容审核才能进入可用状态。上传前请先按内容合规要求自查。
内容合规要求
以下要求需要你在上传前逐项确认，不符合要求的素材将无法进入可用状态：
| 要求 | 具体说明 |
|---|---|
| 内容合法 | 素材不得包含违反法律法规、违背公序良俗、危害国家安全的内容，包括但不限于色情低俗、暴力血腥、恐怖主义、违法广告等。 |
| 权利完整 | 你合法拥有素材，或已取得权利人的相应授权（含肖像权、著作权、商标权）；不得包含未获授权的第三方商标、标识、水印。 |
| 不侵害他人权益 | 素材不得与任何自然人肖像或形象雷同，不得抄袭、盗用他人作品，不得侵害第三方人格权、知识产权等合法权益。 |
| 用途正当 | 不得用于伪造他人身份、制作虚假信息或误导性内容；涉及真实人物形象时，需确保使用场景已获得该人物授权。 |
素材未通过审核时会进入失败状态，可参考常见问题排查。删除重建前请先按上述要求自查，避免重复提交未作修改的素材。
素材库结构说明
- 素材组：素材的管理容器。可以把同一人物、同一品牌 IP 的素材放进同一个素材组，便于检索、批量管理和清理。素材可以不属于任何分组。
- 素材：单个素材文件，支持图片、视频、音频三种类型。入库完成后记录名称、类型、分组、入库状态、大小等元信息。
- 素材 ID：素材的唯一标识，由上传接口返回。生成时用它引用素材，而不是原始文件地址。
- 预览地址：素材的临时访问地址，有效期 1 小时。需要展示素材时实时获取，不要当作永久地址保存。
素材状态
| 状态 | 含义 | 建议操作 |
|---|---|---|
Processing | 已受理，正在下载源文件并异步入库 | 继续轮询，按退避策略控制频率 |
Active | 入库完成 | 记录素材 ID，投入业务使用 |
Failed | 入库失败，常见原因是源地址不可访问、文件损坏或内容审核未通过；可能带有 Error.Code 与 Error.Message | 排查原因后删除重建 |
只有 Active 状态的素材可以用于生成。素材处理是异步的，视频与音频的入库耗时通常明显长于图片，请按异步任务设计轮询与超时，不要假设上传后立即可用。
素材列表接口在未指定 Filter.Statuses 时，只返回 Active 的素材。刚上传的素材处于 Processing，此时查列表看不到它，属于正常现象——这正是需要轮询素材状态而不是查列表判断的原因。
素材格式要求
素材库支持图片、视频、音频三种类型，上传时通过 AssetType 指定（Image / Video / Audio）；不指定时按远端文件的 Content-Type 和文件扩展名推断。字段细节见上传素材。
图片
| 项目 | 要求 |
|---|---|
| 文件格式 | JPG、JPEG、PNG、WEBP、TIF、TIFF、GIF、HEIC、HEIF |
| 宽高像素 | 300 ~ 6000 px |
| 单文件大小 | < 30 MB |
视频与音频
| 类型 | 格式 | 大小 | 时长 |
|---|---|---|---|
| 视频 | MP4、MOV | ≤ 200 MB | 2-30 秒 |
| 音频 | WAV、MP3 | ≤ 15 MB | 2-30 秒 |
无法确认媒体元数据时，入库会失败，失败原因写入素材状态。
人像素材最佳实践
同一人物的图片素材越完整，生成时的面部与服装还原越稳定。以下建议针对人像类图片素材：一个素材组内至少包含一张全身图和一张人脸特写图。
| 类型 | 要求 |
|---|---|
| 全身参考图 | 竖版；人物全身正面；从头顶到脚部完整入画；光线均匀、背景干净 |
| 人脸特写图 | 竖版；肩部以上正面；表情自然；面部约占画面 2/3 |
应避免：大角度侧脸、强逆光或欠曝、重度滤镜与磨皮、多人同框、水印与叠加文字、面部遮挡（口罩、墨镜、手部挡脸）。
接口说明
权限要求
素材库接口沿用火山方舟的 Action、Version 与 V4 签名：所有请求发往同一个入口，通过查询参数 Action 区分操作，Version 固定为 2024-01-01。凭证的 Access Key 用于 Credential，Secret Key 只用于本地计算签名。请求只接受 POST 与 Content-Type: application/json。
V4 签名的构造步骤、X-Date 容差与请求头要求，详见火山方舟素材库 API 概览中的「认证」一节。
接口列表
创建类
| 接口 | 说明 |
|---|---|
| 创建素材分组 | 创建素材组，返回分组 ID |
| 上传素材 | 传入素材公网地址创建素材，返回素材 ID |
管理类
| 接口 | 说明 |
|---|---|
| 分页查询素材 | 按分组、名称、入库状态、一次性标记分页查询 |
| 查询素材详情 | 按素材 ID 查询详情与入库状态，用于轮询 |
| 更新素材 | 修改素材名称 |
| 查询素材分组 | 查询分组列表 |
| 重命名素材分组 | 修改分组名称 |
| 删除素材 | 删除单个素材，或单次最多 100 个批量删除 |
| 删除素材分组 | 删除分组，组内素材一并删除 |
完整字段、取值范围与响应结构见对应接口页；公共的认证方式与错误码见火山方舟素材库 API 概览。
频率限制
每个凭证有每分钟调用上限。触发 QuotaWriteQPMExceeded 表示每分钟写入次数用尽，等到下一分钟重试；触发 AccountFlowLimitExceeded 表示每秒请求上限，约 1 秒后重试。批量上传、批量删除时请控制并发，收到 429 一律按指数退避重试；轮询素材状态时同样优先使用指数退避，而不是固定高频请求。
使用教程
在控制台使用
- 登录 ClawdRouter 控制台，在左侧导航进入「素材库」。
- 点击页面右上角「上传素材」，按页面提示完成上传。
- 在素材列表中查看「入库状态」，等待其变为可用。列表支持按素材名称搜索、按类型与分组筛选。
- 需要整理时，可使用「分组管理」创建分组、通过「移动到分组」归置素材，也可以使用「批量删除」清理不再需要的素材。
控制台与开放 API 操作的是同一份素材库数据，两种方式可以混用。
通过 API 上传
第 1 步：创建素材组（可选） 调用创建素材分组，得到分组 ID。不建分组时素材会处于未分组状态，后续也可以再用更新接口调整。
第 2 步：上传素材 调用上传素材，传入素材的公网 https 地址、名称与分组 ID，得到素材 ID。
需要注意：该接口不接收文件流，只接收可公开访问的地址；链接需要能被服务端直接下载；链接有效期要覆盖下载与处理耗时。
第 3 步：轮询入库状态
调用查询素材详情，轮询素材状态直到 Active。变为 Failed 时停止轮询，按常见问题排查。
第 4 步：用于生成 在生成请求中引用素材 ID。参考素材的字段位置以所用生成接口的定义为准，视频生成见视频生成。
检索与管理
在提示词中指代素材
- 使用「素材类型 + 序号」指代，例如 图片1、视频1、音频1，序号是该类型素材在请求体中的出现顺序。
- 不要在提示词里写素材 ID 或素材地址，模型只理解「图片1」这类指代。
- 一次传多个素材时，先确认顺序，再在提示词中按序号描述。
示例：
图片1中的女主穿着图片2中的外套，站在图片3的街景中，镜头从近景缓慢推到中景。
相关链接
- 火山方舟素材库 API 概览 - 认证、签名与接口索引
- 视频生成 - 提交视频生成任务并下载结果
- 认证鉴权 - 平台 API Key 的获取与使用
- 错误码 - 排查参数错误、鉴权失败与权限问题