素材管理 API 接口文档

本文档描述素材管理模块对外暴露的 HTTP API。对应界面入口为 /console/material（素材管理）。

基础说明

Base URL：https://www.moyu.cn（各接口完整路径见下文「接口与数据表对应总表」）

请求格式：Content-Type: application/json

令牌格式：{32位token}-{userId}，其中 {userId} 为数字。访问令牌取个人设置里的 API 访问令牌（/console/setting）。

统一定义：

success：true 表示请求整体成功；false 表示失败。

失败时返回 {"success": false, "message": "原因"} 与对应 message。

data：成功时返回的具体数据对象，各接口字段见下文。

认证方式

本模块接口使用两种认证，二者不可混用：

认证	Header	适用接口	鉴权中间件
访问令牌	`Authorization: {token}-{userId}`	新建分组、上传素材、分页查询	`UserAuth`

接口

接口	方法	路径	认证
新建分组	POST	`/v1/material/groups`	访问令牌
上传素材	POST	`/v1/material/items/upload`	访问令牌
分页查询素材	POST	`/v1/material/items/list`	访问令牌
获取分组	POST	`/v1/material/groups`	访问令牌

接口 1：新建分组

在素材管理中新建一个素材分组。

请求路径

POST /v1/material/groups

认证头

Authorization: {token}-{userId}

请求参数

参数	类型	必填	默认值	说明
`name`	string	是	-	分组名称

Body 示例：

{
  "name": "API测试分组"
}

响应

成功（200）

{
  "success": true,
  "data": {
    "id": 12,
    "name": "API测试分组",
    "user_id": 326,
    "is_default": false,
    "created_at": "2026-09-09 10:30:00",
    "updated_at": "2026-09-09 10:30:00"
  }
}

字段释义：

字段	说明
`id`	分组 ID（自增主键）
`name`	分组名称
`user_id`	所属用户 ID（即令牌后缀`userId`）
`is_default`	是否默认分组（外部新建恒为`false`）
`created_at`	创建时间
`updated_at`	更新时间

失败

HTTP	场景	响应
400	`name` 为空	`{"success": false, "message": "分组名称不能为空"}`

接口 2：获取分组

在素材管理中新建一个素材分组。

请求路径

GET /v1/material/groups

认证头

Authorization: {token}-{userId}

响应

成功（200）

{
    "data": [
        {
            "id": 1,
            "user_id": 1,
            "name": "我的素材",
            "is_default": true,
            "created_at": 1783475596,
            "item_count": 13
        },
        {
            "id": 15,
            "user_id": 1,
            "name": "API测试分组",
            "is_default": false,
            "created_at": 1788947593,
            "item_count": 3
        }      
    ],
    "success": true
}

字段释义：

字段	说明
`id`	分组 ID（自增主键）
`name`	分组名称
`user_id`	所属用户 ID（即令牌后缀`userId`）
`is_default`	是否默认分组（外部新建恒为`false`）
`created_at`	创建时间
`item_count`	分组素材数量

接口 3：上传素材到分组

通过素材内容将素材上传至指定分组，素材内容支持两种传入方式：在线 URL 或 base64 编码内容（含图片 base64）。

请求路径

POST /v1/material/items/upload

认证头

默认：Authorization: {token}-{userId}

auto_asset=true：额外需 X-Token: Bearer sk-xxx

请求参数

参数	类型	必填	默认值	说明
`group_id`	int	是	-	目标分组 ID
`url`	string	是	-	素材内容。支持在线 URL（http/https 直链）或 base64 内容：`data:image/png;base64,xxxx`（data URI）或纯 base64 字符串
`name`	string	否	空	素材名称；不传则从来源自动提取

url 参数说明：
在线 URL：https://example.com/exa.png，服务端下载文件后入库。
base64 内容（图片）：推荐用 data URI 形式 data:image/png;base64,iVBORw0KGgo...，因带 MIME，服务端可准确识别类型与扩展名。
纯 base64 字符串（无 MIME 前缀）：服务端无法判断媒体类型，目前仅接受带 data: 前缀的 URI 形式；纯 base64 会因无法识别类型被拒绝（返回「不支持的文件类型」）。如需上传图片请使用 data URI 形式。

Body 示例（在线 URL）：

{
  "group_id": 12,
  "url": "https://example.com/exa.png",
  "name": "示例图片",
  "auto_asset": false
}

Body 示例（base64 图片，data URI）：

{
  "group_id": 12,
  "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
  "name": "示例图片"
}

