虚拟人像素材库

约 2454 字大约 8 分钟

虚拟人像素材库用于保存可复用的虚拟角色、图片、视频和音频素材。推荐先创建素材组，再把素材加入该组，素材状态可用后再交给视频生成接口引用。

Ark 响应公共字段

本页响应示例中的 ResponseMetadata 字段含义一致，具体业务数据位于 Result。

字段	类型	说明
`ResponseMetadata.RequestId`	string	上游请求唯一 ID，用于日志检索和问题排查
`ResponseMetadata.Action`	string	本次执行的素材动作
`ResponseMetadata.Version`	string	上游素材 API 版本
`ResponseMetadata.Service`	string	上游服务名，国内素材库通常为 `ark`
`ResponseMetadata.Region`	string	上游区域
`ResponseMetadata.Error`	object	上游错误对象；成功时通常不返回
`Result`	object	当前接口的业务响应对象

创建素材组

POST https://mivsub.com/api/v3/ark/assets/groups
Authorization: Bearer sk-frameai-xxxxxxxx
Content-Type: application/json

请求体：

字段	类型	必填	说明
`Name`	string	是	素材组名称
`Description`	string	否	素材组描述
`GroupType`	string	否	素材组类型，常见值为 `AIGC`

{
  "Name": "原创角色素材组",
  "Description": "用于 Seedance 角色一致性视频",
  "GroupType": "AIGC"
}

成功响应示例：

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

响应字段：

字段	类型	说明
`Result.Id`	string	新创建的素材组 ID，创建素材时作为 `GroupId` 使用

后续创建素材时，将 Result.Id 作为 GroupId。

查询素材组列表

GET https://mivsub.com/api/v3/ark/assets/groups?PageNumber=1&PageSize=20&SortBy=CreateTime&SortOrder=Desc
Authorization: Bearer sk-frameai-xxxxxxxx

查询参数：

参数	类型	必填	说明
`PageNumber`	integer	否	页码，例如 `1`
`PageSize`	integer	否	每页数量，例如 `20`
`SortBy`	string	否	排序字段，例如 `CreateTime`
`SortOrder`	string	否	排序方向，例如 `Asc` 或 `Desc`
`ProjectName`	string	否	项目名称

PageNumber 和 PageSize 必须传十进制整数，不要传空字符串。

响应示例：

{
  "ResponseMetadata": {
    "RequestId": "20260809101100D4E5F6",
    "Action": "ListAssetGroups",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Items": [
      {
        "Id": "asset-group-xxxxxxxx",
        "Name": "原创角色素材组",
        "Description": "用于 Seedance 角色一致性视频",
        "GroupType": "AIGC",
        "ProjectName": "default"
      }
    ],
    "TotalCount": 1,
    "PageNumber": 1,
    "PageSize": 20
  }
}

响应字段：

字段	类型	说明
`Result.Items`	`array<object>`	当前页素材组对象列表
`Result.Items[].Id`	string	素材组 ID
`Result.Items[].Name`	string	素材组名称
`Result.Items[].Description`	string	素材组描述
`Result.Items[].GroupType`	string	素材组类型
`Result.Items[].ProjectName`	string	素材组所属项目
`Result.Items[].CreateTime`	string / integer	创建时间，格式由上游渠道决定
`Result.Items[].UpdateTime`	string / integer	最后更新时间，格式由上游渠道决定
`Result.TotalCount`	integer	符合条件的素材组总数
`Result.PageNumber`	integer	当前页码
`Result.PageSize`	integer	当前页返回上限

查询素材组详情

GET https://mivsub.com/api/v3/ark/assets/groups/asset-group-xxxxxxxx
Authorization: Bearer sk-frameai-xxxxxxxx

路径中的 group_id 为创建素材组时返回的 ID。需要指定项目时，可以追加 ?ProjectName=default。请求字段：

字段	位置	类型	必填	说明
`group_id`	path	string	是	要查询的素材组 ID
`ProjectName`	query	string	否	项目名称

响应字段：

