素材管理

素材是宁享Token 素材库中的具体媒体对象（图片 / 视频 / 音频）。所有端点使用 API Key（Bearer Token）鉴权，按 client_key 隔离。素材必须归属一个素材组。

Base URL

/  （部署域名，例如 https://your-domain.com）

素材列表

GET/api/assets/list

获取当前 API Key 下的素材列表，支持按素材组、类型过滤与分页。

Bearer Token

请求参数

参数	类型	必填	默认值	描述
group_id	string	否	-	按素材组 ID 过滤
asset_type	string	否	-	按素材类型过滤：`Image` / `Video` / `Audio`（精确匹配，注意首字母大写；旧名 `type` 会被忽略并返回全量）
page	integer	否	1	页码，从 1 开始
page_size	integer	否	20	每页条数，1-100。越界值（0 或 >100）静默回退为 20

分页边界：page_size 传入 0 或大于 100 时不报错，静默回退为默认值 20；合法值（1-100）原样生效。

请求示例

bash

curl "/api/assets/list?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例

响应字段对齐火山 AssetDTO 命名风格（assetId / assetName / assetType / status / createdTime / updatedTime）：

成功响应

json

{
  "data": [
    {
      "assetId": "asset-20260904153000-kqmzr",
      "assetName": "真人形象-01",
      "assetType": "Image",
      "status": "ACTIVE",
      "createdTime": "2026-09-04 15:30:00",
      "updatedTime": "2026-09-04 15:30:22"
    }
  ],
  "total": 50,
  "page": 1,
  "page_size": 20
}

字段	说明
assetId	平台素材 ID，官方引用形态 `asset-<14位时间戳>-<5位小写>`（视频生成 `asset://<assetId>` 引用用这个；系统托管/类真人前置入库路径可能返回 `nxt-asset-*` 存量形态，两种都可用作本组端点的 `:id`）
assetName	素材名称（不填取 URL 文件名）
assetType	`Image` / `Video` / `Audio`
status	火山 AssetStatusEnum：`PROCESSING`（处理中）/ `ACTIVE`（可用）/ `FAILED`（失败）
errorMessage	FAILED 时的可读原因
createdTime / updatedTime	时间格式 `yyyy-MM-dd HH:mm:ss`（火山风格）

获取单个素材

GET/api/assets/:id

获取指定素材的元数据信息。

Bearer Token

路径参数

参数	类型	必填	描述
id	string	是	素材 ID——支持两种形态：`asset-<14位时间戳>-<5位小写>`（平台素材 ID，推荐）或 `ma-<同后缀>`（寻址形态）；`asset://asset-…` 引用串亦可直接传入。删除/更新/下载同

请求示例

bash

curl /api/assets/asset-20260904153000-kqmzr \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例

响应结构与列表一致（火山 AssetDTO 命名风格）：

成功响应

json

{
  "data": {
    "assetId": "asset-20260904153000-kqmzr",
    "assetName": "真人形象-01",
    "assetType": "Image",
    "status": "ACTIVE",
    "createdTime": "2026-09-04 15:30:00",
    "updatedTime": "2026-09-04 15:30:22"
  }
}

已删除的素材返回 404「素材不存在」（删除即不可见）。

创建素材

POST/api/assets

通过公网 URL 引用登记素材（URL 引用模式，对齐火山 Files API）。

Bearer Token

请求头

Content-Type: application/json

说明：本端点采用 URL 引用模式登记素材——你提供素材的公网可访问 URL，平台将其纳入素材库统一管理。对齐火山方舟 Files API 的 URL 上传方式。素材需先归属一个素材组（group_id）。

请求参数

参数	类型	必填	默认值	描述
group_id	string	是	-	所属素材组 ID
url	string	是	-	素材的公网可访问 URL（HTTP/HTTPS）
name	string	否	-	素材名称（不填取 URL 文件名）
asset_type	string	否	`Image`	素材类型：`Image` / `Video` / `Audio`

请求示例

bash

curl -X POST /api/assets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "mg-20260930120000-abcde",
    "url": "https://example.com/face.png",
    "name": "真人形象-01",
    "asset_type": "Image"
  }'

响应示例

成功响应

json

{
  "data": {
    "assetId": "asset-20260930120000-abcde",
    "assetName": "真人形象-01",
    "assetType": "Image",
    "status": "PROCESSING",
    "createdTime": "2026-09-30 12:00:00",
    "updatedTime": "2026-09-30 12:00:00",
    "groupId": "mg-20260930120000-abcde"
  }
}