响应

成功（200）

{
  "success": true,
  "data": {
    "id": 88,
    "name": "示例图片",
    "group_id": 12,
    "url": "https://moyu-sass.oss-cn-beijing.aliyuncs.com/exa/11c8b1f.png",
    "file_type": "image",
    "created_at": "2026-09-09 10:30:00",
    "updated_at": "2026-09-09 10:30:00"
  }
}

字段释义：

字段	说明
`id`	素材 ID（自增主键）
`name`	素材名称
`group_id`	所属分组 ID
`url`	素材文件 URL
`file_type`	素材类型（`audio` / `video` / `image`）
`created_at`	创建时间
`updated_at`	更新时间

接口 4：分页查询素材

按分组、名称分页查询当前用户的素材列表。

请求路径

POST /v1/material/items/list

认证头

Authorization: {token}-{userId}

请求参数

参数	类型	必填	默认值	说明
`group_id`	int	否	0	按分组过滤；不传或为 0 表示所有分组
`name`	string	否	空	按名称模糊搜索（`LIKE %name%`）
`page_number`	int	否	1	页码，从 1 开始；小于 1 按 1 处理
`page_size`	int	否	20	每页条数；大于 100 截断为 100

Body 示例：

{
  "group_id": 12,
  "page_number": 1,
  "page_size": 20
}

响应

成功（200）

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 88,
        "name": "示例图片",
        "group_id": 12,
        "url": "https://moyu-sass.oss-cn-beijing.aliyuncs.com/exa/11c8b1f.png",
        "file_type": "image",
        "created_at": "2026-09-09 10:30:00",
        "updated_at": "2026-09-09 10:30:00"
      }
    ],
    "total_count": 1,
    "page_number": 1,
    "page_size": 20
  }
}

字段释义：

字段	说明
`items`	当前页素材列表
`items[].id`	素材 ID
`items[].name`	素材名称
`items[].group_id`	所属分组 ID
`items[].url`	素材文件 URL
`items[].file_type`	素材类型
`items[].volc_channel_count`	该素材关联的活跃火山渠道数
`items[].upstream_url`	该素材的活跃 upstream 地址；无则为空
`items[].created_at`	创建时间
`items[].updated_at`	更新时间
`total_count`	符合条件的总条数
`page_number`	当前页码
`page_size`	当前页大小

完整调用链路

链路 A：新建分组 → 上传素材

POST /v1/material/groups
  Authorization: {token}-{userId}
  {"name": "API测试分组"}
  → 写入 → data.id = 12

POST /v1/material/items/upload
  Authorization: {token}-{userId}
  X-Token: Bearer sk-xxx
  {"group_id": 12, "url": "https://example.com/exa.png", "name": "示例图片"}

链路 B：base64 图片上传

POST /v1/material/items/upload
  Authorization: {token}-{userId}
  {"group_id": 12, "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==", "name": "测试图片"}
  → 解码 base64 → 识别为 image/png → 写入 → data.id = 91, file_type = "image"

链路 C：分页查询

POST /v1/material/items/list
  Authorization: {token}-{userId}
  {"group_id": 12, "page_number": 1, "page_size": 20}

HTTP 状态码汇总

状态码	场景
200	请求成功
400	参数缺失/非法（缺`url`、缺 `name`、分页参数越界处理等）
401	认证失败（令牌无效）
403	权限不足（无权访问分组、令牌分组不在白名单）
404	素材不存在
500	服务器内部错误（下载素材失败等）

基础说明#

认证方式#

接口#

接口 1：新建分组#

请求路径#

认证头#

请求参数#

响应#

接口 2：获取分组#

请求路径#

认证头#

响应#

接口 3：上传素材到分组#

请求路径#

认证头#

请求参数#

响应#

接口 4：分页查询素材#

请求路径#

认证头#

请求参数#

响应#

完整调用链路#

链路 A：新建分组 → 上传素材#

链路 B：base64 图片上传#

链路 C：分页查询#

HTTP 状态码汇总#

基础说明

认证方式

接口

接口 1：新建分组

请求路径

认证头

请求参数

响应

接口 2：获取分组

请求路径

认证头

响应

接口 3：上传素材到分组

请求路径

认证头

请求参数

响应

接口 4：分页查询素材

请求路径

认证头

请求参数

响应

完整调用链路

链路 A：新建分组 → 上传素材

链路 B：base64 图片上传

链路 C：分页查询

HTTP 状态码汇总