字段	类型	说明
`Result.Id`	string	素材组 ID
`Result.Name`	string	素材组名称
`Result.Description`	string	素材组描述
`Result.GroupType`	string	素材组类型
`Result.ProjectName`	string	所属项目
`Result.CreateTime`	string / integer	创建时间，格式由上游渠道决定
`Result.UpdateTime`	string / integer	最后更新时间，格式由上游渠道决定

更新素材组

PUT https://mivsub.com/api/v3/ark/assets/groups/asset-group-xxxxxxxx
Authorization: Bearer sk-frameai-xxxxxxxx
Content-Type: application/json

请求体字段：

字段	类型	必填	说明
`Name`	string	否	更新后的素材组名称
`Description`	string	否	更新后的素材组描述
`GroupType`	string	否	更新后的素材组类型；仅在上游允许修改时有效
`ProjectName`	string	否	项目名称

只发送需要更新且上游支持的字段：

{
  "Name": "原创角色素材组（已更新）",
  "Description": "角色正面、侧面和动作参考"
}

路径中的 group_id 会作为目标素材组 ID，客户端不需要在请求体中重复传 GroupId。响应字段：

字段	类型	说明
`Result.Id`	string	已更新的素材组 ID；部分渠道只返回空 `Result`
`Result.Name`	string	更新后的名称；仅在上游返回完整对象时存在
`Result.UpdateTime`	string / integer	更新时间；仅在上游返回时存在

删除素材组

DELETE https://mivsub.com/api/v3/ark/assets/groups/asset-group-xxxxxxxx
Authorization: Bearer sk-frameai-xxxxxxxx

建议先删除组内不再使用的素材。若素材组仍被素材或任务引用，上游可能拒绝删除。请求与响应字段：

字段	位置	类型	必填	说明
`group_id`	path	string	是	要删除的素材组 ID
`ProjectName`	query	string	否	项目名称
`Result.Id`	response	string	否	已删除的素材组 ID；部分渠道删除成功返回空对象或 HTTP 204

创建虚拟人素材

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

请求体：

字段	类型	必填	说明
`GroupId`	string	是	已创建的素材组 ID
`URL`	string	是	服务端可直接下载的公网素材 URL
`Name`	string	否	素材名称
`AssetType`	string	否	常见值为 `Image`、`Video` 或 `Audio`
`ProjectName`	string	否	项目名称

{
  "GroupId": "asset-group-xxxxxxxx",
  "URL": "https://cdn.example.com/characters/original-character.png",
  "Name": "原创角色正面参考图",
  "AssetType": "Image"
}

成功响应示例：

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

响应字段：

字段	类型	说明
`Result.Id`	string	新创建的素材 ID，后续查询和 `asset://` 引用使用该值

查询虚拟人素材列表

GET https://mivsub.com/api/v3/ark/assets?GroupId=asset-group-xxxxxxxx&AssetType=Image&PageNumber=1&PageSize=20
Authorization: Bearer sk-frameai-xxxxxxxx

查询参数：

参数	类型	必填	说明
`GroupId`	string	否	按素材组筛选
`AssetType`	string	否	按素材类型筛选
`GroupType`	string	否	按素材组类型筛选
`PageNumber`	integer	否	页码
`PageSize`	integer	否	每页数量
`SortBy`	string	否	排序字段
`SortOrder`	string	否	排序方向
`ProjectName`	string	否	项目名称

响应示例：

{
  "ResponseMetadata": {
    "RequestId": "20260809101300C1D2E3",
    "Action": "ListAssets",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Items": [
      {
        "Id": "asset-xxxxxxxx",
        "Name": "原创角色正面参考图",
        "URL": "https://cdn.example.com/characters/original-character.png",
        "AssetType": "Image",
        "GroupId": "asset-group-xxxxxxxx",
        "Status": "Active",
        "ProjectName": "default"
      }
    ],
    "TotalCount": 1,
    "PageNumber": 1,
    "PageSize": 20
  }
}

响应字段：

