管理 Seedance 兼容的资产组和资产，用于可复用的视频工作流。

字节 Seedance / 素材库

管理可复用的 Seedance 素材库和素材，用于参考素材视频生成流程。

需要素材审核、白名单素材、可复用角色/场景参考图，或围绕同一组审核素材持续生成时使用素材库。普通文生视频和简单图生视频可以直接使用视频任务接口，不需要素材库。

接口信息

项目	值
Base URL	`https://api.unigateway.ai`
鉴权	`Authorization: Bearer $UNIGATEWAY_API_KEY`

接口

操作	方法	路径
创建素材库	`POST`	`/api/v3/asset-groups`
查询素材库列表	`GET`	`/api/v3/asset-groups`
查询单个素材库	`GET`	`/api/v3/asset-groups/{groupId}`
更新素材库	`PATCH`	`/api/v3/asset-groups/{groupId}`
创建素材	`POST`	`/api/v3/assets`
查询素材列表	`GET`	`/api/v3/assets`
查询单个素材	`GET`	`/api/v3/assets/{assetId}`
更新素材	`PATCH`	`/api/v3/assets/{assetId}`
删除素材	`DELETE`	`/api/v3/assets/{assetId}`

请求体和响应体使用 Volcengine 风格的大驼峰字段，例如 Name、Description、GroupType、GroupId、URL、AssetType、Id。

创建素材库时建议同时传入 Seedance 模型 ID，以便素材库稳定绑定到对应的国内或全球版本。未传模型 ID 时，系统会根据可用通道自动选择，可能无法稳定落到预期版本。

创建素材库

curl -sS -X POST "https://api.unigateway.ai/api/v3/asset-groups" \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "Seedance Character Library",
    "Description": "Reference characters for story-consistent renders.",
    "GroupType": "AIGC",
    "ModelId": "dreamina-seedance-2-0-260128"
  }'

字段	类型	必填	说明
`Name`	string	是	素材库名称
`Description`	string	否	描述
`GroupType`	string	否	默认 `AIGC`；当前只接受 `AIGC`
`ModelId` / `model_id`	string	建议传	Seedance 模型 ID，用于选择对应的国内或全球版本。例如 `dreamina-seedance-2-0-260128` 会创建绑定到全球 Dreamina Seedance 2.0 的素材库

响应：

{
  "Id": "uag_123",
  "ResponseMetadata": {
    "Action": "CreateAssetGroup",
    "Region": "cn-beijing",
    "RequestId": "<request-id>",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "uag_123"
  }
}

查询素材库列表

curl -sS "https://api.unigateway.ai/api/v3/asset-groups?page_num=1&page_size=50&filter.group_type=AIGC" \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY"

查询参数	必填	说明
`page_num`	否	默认 `1`
`page_size`	否	默认 `50`，最大 `200`
`filter.name`	否	按素材库名称过滤
`filter.group_ids`	否	逗号分隔的素材库 ID
`filter.group_type`	否	如提供，必须为 `AIGC`

响应：

{
  "ResponseMetadata": {
    "Action": "ListAssetGroups",
    "Region": "cn-beijing",
    "RequestId": "<request-id>",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {
    "AssetGroups": [
      {
        "Id": "uag_123",
        "Name": "Seedance Character Library",
        "Title": "Seedance Character Library",
        "Description": "Reference characters for story-consistent renders.",
        "GroupType": "AIGC",
        "ProjectName": "default",
        "CreatedAt": 1781256203,
        "UpdatedAt": 1781256203
      }
    ],
    "PageNumber": 1,
    "PageSize": 50,
    "TotalCount": 1
  }
}

部分部署也可能同时返回顶层兼容字段，例如 Items、TotalCount、PageNumber、PageSize、Limit、Offset。

查询单个素材库

curl -sS "https://api.unigateway.ai/api/v3/asset-groups/uag_123" \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY"

响应：

{
  "ResponseMetadata": {
    "Action": "GetAssetGroup",
    "Region": "cn-beijing",
    "RequestId": "<request-id>",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "uag_123",
    "Name": "Seedance Character Library",
    "Description": "Reference characters for story-consistent renders.",
    "GroupType": "AIGC",
    "ProjectName": "default",
    "CreateTime": "2026-06-12T09:23:23Z",
    "UpdateTime": "2026-06-12T09:23:23Z"
  }
}

更新素材库

至少提供 Name 或 Description 之一。

curl -sS -X PATCH "https://api.unigateway.ai/api/v3/asset-groups/uag_123" \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "Seedance Resource Library",
    "Description": "Approved resources for Seedance workflows."
  }'

