素材管理

素材管理用于在视频生成等场景中引用图片/视频/音频素材。平台提供两套素材接口：

自有素材库尚未收录到本次公开 OpenAPI，下方内容仅用于说明已有业务流程，不能作为只依据当前公开文档即可完成的独立接入示例。需要新接入时请先联系 SilvaMux 确认权限与契约。火山兼容素材接口可依据公开 /api/ark OpenAPI 契约接入。

本页内容：

• 自有素材库
• 火山兼容接口
• 在视频生成中引用素材

自有素材库

基础路径 /api/business/v1，认证 Authorization: Bearer sk_live_... 或 JWT。

数据模型（AssetView）

{
  "id": "AST-01JQ8Y7P8R6L7S9T0U1V2W3X4Y",
  "url": "https://example.com/image.png",
  "asset_type": "Image",
  "name": "cover-image",
  "asset_url": "asset://asset-123456",
  "status": "processing",
  "created_at": "2026-03-27T10:00:00Z"
}

端点

创建素材

curl -X POST https://www.silvamux.com/api/business/v1/assets \
  -H "Authorization: Bearer $SILVAMUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/image.png",
    "asset_type": "Image",
    "name": "cover-image"
  }'

成功返回 201，响应体为 AssetView。新建后通常先 processing，后续变为 active、failed 或 timeout。后台每 5 秒轮询 processing 状态的素材，创建超过 24 小时仍未就绪的素材会被标记为 timeout。

列出素材

curl "https://www.silvamux.com/api/business/v1/assets?limit=20" \
  -H "Authorization: Bearer $SILVAMUX_API_KEY"

获取单个素材

curl "https://www.silvamux.com/api/business/v1/assets/AST-01JQ8Y7P8R6L7S9T0U1V2W3X4Y" \
  -H "Authorization: Bearer $SILVAMUX_API_KEY"

常用于轮询素材状态，直到 status 变为 active。

最小调用流程

1. 准备一个外网可访问的素材 URL
2. POST /assets 创建，拿到 id、asset_url
3. 轮询 GET /assets/{id}，直到 status 变为 active
4. 用 asset_url 在视频生成中引用

引用非 active 状态的素材会返回 InvalidParameter.asset_status 错误。请确保素材状态为 active 后再在视频生成中引用。

火山兼容接口

兼容本页列出的火山引擎素材管理操作。从火山引擎迁移的客户可以继续使用对应的火山引擎官方 SDK，将接入地址指向本平台，并将凭证换成平台签发的 AK/SK。

POST https://www.silvamux.com/api/ark
Authorization: HMAC-SHA256 Credential=<AK>/...
Content-Type: application/json

接入准备

1. 控制台 → 凭据管理 → 创建 Volcengine 兼容 (AK/SK) 凭据，一次性返回 AK 与 SK（SK 仅此时可见）。
2. AK/SK 绑定组织，项目通过 ProjectName 字段指定。

配置 SDK

在火山引擎官方 SDK 对应的素材客户端中修改以下配置：

具体客户端类名和初始化方式以所使用的火山引擎 SDK 版本为准。本仓库不提供名为 ArkAssetClient 的独立客户端。

支持的操作

请求体字段名与火山引擎一致（驼峰、首字母大写）。

素材组（AssetGroup）：CreateAssetGroup（仅 AIGC，创建时回填组织级共享火山组 id）、GetAssetGroup、ListAssetGroups、UpdateAssetGroup、DeleteAssetGroup。ListAssetGroups 的 Filter.GroupType 可选，默认 AIGC（仅列 AIGC 组）；传 LivenessFace 列真人组，取其它值返回 InvalidParameter.GroupType。DeleteAssetGroup 对真人组同步删除上游真人火山组（provider_group_id 缺失直接报错），AIGC 组仅清本地（共享组不删）。

素材（Asset）：CreateAsset（GroupId+URL+AssetType+Name，可选 GroupType）GetAsset、ListAssets、UpdateAsset、DeleteAsset。AssetType 可选 Image/Video/Audio。

CreateAsset 的上游组按目标组的类型自动路由：指向 AIGC 组走普通 AIGC 素材入库（上传到组织级 AIGC 火山组）；指向 CreateVisualValidateSession + GetVisualValidateResult 流程返回的 LivenessFace 组即走真人素材入库，上游真人火山组 id 由平台内部解析，客户端无需知晓。完整流程见人像认证（真人活体认证）。

ProjectName 为空或填 default 用默认项目，填其它值按项目名精确匹配。

重要限制

• 历史素材不可见：之前通过火山引擎控制台或其它账号上传的素材无法通过本接口访问，需重新上传。
• 素材类型区分：CreateAsset 指向 AIGC 组走普通 AIGC 素材（图片/视频/音频）；真人素材（LivenessFace）需先走 CreateVisualValidateSession + GetVisualValidateResult 完成活体校验，再把素材上传到返回的 LivenessFace 组，平台按组类型自动路由到真人上游组（见人像认证（真人活体认证））。
• CreateAsset 需提供公网可访问的素材 URL，平台拉取入库。

错误码

在视频生成中引用素材

素材 active 后，用 asset_url（asset://...）在视频生成的 content 中引用：

{
  "model": "<MODEL_CALL_NAME>",
  "content": [
    {"type": "video_url", "video_url": "asset://asset-123456"},
    {"type": "text", "text": "让画面中的角色跳舞"}
  ]
}

迁移要点（火山引擎 → SilvaMux）

• 视频生成走 API Key，不走 V4 签名。V4 签名仅用于本页素材接口。
• API Key（sk_live_）与 AK/SK 在控制台分别创建，不同。
• model 使用模型广场或模型列表展示的真实调用名，不是火山 endpoint ID。
• 视频与 3D 任务支持任务列表、单任务查询和创建时传入 callback_url；字段与鉴权以公开 OpenAPI 契约为准。