字段	类型	说明
`Result.Items`	`array<object>`	当前页素材对象列表
`Result.Items[].Id`	string	素材 ID
`Result.Items[].Name`	string	素材名称
`Result.Items[].URL`	string	渠道返回的素材访问地址
`Result.Items[].AssetType`	string	素材类型，例如 `Image`、`Video` 或 `Audio`
`Result.Items[].GroupId`	string	所属素材组 ID
`Result.Items[].Status`	string	素材处理状态
`Result.Items[].ProjectName`	string	所属项目
`Result.Items[].CreateTime`	string / integer	创建时间，存在时由上游返回
`Result.Items[].UpdateTime`	string / integer	更新时间，存在时由上游返回
`Result.TotalCount`	integer	符合条件的素材总数
`Result.PageNumber`	integer	当前页码
`Result.PageSize`	integer	当前页返回上限

查询虚拟人素材详情

GET https://mivsub.com/api/v3/ark/assets/asset-xxxxxxxx
Authorization: Bearer sk-frameai-xxxxxxxx

请求字段：

字段	位置	类型	必填	说明
`asset_id`	path	string	是	要查询的素材 ID
`ProjectName`	query	string	否	项目名称

重点检查以下字段：

字段	说明
`Id`	素材 ID，用于后续引用
`Status`	`Active` 时通常可用于生成；`Processing` 时继续轮询；`Failed` 时读取错误信息
`AssetType`	实际素材类型
`GroupId`	所属素材组
`URL`	渠道返回的素材访问地址
完整响应字段：

字段	类型	说明
`Result.Id`	string	素材 ID
`Result.Name`	string	素材名称
`Result.URL`	string	渠道返回的素材地址
`Result.AssetType`	string	素材类型
`Result.GroupId`	string	所属素材组 ID
`Result.Status`	string	`Active`、`Processing` 或 `Failed` 等处理状态
`Result.Moderation`	object	内容审核或策略信息，存在时由上游返回
`Result.Moderation.Strategy`	string	审核策略名称
`Result.ProjectName`	string	所属项目
`Result.CreateTime`	string / integer	创建时间
`Result.UpdateTime`	string / integer	最后更新时间
`Result.Error`	object	素材处理失败信息，仅失败状态可能返回
`Result.Error.Code`	string	素材处理错误码
`Result.Error.Message`	string	素材处理错误详情

更新虚拟人素材

PUT https://mivsub.com/api/v3/ark/assets/asset-xxxxxxxx
Authorization: Bearer sk-frameai-xxxxxxxx
Content-Type: application/json

请求体字段：

字段	类型	必填	说明
`Name`	string	否	更新后的素材名称
`ProjectName`	string	否	项目名称
其他字段	any	否	仅传所选渠道明确支持更新的字段

{
  "Name": "原创角色正面参考图（高清版）"
}

路径中的 asset_id 会作为目标素材 ID。可更新字段以所选渠道的实际支持范围为准；不要在更新时更换素材内容，内容变更应创建新素材。响应字段：

字段	类型	说明
`Result.Id`	string	已更新的素材 ID；部分渠道只返回空 `Result`
`Result.Name`	string	更新后的素材名称；仅在上游返回完整对象时存在
`Result.UpdateTime`	string / integer	更新时间；仅在上游返回时存在

删除虚拟人素材

DELETE https://mivsub.com/api/v3/ark/assets/asset-xxxxxxxx
Authorization: Bearer sk-frameai-xxxxxxxx

删除前确认没有正在运行的视频任务继续引用该素材。删除结果和响应体由上游渠道透传。请求与响应字段：

字段	位置	类型	必填	说明
`asset_id`	path	string	是	要删除的素材 ID
`ProjectName`	query	string	否	项目名称
`Result.Id`	response	string	否	已删除的素材 ID；部分渠道删除成功返回空对象或 HTTP 204

在视频请求中引用

当模型和渠道支持素材协议时，使用创建接口返回的素材 ID：

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "保持参考角色外观一致，生成角色在花园中挥手的视频"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "asset://asset-xxxxxxxx"
      }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": false,
  "watermark": false
}

状态要求：创建接口返回素材 ID 后不要立即假定素材可用。先查询详情，确认素材状态满足所选渠道和模型的生成要求。

接口文档

素材接口

虚拟人像素材库

Ark 响应公共字段

推荐调用顺序

创建素材组

查询素材组列表

查询素材组详情

更新素材组

删除素材组

创建虚拟人素材

查询虚拟人素材列表

查询虚拟人素材详情

更新虚拟人素材

删除虚拟人素材

在视频请求中引用