响应结构与素材列表一致（火山 AssetDTO 命名风格），并额外带回该素材所属素材组的对外 ID（groupId 仅本创建响应带，列表/单个素材响应不含）：
字段说明
assetId 平台素材 ID，常规为 asset-<14位时间戳>-<5位小写>（nxt-asset-* 托管形态亦存在且同样可用）——视频生成 asset://<assetId> 引用请用这个，本地预检存在性并自动改写；亦可用作本组素材端点的 :id
groupId 素材所属素材组的对外 ID（group_id 同源，见创建素材组）——与请求时所用的 group_id 一致，可直接用于后续过滤/建组查询
素材创建后进入 Processing 状态，平台异步入库并轮询状态。完成后在视频生成中用 asset://<assetId> 引用（提交时本地预检并改写为可用引用）。
素材 URL 要求（重要）：
必须为公网可访问的 HTTP/HTTPS 地址（官方要求），平台将通过该 URL 下载素材转存。
上游转存对 301/302 重定向的兼容性有限（实测部分 GitHub raw / jsdelivr 路径拉取失败，picsum 可用）——这是上游转存服务的行为限制而非官方规范承诺，建议使用对象存储/CDN 直链避免踩坑。
素材规格（上游官方约束；本平台不做本地预校验，规格不符将在上游入库阶段失败）：图片 jpeg/png/webp/tiff/gif/heic、单张 ≤30MB、宽高 300~6000px、宽高比 0.4~2.5；视频 mp4/mov、≤200MB、2~30s（宽高比 0.4~2.5、FPS 24~60）；音频 wav/mp3、≤15MB、2~30s。

字段	说明
assetId	平台素材 ID，常规为 `asset-<14位时间戳>-<5位小写>`（`nxt-asset-*` 托管形态亦存在且同样可用）——视频生成 `asset://<assetId>` 引用请用这个，本地预检存在性并自动改写；亦可用作本组素材端点的 `:id`
groupId	素材所属素材组的对外 ID（`group_id` 同源，见创建素材组）——与请求时所用的 `group_id` 一致，可直接用于后续过滤/建组查询

上传素材文件

POST /api/assets/upload（multipart/form-data，Bearer Token 鉴权）直接上传素材文件。

表单字段	类型	必填	默认值	描述
group_id	string	是	-	所属素材组 ID
file	file	是	-	素材文件（当前仅支持图片：png / jpg / jpeg / webp / gif / bmp）
name	string	否	-	素材名称
mode	string	否	`link`	入库模式：`link`（通用）/ `library`（入库优化）/ `real`（真人）

约束与错误：单文件 ≤ 50MB（超限 400 文件超过 50MB 上限）；扩展名非图片 → 400 仅支持图片文件（png/jpg/jpeg/webp/gif/bmp）；缺 group_id → 400 group_id 必填；mode 非法 → 400 mode 取值仅支持 link/library/real。

更新素材

PUT/api/assets/:id

更新素材的名称或所属素材组。文件本身不可通过本端点替换，如需替换请新建素材。

Bearer Token

路径参数

参数	类型	必填	描述
id	string	是	素材 ID

请求参数

参数	类型	必填	默认值	描述
name	string	否	-	新的素材名称
group_id	string	否	-	迁移到新的素材组 ID

请求示例

bash

curl -X PUT /api/assets/asset-20260930120000-abcde \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "真人形象-01-更新"}'

响应示例

成功响应

json

{
  "code": 0,
  "message": "ok"
}

本端点不返回素材对象（无 assetId / group_id / name / type / mime / size / created_at 等键）；如需最新元数据，请随后调 GET /api/assets/:id。请求体仅接受 name 与 group_id 两个字段（没有 description）；两者都为空时返回 400 no fields to update。

删除素材

DELETE/api/assets/:id

删除素材及其底层文件，操作不可恢复。

Bearer Token

路径参数

参数	类型	必填	描述
id	string	是	素材 ID

请求示例

bash

curl -X DELETE /api/assets/asset-20260930120000-abcde \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例

成功响应

json

{
  "code": 0,
  "message": "ok"
}

删除为软删除（素材状态置为 Deleted，不再出现在列表与单个查询中）；本端点不返回 deleted 之类的布尔键。响应结构与更新素材同形。

下载素材

GET/api/assets/:id/download

下载素材原文件，返回二进制流。

Bearer Token

路径参数

参数	类型	必填	描述
id	string	是	素材 ID

请求示例

bash

curl /api/assets/asset-20260930120000-abcde/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o image.png

响应示例

成功响应

返回二进制文件流，Content-Type 为素材的 mime 类型。

Content-Type: image/png
Content-Disposition: attachment; filename="image.png"

<binary data>

错误响应

错误以 {"error": "<message>"} 形式返回（中文描述）：

HTTP 状态	error	说明
404	`素材不存在`	素材不存在或不属于当前 API Key
400	`group_id 与 url 必填`	缺少必填参数

素材管理 ​

Base URL ​

素材列表 ​

请求参数 ​

请求示例 ​

响应示例 ​

获取单个素材 ​

路径参数 ​

请求示例 ​

响应示例 ​

创建素材 ​

请求头 ​

请求参数 ​

请求示例 ​

响应示例 ​

上传素材文件 ​

更新素材 ​

路径参数 ​

请求参数 ​

请求示例 ​

响应示例 ​

删除素材 ​

路径参数 ​

请求示例 ​

响应示例 ​

下载素材 ​

路径参数 ​

请求示例 ​

响应示例 ​

错误响应 ​

相关文档 ​

素材管理

Base URL

素材列表

请求参数

请求示例

响应示例

获取单个素材

路径参数

请求示例

响应示例

创建素材

请求头

请求参数

请求示例

响应示例

上传素材文件

更新素材

路径参数

请求参数

请求示例

响应示例

删除素材

路径参数

请求示例

响应示例

下载素材

路径参数

请求示例

响应示例

错误响应

相关文档