响应：

{
  "ResponseMetadata": {
    "Action": "UpdateAssetGroup",
    "Region": "cn-beijing",
    "RequestId": "<request-id>",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "uag_123"
  }
}

创建素材

curl -sS -X POST "https://api.unigateway.ai/api/v3/assets" \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "hero-reference-01",
    "AssetType": "Image",
    "URL": "https://example.com/assets/hero-reference-01.jpg",
    "GroupId": "uag_123"
  }'

字段	类型	必填	说明
`Name`	string	是	素材显示名称
`URL`	string	是	源文件 URL
`GroupId`	string	是	创建或查询素材库返回的素材库 ID
`AssetType`	string	建议传	`Image`、`Video` 或 `Audio`；省略时默认 `Image`

响应：

{
  "Id": "ua_123",
  "ResponseMetadata": {
    "Action": "CreateAsset",
    "Region": "cn-beijing",
    "RequestId": "<request-id>",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "ua_123"
  }
}

在视频生成请求中使用返回的素材 ID：asset://ua_123。

查询素材列表

curl -sS "https://api.unigateway.ai/api/v3/assets?page_num=1&page_size=20&filter.group_ids=uag_123&filter.group_type=AIGC&filter.statuses=Active&sort_by=created_at&sort_order=asc" \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY"

查询参数	必填	说明
`page_num`	否	默认 `1`
`page_size`	否	默认 `10`，最大 `100`
`filter.group_ids`	是	逗号分隔的素材库 ID
`filter.group_type`	是	必须为 `AIGC`
`filter.statuses`	否	逗号分隔的状态，例如 `Active`、`Processing`、`Failed`
`filter.name`	否	按素材名称过滤
`sort_by`	否	`created_at`、`updated_at` 或 `group_id`
`sort_order`	否	`asc` 或 `desc`

响应：

{
  "ResponseMetadata": {
    "Action": "ListAssets",
    "Region": "cn-beijing",
    "RequestId": "<request-id>",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {
    "Assets": [
      {
        "Id": "ua_123",
        "Name": "hero-reference-01",
        "URL": "https://example.com/assets/hero-reference-01.jpg",
        "GroupId": "uag_123",
        "AssetType": "Image",
        "Status": "Active",
        "ProjectName": "default",
        "CreatedAt": 1781257489,
        "UpdatedAt": 1781257865
      }
    ],
    "PageNumber": 1,
    "PageSize": 20,
    "TotalCount": 1
  }
}

查询单个素材

curl -sS "https://api.unigateway.ai/api/v3/assets/ua_123" \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY"

响应：

{
  "ResponseMetadata": {
    "Action": "GetAsset",
    "Region": "cn-beijing",
    "RequestId": "<request-id>",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "ua_123",
    "Name": "hero-reference-01",
    "URL": "https://example.com/assets/hero-reference-01.jpg",
    "GroupId": "uag_123",
    "AssetType": "Image",
    "Status": "Active",
    "ProjectName": "default",
    "Moderation": {
      "Strategy": "Default"
    },
    "CreateTime": "2026-06-12T09:34:53Z",
    "UpdateTime": "2026-06-12T09:35:00Z"
  }
}

更新素材

当前仅更新 Name。

curl -sS -X PATCH "https://api.unigateway.ai/api/v3/assets/ua_123" \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "hero-reference-01-rename"
  }'

响应：

{
  "ResponseMetadata": {
    "Action": "UpdateAsset",
    "Region": "cn-beijing",
    "RequestId": "<request-id>",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "ua_123"
  }
}

删除素材

curl -sS -X DELETE "https://api.unigateway.ai/api/v3/assets/ua_123" \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY"

响应：

{
  "ResponseMetadata": {
    "Action": "DeleteAsset",
    "Region": "cn-beijing",
    "RequestId": "<request-id>",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {}
}

ID 使用说明

素材库和素材按账号隔离
使用返回的 Id 进行后续查询、更新、删除，以及 asset://<ASSET_ID> 引用
创建视频任务时，只引用同一个 API Key 可访问的素材

字节 Seedance / 素材库#

接口信息#

接口#

创建素材库#

查询素材库列表#

查询单个素材库#

更新素材库#

创建素材#

查询素材列表#

查询单个素材#

更新素材#

删除素材#

ID 使用说明#