资产接口对接规范

1. 文档说明

1.1 文档目标

本文档用于说明本项目“资产能力”相关接口的调用方式、字段约束、返回结构与接入流程，供前端、客户端及外部调用方进行标准化接入。

1.2 适用范围

本规范适用于以下资产类型：

图片资产：Image

音频资产：Audio

视频资产：Video

1.3 接口职责边界

本项目资产接口的职责如下：

接收调用方传入的公网可访问媒体 URL

校验调用参数

代表调用方转调上游资产接口

保存资产本地映射记录

提供资产查询与状态刷新能力

本项目资产接口不承担以下职责：

不接收二进制文件上传

不接收本地文件路径

不负责前端本地文件上传到 OSS / COS / S3 / CDN

不负责生成媒体公网 URL

2. 业务流程

2.1 标准接入流程

调用方应按如下流程接入：

将本地文件上传到调用方自有对象存储或 CDN

获取公网可访问的 http:// 或 https:// 媒体 URL

调用本项目资产组接口创建或选择资产组

调用本项目资产创建接口创建资产

根据返回结果同步等待或异步轮询资产状态

在后续业务流程中使用返回的 provider_asset_id 或 asset_uri

2.2 推荐模式

图片资产

可使用同步等待模式：

wait_for_active = true

音频、视频资产

推荐使用异步轮询模式：

wait_for_active = false

创建成功后再轮询资产详情或刷新接口

3. 认证方式

所有接口均需在请求头中携带认证信息：

支持以下两类凭证：

用户 API Key

登录态 Session Token

4. 通用约定

4.1 Base URL

开发环境示例：

http://127.0.0.1:30000

生产环境请替换为正式服务地址。

4.2 请求格式

创建类接口统一使用 JSON 请求体：

4.3 统一返回结构

成功返回

{
  "success": true,
  "data": {}
}

失败返回

{
  "success": false,
  "message": "错误信息"
}

4.4 时间格式

接口中的时间字段统一为毫秒时间戳，例如：

created_time

updated_time

4.5 资产类型枚举

当前允许的 asset_type 仅包括以下三种：

值	含义
`Image`	图片资产
`Audio`	音频资产
`Video`	视频资产

不支持以下形式：

image_file

audio_file

video_file

img

mp3

mp4

5. 资产组接口

资产必须归属到某个资产组。调用方在创建资产前，应先创建资产组或选择已有资产组。

5.1 创建资产组

请求

请求体

{
  "name": "项目A素材组",
  "description": "用于项目A的图片、音频、视频资产",
  "project_name": "default"
}

请求字段说明

字段	类型	必填	说明
`name`	string	是	资产组名称
`description`	string	否	资产组描述
`project_name`	string	否	项目标识，默认 `default`

成功返回示例

{
  "success": true,
  "data": {
    "id": 1,
    "provider_group_id": "group-202603190001-abcde",
    "name": "项目A素材组",
    "description": "用于项目A的图片、音频、视频资产",
    "group_type": "AIGC",
    "project_name": "default",
    "created_time": 1742360000000,
    "updated_time": 1742360000000,
    "raw": {
      "Id": "group-202603190001-abcde"
    }
  }
}

5.2 查询资产组列表

请求

查询参数

字段	类型	必填	说明
`page`	number	否	页码，默认 `1`
`page_size`	number	否	每页数量，默认 `20`，最大 `100`
`name`	string	否	按名称或描述搜索

成功返回示例

