素材组管理

素材组是 宁享Token 素材库的容器，用于对同类素材进行逻辑分组（如真人组、AIGC 组）。每个素材必须归属一个素材组。

所有端点使用 API Key（Bearer Token）鉴权，素材组数据按 client_key 隔离。

Base URL

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

列表素材组

GET/api/assets/groups

获取当前 API Key 下的所有素材组列表。

Bearer Token

请求参数

本端点无请求参数。

请求示例

curl /api/assets/groups \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

resp = requests.get(
    "/api/assets/groups",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(resp.json())

响应示例

成功响应

{
  "data": [
    {
      "group_id": "mg-20260930120000-abcde",
      "name": "真人形象组",
      "description": "真人驱动素材",
      "group_type": "LivenessFace",
      "bind_model": "doubao-seedance-2-0",
      "asset_count": 2,
      "status": 1,
      "create_time": "2026-09-30T12:00:00+08:00",
      "update_time": "2026-09-30T12:00:00+08:00"
    },
    {
      "group_id": "mg-20260930120500-fghij",
      "name": "AIGC 形象组",
      "description": "AI 生成形象",
      "group_type": "AIGC",
      "bind_model": "doubao-seedance-2-0",
      "asset_count": 0,
      "status": 1,
      "create_time": "2026-09-30T12:05:00+08:00",
      "update_time": "2026-09-30T12:05:00+08:00"
    }
  ],
  "total": 2,
  "page": 1,
  "page_size": 20
}

group_id 是素材组的对外 ID（mg-<14位时间戳>-<5位小写>），创建、列表、更新、删除与 POST /api/assets、POST /api/assets/upload 的 group_id 全部使用同一个值。 2026-09-30 之前已发出的 group-… 形态继续可用（原样回显，不就地改写）。

创建素材组

POST/api/assets/groups

创建一个新的素材组。

Bearer Token

请求参数

请求参数

参数	类型	必填	默认值	描述
name	string	是	-	素材组名称
type	string	否	AIGC	素材组类型：仅支持 aigc（AI 生成，大小写不敏感；不传时回显 AIGC，传入时按原文回显）。real（真人）不能通过本接口创建——传 real 返回 400，需先完成真人活体认证，认证通过后系统自动创建真人素材组
bind_model	string	是	-	绑定模型名（如 doubao-seedance-2-0）——确保素材可被该模型引用，避免生成时 AssetNotFound。同族模型名亦可（如 doubao-seedance-2-0-yd）
description	string	否	-	素材组描述

请求示例

curl -X POST /api/assets/groups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "AIGC 形象组", "type": "aigc", "bind_model": "doubao-seedance-2-0", "description": "AI 生成形象"}'

响应示例

成功响应

{
  "data": {
    "group_id": "mg-20260930120000-abcde",
    "name": "AIGC 形象组",
    "description": "AI 生成形象",
    "group_type": "aigc",
    "bind_model": "doubao-seedance-2-0",
    "asset_count": 0,
    "status": 1,
    "create_time": "2026-09-30T12:00:00+08:00",
    "update_time": "2026-09-30T12:00:00+08:00"
  }
}

建组成功后，data.group_id 就是该组的对外 ID——后续上传素材、迁移素材、改名、删除都用它。

成功但带警告（bind_model 不在您的模型白名单内）

{
  "data": {
    "group_id": "mg-20260930120500-fghij",
    "name": "AIGC 形象组",
    "description": "",
    "group_type": "AIGC",
    "bind_model": "some-model-not-in-whitelist",
    "asset_count": 0,
    "status": 1,
    "create_time": "2026-09-30T12:05:00+08:00",
    "update_time": "2026-09-30T12:05:00+08:00"
  },
  "warning": "注意：绑定模型 some-model-not-in-whitelist 不在您当前可用模型范围内，素材入库后将无法用于生成，请先在 Key 管理中确认模型白名单"
}

更新素材组

PUT/api/assets/groups/:id

更新素材组信息（名称、描述）。type 不可更改。

Bearer Token

路径参数

路径参数

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

请求参数

请求参数

参数	类型	必填	默认值	描述
name	string	否	-	新的素材组名称
description	string	否	-	新的素材组描述

请求示例

curl -X PUT /api/assets/groups/mg-20260930120000-abcde \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "真人形象组-更新", "description": "更新后的描述"}'

响应示例

成功响应

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

删除素材组

DELETE/api/assets/groups/:id

删除素材组。组内存在素材时无法删除，需先清空或迁移组内素材。

Bearer Token

路径参数

路径参数

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

请求示例

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

响应示例

成功响应

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

错误响应

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

HTTP 状态	error	说明
404	素材组不存在	素材组不存在或不属于当前 API Key
409	组内存在素材，无法删除；请先清空或迁移组内素材	组内仍有素材，需先清空或迁移

相关文档

• 素材库概览
• 素材管理
• 真人活体认证