移动云 Seedance 素材接口

约 2502 字大约 8 分钟

移动云 Seedance 素材接口用于管理视频生成所需的素材组、真人认证素材组和 AICC 素材。客户端只需要使用 FrameAI 分发的 API Key。

所有接口统一返回 code、data、msg：

{
  "code": 0,
  "data": {},
  "msg": "success"
}

公共请求头

Authorization: Bearer sk-frameai-xxxxxxxx
Content-Type: application/json

GET 请求不需要发送 Content-Type。示例中的 https://mivsub.com 代表你的 FrameAI 公网地址。

接口总览

分组	方法	路径	说明
素材组	`GET`	`/api/v1/aicc/asset-groups`	查询素材组列表
素材组	`GET`	`/api/v1/aicc/asset-groups/{group_id}`	查询素材组详情
素材组	`POST`	`/api/v1/aicc/asset-groups`	创建素材组
素材组	`PUT`	`/api/v1/aicc/asset-groups/{group_id}`	更新素材组
素材组	`DELETE`	`/api/v1/aicc/asset-groups/{group_id}`	删除素材组
真人认证	`POST`	`/api/v1/aicc/real-person-auth/sessions`	创建真人认证 H5 会话
真人认证	`POST`	`/api/v1/aicc/real-person-auth/asset-group`	获取并绑定真人素材组
AICC 素材	`GET`	`/api/v1/aicc/assets`	查询素材列表
AICC 素材	`POST`	`/api/v1/aicc/assets`	创建素材
AICC 素材	`GET`	`/api/v1/aicc/assets/{asset_id}`	查询素材详情
AICC 素材	`PUT`	`/api/v1/aicc/assets/{asset_id}`	更新素材
AICC 素材	`DELETE`	`/api/v1/aicc/assets/{asset_id}`	删除素材

素材组

查询素材组列表

GET https://mivsub.com/api/v1/aicc/asset-groups?page=1&page_size=20&group_type=AIGC&group_name=测试
Authorization: Bearer sk-frameai-xxxxxxxx

查询参数：

参数	类型	必填	说明
`page`	integer	否	页码，默认 `1`
`page_size`	integer	否	每页数量，默认 `20`
`group_type`	string	否	`AIGC` 或 `LivenessFace`
`group_name`	string	否	名称模糊查询，最长 64 字符

响应字段：

字段	类型	说明
`code`	integer/string	FrameAI 标准响应码，成功通常为 `0`
`data.list`	array	素材组列表
`data.list[].group_id`	string	素材组 ID
`data.list[].group_type`	string	素材组类型，`AIGC` 或 `LivenessFace`
`data.list[].group_name`	string	素材组名称
`data.list[].description`	string	素材组说明
`data.list[].is_default`	boolean	是否为默认素材组
`data.total`	integer	总数量
`data.page`	integer	当前页码
`data.page_size`	integer	每页数量
`msg`	string	响应消息

