FrameAI 对外提供与上游素材服务一致的 REST 路径。客户端只需要使用 FrameAI 分发的 API Key，无需自行计算火山 HMAC 签名，也不需要在查询参数中传入 Action 或 Version。

素材库分组

素材库	用途	接口前缀	详细文档
虚拟人像素材库	管理素材组和原创虚拟人物、图片、视频或音频素材	/api/v3/ark/assets	虚拟人像素材库
真人人像素材库	完成真人授权认证后创建和查询真人形象素材	/api/v3/ark/real-person	真人人像素材库
Seedance 海外素材库	为海外 Seedance 模型创建和查询素材	/api/v3/open	Seedance 海外素材库
移动云 Seedance 素材接口	管理移动云 Seedance 视频生成所需的素材组、认证素材和 AICC 素材	/api/v1/aicc	移动云 Seedance 素材接口

公共请求头

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

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

完整接口表

虚拟人像素材库

方法	路径	说明
POST	/api/v3/ark/assets/groups	创建素材组
GET	/api/v3/ark/assets/groups	查询素材组列表
GET	/api/v3/ark/assets/groups/{group_id}	查询素材组详情
PUT	/api/v3/ark/assets/groups/{group_id}	更新素材组
DELETE	/api/v3/ark/assets/groups/{group_id}	删除素材组
POST	/api/v3/ark/assets	创建素材
GET	/api/v3/ark/assets	查询素材列表
GET	/api/v3/ark/assets/{asset_id}	查询素材详情
PUT	/api/v3/ark/assets/{asset_id}	更新素材
DELETE	/api/v3/ark/assets/{asset_id}	删除素材

真人人像素材库

方法	路径	说明
POST	/api/v3/ark/real-person/validate/sessions	创建真人认证会话
GET	/api/v3/ark/real-person/validate/sessions/{session_id}	查询真人认证结果
POST	/api/v3/ark/real-person/assets	创建真人素材
GET	/api/v3/ark/real-person/assets/{asset_id}	查询真人素材

Seedance 海外素材库

方法	路径	说明
POST	/api/v3/open/CreateAsset	创建海外素材
POST	/api/v3/open/GetAsset	查询海外素材

移动云 Seedance 素材接口

方法	路径	说明
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	获取并绑定真人素材组
GET	/api/v1/aicc/assets	查询素材列表
POST	/api/v1/aicc/assets	创建素材
GET	/api/v1/aicc/assets/{asset_id}	查询素材详情
PUT	/api/v1/aicc/assets/{asset_id}	更新素材
DELETE	/api/v1/aicc/assets/{asset_id}	删除素材

素材调用流程

上传素材到公网可访问地址
  -> 调用对应素材库的创建接口
  -> 保存返回的素材 ID
  -> 查询素材状态
  -> 状态可用后按 asset://<素材ID> 引用
  -> 创建 Seedance 视频任务

虚拟人像素材通常先创建素材组，再在组内创建素材；真人人像素材必须先完成授权认证；海外素材直接调用 CreateAsset。移动云 Seedance 素材接口使用 /api/v1/aicc 路径。

响应约定

FrameAI 会透传所选渠道的成功响应和上游错误，因此不同渠道的响应包裹方式可能不同。火山 Ark 常见成功响应使用 ResponseMetadata 和 Result：

{
  "ResponseMetadata": {
    "RequestId": "20260809100000A1B2C3",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-xxxxxxxx"
  }
}

公共成功响应字段：

字段	类型	说明
ResponseMetadata	object	火山 Ark 响应元数据
ResponseMetadata.RequestId	string	本次上游请求的唯一 ID，排查问题时应完整保存
ResponseMetadata.Action	string	实际执行的上游动作，例如 CreateAsset
ResponseMetadata.Version	string	上游 API 版本；国内 Ark 素材接口常见为 2024-01-01
ResponseMetadata.Service	string	上游服务名，例如 ark 或 pcc
ResponseMetadata.Region	string	上游区域，例如 cn-beijing
ResponseMetadata.Error	object	上游业务错误；成功时通常不返回
ResponseMetadata.Error.CodeN	integer	火山数值错误码，存在时表示请求失败
ResponseMetadata.Error.Code	string	火山字符串错误码
ResponseMetadata.Error.Message	string	火山错误详情
Result	object	当前接口的业务结果；具体字段见三组素材库页面

兼容路由在本地校验失败时返回：

{
  "error": {
    "message": "request body must be a JSON object",
    "type": "invalid_request_error",
    "code": "InvalidRequest"
  }
}

本地错误响应字段：

字段	类型	说明
error	object	FrameAI 兼容路由错误对象
error.message	string	可读的错误原因
error.type	string	错误类别，例如 invalid_request_error
error.code	string	稳定错误码，例如 InvalidRequest、InvalidChannel

HTTP 状态码	说明
200 / 201	请求成功，以实际响应体为准
204	删除成功且没有响应体
400	请求体、路径参数或查询参数不合法
401	FrameAI API Key 缺失、无效或过期
403	当前账号无权访问素材或真人认证能力
404	素材、素材组或认证会话不存在
502	渠道配置、凭证或上游请求失败

路径约定：客户端应直接调用本页列出的 REST 路径。旧版 /volcengine/ark/materials/{library}?Action=... 仅用于兼容已有调用，不建议新接入继续使用。

使用注意事项

• 素材 URL 必须是服务端可直接下载的公网地址，不能依赖 Cookie、浏览器登录态或 Referer。
• group_id、asset_id 和 session_id 应作为不透明字符串保存，不要从 ID 格式推断业务信息。
• 创建成功不一定表示素材立即可用于生成，应查询详情并确认状态为 Active 或渠道定义的成功状态。
• 素材 ID 只能在创建它的账号、项目和渠道权限范围内使用。
• 真人素材必须由本人完成授权，并遵守适用的隐私、肖像和内容合规要求。

上一页火山标准格式

下一页虚拟人像素材库