{
  "success": true,
  "data": [
    {
      "id": 1,
      "provider_group_id": "group-202603190001-abcde",
      "name": "项目A素材组",
      "description": "用于项目A的图片、音频、视频资产",
      "group_type": "AIGC",
      "project_name": "default",
      "created_time": 1742360000000,
      "updated_time": 1742360000000,
      "raw": {
        "Id": "group-202603190001-abcde"
      }
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "page_size": 20,
    "total_pages": 1
  }
}

5.3 查询单个资产组

请求

路径参数说明

id 支持两种形式：

本地资产组 ID，例如 1

上游资产组 ID，例如 group-202603190001-abcde

示例

或：

6. 资产接口

6.1 创建资产

该接口用于根据公网媒体 URL 创建图片、音频或视频资产。

请求

请求体示例

图片

{
  "group_id": 1,
  "url": "https://your-cdn.com/media/test-image.png",
  "name": "封面图",
  "asset_type": "Image",
  "project_name": "default",
  "wait_for_active": true,
  "timeout_ms": 120000
}

音频

{
  "group_id": 1,
  "url": "https://your-cdn.com/media/test-audio.mp3",
  "name": "背景音频",
  "asset_type": "Audio",
  "project_name": "default",
  "wait_for_active": false,
  "timeout_ms": 120000
}

视频

{
  "group_id": 1,
  "url": "https://your-cdn.com/media/test-video.mp4",
  "name": "演示视频",
  "asset_type": "Video",
  "project_name": "default",
  "wait_for_active": false,
  "timeout_ms": 120000
}

请求字段说明

字段	类型	必填	说明
`group_id`	string \| number	否	本地资产组 ID，推荐优先传该字段
`provider_group_id`	string \| number	否	上游资产组 ID，可作为 `group_id` 替代字段
`url`	string	否	公网可访问媒体 URL，推荐优先使用该字段
`source_url`	string	否	`url` 的兼容别名
`name`	string	否	资产名称
`asset_type`	string	否	`Image` / `Audio` / `Video`，默认 `Image`
`project_name`	string	否	项目标识，默认 `default`
`wait_for_active`	boolean	否	是否等待状态进入 `Active` 后再返回
`timeout_ms`	number	否	等待超时时间，单位毫秒，默认约 `120000`

参数约束

资产组参数

调用方至少需要传入以下其中之一：

group_id

provider_group_id

否则无法定位资产归属的资产组。

URL 参数

调用方至少需要传入以下其中之一：

url

source_url

URL 必须满足以下要求：

必须以 http:// 或 https:// 开头

必须为公网可访问地址

上游服务必须能够直接下载

不能为本地路径

不能为 blob URL

不能为 data URL

错误示例：

file:///Users/test/a.png

blob:http://localhost/...

data:image/png;base64,...

C:\test\a.png

正确示例：

https://cdn.example.com/assets/a.png

https://cdn.example.com/assets/a.mp3

https://cdn.example.com/assets/a.mp4

资产类型参数

asset_type 当前仅允许以下值：

Image

Audio

Video

若传入其他值，接口将直接返回 400。

等待策略

当 wait_for_active = true 时：

接口在创建资产后不会立即返回

后端将轮询上游资产状态

若状态变为 Active，则返回最新资产信息

若达到 timeout_ms 仍未 Active，则按当前状态返回或报错，具体取决于上游状态与轮询结果

当 wait_for_active = false 时：

接口创建成功后会立即返回

返回结果中的状态通常为 Processing

调用方需要自行轮询详情或刷新接口

成功返回示例

{
  "success": true,
  "data": {
    "id": 12,
    "local_group_id": 1,
    "provider_group_id": "group-202603190001-abcde",
    "provider_asset_id": "asset-202603190010-fghij",
    "asset_uri": "Asset://asset-202603190010-fghij",
    "name": "演示视频",
    "source_url": "https://your-cdn.com/media/test-video.mp4",
    "provider_url": "https://provider.example.com/media/xxx",
    "asset_type": "Video",
    "status": "Processing",
    "error_code": "",
    "error_message": "",
    "project_name": "default",
    "created_time": 1742360100000,
    "updated_time": 1742360103000,
    "raw": {
      "Id": "asset-202603190010-fghij",
      "Status": "Processing"
    }
  }
}

返回字段说明

字段	类型	说明
`id`	number	本地资产记录 ID
`local_group_id`	number	本地资产组 ID
`provider_group_id`	string	上游资产组 ID
`provider_asset_id`	string	上游资产 ID
`asset_uri`	string	资产 URI，格式通常为 `Asset://...`
`name`	string	资产名称
`source_url`	string	调用方传入的原始媒体 URL
`provider_url`	string	上游返回的资源 URL，可能为空
`asset_type`	string	资产类型，固定返回 `Image` / `Audio` / `Video` 之一
`status`	string	当前资产状态
`error_code`	string	错误码
`error_message`	string	错误信息
`project_name`	string	项目名
`created_time`	number	创建时间戳（毫秒）
`updated_time`	number	更新时间戳（毫秒）
`raw`	object	上游原始返回对象

常见错误返回

资产组不存在

{
  "success": false,
  "message": "素材组不存在或不属于当前用户"
}

URL 非法

{
  "success": false,
  "message": "素材 URL 必须是公网可访问的 http/https 地址"
}

资产类型非法

{
  "success": false,
  "message": "asset_type 仅支持 Image、Audio、Video"
}

上游创建失败

{
  "success": false,
  "message": "创建素材失败：上游返回的具体错误"
}

6.2 查询资产列表

请求

查询参数

字段	类型	必填	说明
`page`	number	否	页码，默认 `1`
`page_size`	number	否	每页数量，默认 `20`，最大 `100`
`name`	string	否	按名称、URL 或资产 ID 搜索
`status`	string	否	按资产状态筛选
`group_id`	string \| number	否	本地资产组 ID 或上游资产组 ID
`refresh`	0 \| 1	否	传 `1` 时，后端会尝试刷新当前页资产状态

成功返回示例

{
  "success": true,
  "data": [
    {
      "id": 12,
      "local_group_id": 1,
      "provider_group_id": "group-202603190001-abcde",
      "provider_asset_id": "asset-202603190010-fghij",
      "asset_uri": "Asset://asset-202603190010-fghij",
      "name": "演示视频",
      "source_url": "https://your-cdn.com/media/test-video.mp4",
      "provider_url": "https://provider.example.com/media/xxx",
      "asset_type": "Video",
      "status": "Active",
      "error_code": "",
      "error_message": "",
      "project_name": "default",
      "created_time": 1742360100000,
      "updated_time": 1742360103000,
      "raw": {
        "Id": "asset-202603190010-fghij",
        "Status": "Active"
      }
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "page_size": 20,
    "total_pages": 1
  }
}

6.3 查询单个资产详情

请求

路径参数说明

id 支持两种形式：

本地资产记录 ID，例如 12

上游资产 ID，例如 asset-202603190010-fghij

示例

或：

成功返回示例

{
  "success": true,
  "data": {
    "id": 12,
    "local_group_id": 1,
    "provider_group_id": "group-202603190001-abcde",
    "provider_asset_id": "asset-202603190010-fghij",
    "asset_uri": "Asset://asset-202603190010-fghij",
    "name": "演示视频",
    "source_url": "https://your-cdn.com/media/test-video.mp4",
    "provider_url": "https://provider.example.com/media/xxx",
    "asset_type": "Video",
    "status": "Active",
    "error_code": "",
    "error_message": "",
    "project_name": "default",
    "created_time": 1742360100000,
    "updated_time": 1742360103000,
    "raw": {
      "Id": "asset-202603190010-fghij",
      "Status": "Active"
    }
  }
}

6.4 主动刷新资产状态

请求

请求体

{}

示例

成功返回示例

{
  "success": true,
  "data": {
    "id": 12,
    "local_group_id": 1,
    "provider_group_id": "group-202603190001-abcde",
    "provider_asset_id": "asset-202603190010-fghij",
    "asset_uri": "Asset://asset-202603190010-fghij",
    "name": "演示视频",
    "source_url": "https://your-cdn.com/media/test-video.mp4",
    "provider_url": "https://provider.example.com/media/xxx",
    "asset_type": "Video",
    "status": "Active",
    "error_code": "",
    "error_message": "",
    "project_name": "default",
    "created_time": 1742360100000,
    "updated_time": 1742360200000,
    "raw": {
      "Id": "asset-202603190010-fghij",
      "Status": "Active"
    }
  }
}

7. 资产状态说明

当前接口常见状态如下：

状态	含义
`Processing`	资产已提交，上游仍在处理中
`Active`	资产已可用
`Failed`	资产处理失败
`deleted`	资产已删除或不可用

调用方建议按以下原则处理：

Processing：继续轮询

Active：视为可用资产

Failed：展示错误信息并中止后续流程

deleted：视为无效资产，不再继续引用

8. 推荐调用策略

8.1 异步模式

适用于音频、视频资产。

步骤

调用 POST /api/user/volc-assets

请求体中传：

{
  "wait_for_active": false
}

创建成功后，记录返回的本地 id

调用以下接口轮询状态：

或：

直到状态变为 Active 或 Failed

8.2 同步模式

适用于图片资产，或调用方希望在一次请求中尽量拿到最终状态的场景。

请求示例

{
  "group_id": 1,
  "url": "https://your-cdn.com/media/test-image.png",
  "name": "图片",
  "asset_type": "Image",
  "wait_for_active": true,
  "timeout_ms": 120000
}

9. 前端或客户端字段映射建议

建议调用方使用如下类型定义管理数据模型。

9.1 资产类型

export type AssetType = 'Image' | 'Audio' | 'Video'

9.2 创建资产请求

export interface CreateAssetRequest {
  group_id?: number | string
  provider_group_id?: number | string
  url?: string
  source_url?: string
  name?: string
  asset_type?: AssetType
  project_name?: string
  wait_for_active?: boolean
  timeout_ms?: number
}

9.3 资产返回对象

export interface AssetItem {
  id: number
  local_group_id: number
  provider_group_id: string
  provider_asset_id: string
  asset_uri: string
  name: string
  source_url: string
  provider_url: string
  asset_type: AssetType
  status: string
  error_code: string
  error_message: string
  project_name: string
  created_time: number
  updated_time: number
  raw: Record<string, any>
}

9.4 通用返回结构

export interface ApiResponse<T> {
  success: boolean
  message?: string
  data: T
  meta?: {
    total: number
    page: number
    page_size: number
    total_pages: number
  }
}

10. 错误处理规范

调用方至少应处理以下错误场景：

10.1 URL 非法

示例：

{
  "success": false,
  "message": "素材 URL 必须是公网可访问的 http/https 地址"
}

10.2 资产类型非法

示例：

{
  "success": false,
  "message": "asset_type 仅支持 Image、Audio、Video"
}

10.3 资产组不存在

示例：

{
  "success": false,
  "message": "素材组不存在或不属于当前用户"
}

10.4 上游处理失败

可能表现为：

创建接口直接失败并返回 message

创建成功但后续状态为 Failed

详情接口中 error_message 有值

调用方展示错误时，建议优先级如下：

使用 error_message

若无 error_message，使用 message

若仍无可展示内容，展示统一兜底错误提示

11. 接入检查清单

接入完成前，请确认以下事项：

已能够创建资产组

已能够查询资产组列表

已能够调用资产创建接口

已能够按类型传 Image / Audio / Video

已确保上传到调用方自有存储后得到公网 URL

未向资产接口传本地路径或二进制文件

已完成资产状态轮询逻辑

已处理 Processing / Active / Failed / deleted 状态

已处理接口失败与上游失败场景

12. 最小可运行示例

12.1 创建视频资产

{
  "group_id": 1,
  "url": "https://cdn.example.com/assets/demo.mp4",
  "name": "宣传视频",
  "asset_type": "Video",
  "project_name": "default",
  "wait_for_active": false
}

12.2 刷新视频资产状态

{}

12.3 创建音频资产

{
  "group_id": 1,
  "url": "https://cdn.example.com/assets/bgm.mp3",
  "name": "背景音乐",
  "asset_type": "Audio",
  "project_name": "default",
  "wait_for_active": false
}

12.4 创建图片资产

{
  "group_id": 1,
  "url": "https://cdn.example.com/assets/cover.png",
  "name": "封面图",
  "asset_type": "Image",
  "project_name": "default",
  "wait_for_active": true,
  "timeout_ms": 120000
}

资产库调用接口文档

资产接口对接规范#

1. 文档说明#

1.1 文档目标#

1.2 适用范围#

1.3 接口职责边界#

2. 业务流程#

2.1 标准接入流程#

2.2 推荐模式#

图片资产#

音频、视频资产#

3. 认证方式#

4. 通用约定#

4.1 Base URL#

4.2 请求格式#

4.3 统一返回结构#

成功返回#

失败返回#

4.4 时间格式#

4.5 资产类型枚举#

5. 资产组接口#

5.1 创建资产组#

请求#

请求体#

请求字段说明#

成功返回示例#

5.2 查询资产组列表#

请求#

查询参数#

成功返回示例#

5.3 查询单个资产组#

请求#

路径参数说明#

示例#

6. 资产接口#

6.1 创建资产#

请求#

请求体示例#

图片#

音频#

视频#

请求字段说明#

参数约束#

资产组参数#

URL 参数#

资产类型参数#

等待策略#

成功返回示例#

返回字段说明#

常见错误返回#

资产组不存在#

URL 非法#

资产类型非法#

上游创建失败#

6.2 查询资产列表#

请求#

查询参数#

成功返回示例#

6.3 查询单个资产详情#

请求#

路径参数说明#

示例#

成功返回示例#

6.4 主动刷新资产状态#

请求#

请求体#

示例#

成功返回示例#

7. 资产状态说明#

8. 推荐调用策略#

8.1 异步模式#

步骤#

8.2 同步模式#

请求示例#

9. 前端或客户端字段映射建议#

9.1 资产类型#

9.2 创建资产请求#

9.3 资产返回对象#

9.4 通用返回结构#

10. 错误处理规范#

资产接口对接规范

1. 文档说明

1.1 文档目标

1.2 适用范围

1.3 接口职责边界

2. 业务流程

2.1 标准接入流程

2.2 推荐模式

图片资产

音频、视频资产

3. 认证方式

4. 通用约定

4.1 Base URL

4.2 请求格式

4.3 统一返回结构

成功返回

失败返回

4.4 时间格式

4.5 资产类型枚举

5. 资产组接口

5.1 创建资产组

请求

请求体

请求字段说明

成功返回示例

5.2 查询资产组列表

请求

查询参数

成功返回示例

5.3 查询单个资产组

请求

路径参数说明

示例

6. 资产接口

6.1 创建资产

请求

请求体示例

图片

音频

视频

请求字段说明

参数约束

资产组参数

URL 参数

资产类型参数

等待策略

成功返回示例

返回字段说明

常见错误返回

资产组不存在

URL 非法

资产类型非法

上游创建失败

6.2 查询资产列表

请求

查询参数

成功返回示例

6.3 查询单个资产详情

请求

路径参数说明

示例

成功返回示例

6.4 主动刷新资产状态

请求

请求体

示例

成功返回示例

7. 资产状态说明

8. 推荐调用策略

8.1 异步模式

步骤

8.2 同步模式

请求示例

9. 前端或客户端字段映射建议

9.1 资产类型

9.2 创建资产请求

9.3 资产返回对象

9.4 通用返回结构

10. 错误处理规范

10.1 URL 非法