{
  "code": 0,
  "data": {
    "list": [
      {
        "group_id": "volcano-group-xxx",
        "group_type": "AIGC",
        "group_name": "我的素材组",
        "description": "用于视频生成",
        "is_default": true
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  },
  "msg": "success"
}

查询素材组详情

GET https://mivsub.com/api/v1/aicc/asset-groups/volcano-group-xxx
Authorization: Bearer sk-frameai-xxxxxxxx

路径参数：

参数	类型	必填	说明
`group_id`	string	是	素材组 ID

响应字段：

字段	类型	说明
`code`	integer/string	FrameAI 标准响应码，成功通常为 `0`
`data.group_id`	string	素材组 ID
`data.group_type`	string	素材组类型，`AIGC` 或 `LivenessFace`
`data.group_name`	string	素材组名称
`data.description`	string	素材组说明
`data.is_default`	boolean	是否为默认素材组
`msg`	string	响应消息

{
  "code": 0,
  "data": {
    "group_id": "volcano-group-xxx",
    "group_type": "AIGC",
    "group_name": "我的素材组",
    "description": "用于视频生成",
    "is_default": true
  },
  "msg": "success"
}

创建素材组

POST https://mivsub.com/api/v1/aicc/asset-groups
Authorization: Bearer sk-frameai-xxxxxxxx
Content-Type: application/json

请求体：

字段	类型	必填	说明
`group_type`	string	是	创建时固定为 `AIGC`
`group_name`	string	是	素材组名称，最长 64 字符
`description`	string	否	素材组说明
`is_default`	boolean	否	是否设置为默认素材组

{
  "group_type": "AIGC",
  "group_name": "我的素材组",
  "description": "用于视频生成",
  "is_default": true
}

响应字段：

字段	类型	说明
`code`	integer/string	FrameAI 标准响应码，成功通常为 `0`
`data.group_id`	string	新创建的素材组 ID
`data.group_type`	string	素材组类型，固定为 `AIGC`
`data.group_name`	string	素材组名称
`data.description`	string	素材组说明
`data.is_default`	boolean	是否为默认素材组
`msg`	string	响应消息

{
  "code": 0,
  "data": {
    "group_id": "volcano-group-xxx",
    "group_type": "AIGC",
    "group_name": "我的素材组",
    "description": "用于视频生成",
    "is_default": true
  },
  "msg": "success"
}

更新素材组

PUT https://mivsub.com/api/v1/aicc/asset-groups/volcano-group-xxx
Authorization: Bearer sk-frameai-xxxxxxxx
Content-Type: application/json

请求体至少提供 group_name 或 description：

{
  "group_name": "新素材组名称",
  "description": "更新后的素材组说明"
}

响应字段：

字段	类型	说明
`code`	integer/string	FrameAI 标准响应码，成功通常为 `0`
`data.group_id`	string	素材组 ID
`data.group_name`	string	更新后的素材组名称
`data.description`	string	更新后的素材组说明
`msg`	string	响应消息

{
  "code": 0,
  "data": {
    "group_id": "volcano-group-xxx",
    "group_name": "新素材组名称",
    "description": "更新后的素材组说明"
  },
  "msg": "success"
}

删除素材组

DELETE https://mivsub.com/api/v1/aicc/asset-groups/volcano-group-xxx
Authorization: Bearer sk-frameai-xxxxxxxx

响应字段：

字段	类型	说明
`code`	integer/string	FrameAI 标准响应码，成功通常为 `0`
`data.group_id`	string	被删除的素材组 ID
`data.deleted`	boolean	是否删除成功
`msg`	string	响应消息

{
  "code": 0,
  "data": {
    "group_id": "volcano-group-xxx",
    "deleted": true
  },
  "msg": "success"
}

真人认证

创建真人认证 H5 会话

POST https://mivsub.com/api/v1/aicc/real-person-auth/sessions
Authorization: Bearer sk-frameai-xxxxxxxx

无需请求体。接口返回 byted_token 和 H5 链接，调用方需要引导用户在手机端完成活体检测。认证成功后，再使用 byted_token 获取并绑定真人素材组。

响应字段：

字段	类型	说明
`code`	integer/string	FrameAI 标准响应码，成功通常为 `0`
`data.byted_token`	string	真人认证会话 token
`data.h5_link`	string	真人认证 H5 链接
`data.expires_in`	integer	链接有效期，单位秒
`msg`	string	响应消息

{
  "code": 0,
  "data": {
    "byted_token": "token-xxx",
    "h5_link": "https://example.com/auth",
    "expires_in": 1800
  },
  "msg": "success"
}

获取并绑定真人素材组

POST https://mivsub.com/api/v1/aicc/real-person-auth/asset-group
Authorization: Bearer sk-frameai-xxxxxxxx
Content-Type: application/json

请求体：

字段	类型	必填	说明
`byted_token`	string	是	创建认证会话返回的 `byted_token`

{
  "byted_token": "token-xxx"
}

响应字段：

字段	类型	说明
`code`	integer/string	FrameAI 标准响应码，成功通常为 `0`
`data.group_id`	string	绑定成功后的真人素材组 ID
`data.group_type`	string	素材组类型，通常为 `LivenessFace`
`data.group_name`	string	真人素材组名称
`data.byted_token`	string	本次绑定使用的认证 token
`msg`	string	响应消息

{
  "code": 0,
  "data": {
    "group_id": "volcano-real-group-xxx",
    "group_type": "LivenessFace",
    "group_name": "真人素材组",
    "byted_token": "token-xxx"
  },
  "msg": "success"
}

绑定成功后返回的 group_id 用于后续真人素材创建和视频生成。

AICC 素材

查询素材列表

GET https://mivsub.com/api/v1/aicc/assets?page=1&page_size=20&group_type=AIGC&asset_name=测试&status=ACTIVE
Authorization: Bearer sk-frameai-xxxxxxxx

查询参数：

参数	类型	必填	说明
`page`	integer	否	页码，默认 `1`
`page_size`	integer	否	每页数量，默认 `20`
`group_type`	string	否	`AIGC` 或 `LivenessFace`
`asset_name`	string	否	名称模糊查询，最长 64 字符
`status`	string	否	逗号分隔：`PROCESSING`（审核中）、`ACTIVE`（审核通过）、`FAILED`（审核失败）
状态枚举：

值	含义
`PROCESSING`	审核中
`ACTIVE`	审核通过
`FAILED`	审核失败

响应字段：

字段	类型	说明
`code`	integer/string	FrameAI 标准响应码，成功通常为 `0`
`data.list`	array	素材列表
`data.list[].asset_id`	string	素材 ID
`data.list[].group_id`	string	所属素材组 ID
`data.list[].asset_name`	string	素材名称
`data.list[].asset_type`	string	素材类型，`Image`、`Video` 或 `Audio`
`data.list[].status`	string	素材状态：`PROCESSING`（审核中）、`ACTIVE`（审核通过）、`FAILED`（审核失败）
`data.list[].asset_url`	string	素材访问地址；状态可用时返回
`data.total`	integer	总数量
`data.page`	integer	当前页码
`data.page_size`	integer	每页数量
`msg`	string	响应消息

{
  "code": 0,
  "data": {
    "list": [
      {
        "asset_id": "volcano-asset-xxx",
        "group_id": "volcano-group-xxx",
        "asset_name": "产品介绍视频",
        "asset_type": "Video",
        "status": "ACTIVE",
        "asset_url": "https://signed.example.com/asset.mp4"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  },
  "msg": "success"
}

创建素材

POST https://mivsub.com/api/v1/aicc/assets
Authorization: Bearer sk-frameai-xxxxxxxx
Content-Type: application/json

请求体：

字段	类型	必填	说明
`group_id`	string	是	当前用户可访问的素材组 ID
`asset_name`	string	是	素材名称，最长 64 字符
`asset_url`	string	是	公网 HTTP(S) URL，不支持文件直传
`asset_type`	string	是	`Image`、`Video`、`Audio`

{
  "group_id": "volcano-group-xxx",
  "asset_name": "产品介绍视频",
  "asset_url": "https://example.com/product.mp4",
  "asset_type": "Video"
}

创建是异步入库过程，成功响应字段：

字段	类型	说明
`code`	integer/string	FrameAI 标准响应码，成功通常为 `0`
`data.asset_id`	string	新创建的素材 ID
`data.group_id`	string	所属素材组 ID
`data.status`	string	素材入库状态，创建后通常为 `PROCESSING`（审核中）
`msg`	string	响应消息

成功响应示例：

{
  "code": 0,
  "data": {
    "asset_id": "volcano-asset-xxx",
    "group_id": "volcano-group-xxx",
    "status": "PROCESSING"
  },
  "msg": "success"
}

查询素材详情

GET https://mivsub.com/api/v1/aicc/assets/volcano-asset-xxx
Authorization: Bearer sk-frameai-xxxxxxxx

响应字段：

字段	类型	说明
`code`	integer/string	FrameAI 标准响应码，成功通常为 `0`
`data.asset_id`	string	素材 ID
`data.group_id`	string	所属素材组 ID
`data.asset_name`	string	素材名称
`data.asset_type`	string	素材类型，`Image`、`Video` 或 `Audio`
`data.status`	string	素材状态：`PROCESSING`（审核中）、`ACTIVE`（审核通过）、`FAILED`（审核失败）
`data.asset_url`	string	素材访问地址；状态可用时返回
`msg`	string	响应消息

响应示例：

{
  "code": 0,
  "data": {
    "asset_id": "volcano-asset-xxx",
    "group_id": "volcano-group-xxx",
    "asset_name": "产品介绍视频",
    "asset_type": "Video",
    "status": "ACTIVE",
    "asset_url": "https://signed.example.com/asset.mp4"
  },
  "msg": "success"
}

asset_url 是临时预签名 URL，不应作为长期存储地址。

更新素材

PUT https://mivsub.com/api/v1/aicc/assets/volcano-asset-xxx
Authorization: Bearer sk-frameai-xxxxxxxx
Content-Type: application/json

只能更新素材名称。素材类型、素材地址和所属素材组不可通过此接口修改。

{
  "asset_name": "新素材名称"
}

响应字段：

字段	类型	说明
`code`	integer/string	FrameAI 标准响应码，成功通常为 `0`
`data.asset_id`	string	素材 ID
`data.asset_name`	string	更新后的素材名称
`data.status`	string	素材状态，通常为 `ACTIVE`（审核通过）
`msg`	string	响应消息

响应示例：

{
  "code": 0,
  "data": {
    "asset_id": "volcano-asset-xxx",
    "asset_name": "新素材名称",
    "status": "ACTIVE"
  },
  "msg": "success"
}

删除素材

DELETE https://mivsub.com/api/v1/aicc/assets/volcano-asset-xxx
Authorization: Bearer sk-frameai-xxxxxxxx

响应字段：

字段	类型	说明
`code`	integer/string	FrameAI 标准响应码，成功通常为 `0`
`data.asset_id`	string	被删除的素材 ID
`data.deleted`	boolean	是否删除成功
`msg`	string	响应消息

响应示例：

{
  "code": 0,
  "data": {
    "asset_id": "volcano-asset-xxx",
    "deleted": true
  },
  "msg": "success"
}

错误响应

本地校验和接口错误都会返回统一结构：

{
  "code": "InvalidRequest",
  "data": {},
  "msg": "request body must be a JSON object"
}

字段	类型	说明
`code`	integer/string	成功通常为 `0`；失败时为稳定错误码或接口错误码
`data`	object	成功时为业务数据；无业务数据或失败时返回空对象 `{}`
`msg`	string	成功或失败消息

HTTP 状态码	常见原因
`400`	请求体不是 JSON 对象、路径参数或查询参数不合法
`401`	FrameAI API Key 缺失或无效
`403`	当前账号无权访问素材组、素材或真人认证能力
`404`	素材组、素材或认证会话不存在
`503`	暂无可用服务
`502`	服务请求失败

使用注意事项

素材 URL 必须能从服务端公网直接下载，不能依赖 Cookie、登录态或 Referer。
创建素材后应查询详情，确认状态为 ACTIVE 后再用于视频生成。
group_id、asset_id、byted_token 都应作为不透明字符串保存，不要从 ID 格式推断业务信息。