素材管理

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

接口	路径	鉴权	适用
自有素材库	`/api/business/v1/assets`	API Key 或 JWT	新接入推荐
火山兼容素材	`/api/ark/*`	火山 V4 签名	火山引擎 SDK 迁移

新接入建议用自有素材库（API Key 鉴权，更简单）。火山兼容接口主要为火山迁移用户保留。

本页内容：

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

自有素材库

基础路径 /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"
}

字段	说明
`id`	素材 ID
`url`	原始素材 URL
`asset_type`	素材类型（`Image`/`Video`/`Audio`）
`name`	素材名称
`asset_url`	素材引用地址，格式 `asset://<素材ID>`，用于视频生成引用
`status`	`processing`、`active`、`failed`；仅 `active` 可用

端点

方法	路径	说明
`POST`	`/assets`	创建素材（注册公网 URL）
`GET`	`/assets`	列出素材（分页）
`GET`	`/assets/{asset_id}`	获取单个素材

创建素材

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"
  }'

字段	必填	说明
`url`	是	素材的公开 URL
`asset_type`	是	`Image`、`Video`、`Audio`
`name`	是	素材名称

成功返回 201，响应体为 AssetView。新建后通常先 processing，后续变为 active 或 failed。

列出素材

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

参数	说明
`limit`	每页数量，1-100，默认 20
`cursor`	分页游标，首次不传

获取单个素材

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

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

最小调用流程

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

火山兼容接口

与火山引擎素材管理 API 完全兼容。从火山引擎迁移的客户可继续使用火山引擎官方 SDK，仅需将接入地址指向本平台、凭证换成平台签发的 AK/SK，原有代码无需改动。

项	值
Endpoint	`https://www.silvamux.com/api/ark`
Region	`cn-beijing`
Service	`ark`
鉴权	火山 V4 签名，使用平台签发的 AK/SK
调用方式	`POST /api/ark?Action=<Action>&Version=2024-01-01`

接入准备

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

配置 SDK

将火山引擎 SDK 的 Endpoint 改为 https://www.silvamux.com/api/ark，Region 保持 cn-beijing，凭证填入平台签发的 AK/SK，其余调用代码不变。

client = ArkAssetClient(
    endpoint="https://www.silvamux.com/api/ark",
    access_key_id="<平台签发的 AK>",
    secret_access_key="<平台签发的 SK>",
    region="cn-beijing",
)
# CreateAssetGroup / CreateAsset / GetAsset ... 调用代码不变

支持的操作

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

素材组（AssetGroup）：CreateAssetGroup、GetAssetGroup、ListAssetGroups、UpdateAssetGroup、DeleteAssetGroup。

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

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

重要限制

历史素材不可见：之前通过火山引擎控制台或其它账号上传的素材无法通过本接口访问，需重新上传。
仅支持 AIGC 类型（图片/视频/音频），不支持真人素材（LivenessFace）。
CreateAsset 需提供公网可访问的素材 URL，平台拉取入库。

错误码

Code	含义
`InvalidSignature`	签名校验失败（AK/SK 错、请求被篡改、时钟偏移过大）
`InvalidAction`	不支持的 Action
`MissingParameter.*`	缺少必填字段
`InvalidParameter.*`	字段值非法
`NotFound.asset_id` / `NotFound.project`	素材 / 项目不存在
`SubscriptionRequired`	组织未开通相应能力
`InternalError`	服务内部错误，记录 `RequestId` 联系支持

在视频生成中引用素材

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

{
  "model": "doubao-seedance-1-5-pro-251215",
  "content": [
    {"type": "video_url", "video_url": "asset://asset-123456"},
    {"type": "text", "text": "让画面中的角色跳舞"}
  ]
}

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

能力	火山引擎	SilvaMux	说明
对话（豆包）	`/api/v3/chat/completions`	`POST /api/v3/chat/completions`	协议兼容，改 Base URL + Key，model 用平台调用名
视频生成	`/contents/generations/tasks`	`POST /api/v3/contents/generations/tasks`	自有接口 + API Key，不走 V4 签名
素材管理	火山官方接口	`POST /api/ark/*`（本页）或 `/api/business/v1/assets`	两套可选

视频生成走 API Key，不走 V4 签名。V4 签名仅用于本页素材接口。
API Key（sk_live_）与 AK/SK 在控制台分别创建，不同。
model 用平台调用名（如 doubao-seedance-1-5-pro-251215），不是火山 endpoint ID。
视频生成不支持任务列表/回调，用轮询查询。