# 查询素材组列表

URL: http://localhost:3000/docs/zh-cn/api/asset-library/ListAssetGroups

按筛选条件分页查询素材组。Filter.GroupType 必填，用于区分 AIGC / LivenessFace。



分页查询素材组。`Filter.GroupType` 必填。接入信息与鉴权见[素材库总览](/zh-cn/api/asset-library)。

<ArkOperation>
  <div>
    ## 请求参数 [#请求参数]

    | 参数                 | 类型        | 必填 | 说明                                  |
    | ------------------ | --------- | -- | ----------------------------------- |
    | `Filter.GroupType` | string    | 是  | 素材组类型，`AIGC` 或 `LivenessFace`       |
    | `Filter.GroupIds`  | string\[] | 否  | 按素材组 Id 过滤                          |
    | `Filter.Name`      | string    | 否  | 按名称模糊过滤                             |
    | `PageNumber`       | integer   | 是  | 页码，从 1 开始                           |
    | `PageSize`         | integer   | 是  | 每页数量，1–100                          |
    | `SortBy`           | string    | 否  | 排序字段，`CreateTime`（默认）或 `UpdateTime` |
    | `SortOrder`        | string    | 否  | 排序方向，`Desc`（默认）或 `Asc`              |
    | `ProjectName`      | string    | 否  | 资源所属项目，默认 `default`                 |

    ## 响应参数 [#响应参数]

    `Result` 结构：

    | 字段           | 类型        | 说明         |
    | ------------ | --------- | ---------- |
    | `TotalCount` | integer   | 符合条件的总数    |
    | `PageNumber` | integer   | 当前页码       |
    | `PageSize`   | integer   | 每页数量       |
    | `Items`      | object\[] | 素材组数组，元素见下 |

    `Items` 元素：

    | 字段            | 类型     | 说明                      |
    | ------------- | ------ | ----------------------- |
    | `Id`          | string | 素材组 Id                  |
    | `Name`        | string | 名称                      |
    | `Description` | string | 描述                      |
    | `GroupType`   | string | `AIGC` / `LivenessFace` |
    | `ProjectName` | string | 所属项目                    |
    | `CreateTime`  | string | 创建时间，ISO8601 UTC        |
    | `UpdateTime`  | string | 更新时间，ISO8601 UTC        |

    ## 错误码 [#错误码]

    | Code                          | 说明                    |
    | ----------------------------- | --------------------- |
    | `MissingParameter.GroupType`  | 未传 `Filter.GroupType` |
    | `MissingParameter.PageNumber` | 未传 `PageNumber`       |
    | `MissingParameter.PageSize`   | 未传 `PageSize`         |
    | `InvalidParameter.GroupType`  | `GroupType` 取值非法      |
    | `InvalidParameter.PageSize`   | `PageSize` 不在 1–100   |
    | `InvalidParameter.SortBy`     | `SortBy` 取值非法         |
    | `InvalidParameter.SortOrder`  | `SortOrder` 取值非法      |

    其余通用错误码见[素材库总览](/zh-cn/api/asset-library#错误码)。
  </div>

  <div>
    ## 在线调试 [#在线调试]

    <ArkTryIt method="POST" action="ListAssetGroups" body="{ Filter: { GroupType: 'AIGC' }, PageNumber: 1, PageSize: 10, ProjectName: 'default' }" />

    ## 请求示例 [#请求示例]

    ```json
    {
      "Filter": { "GroupType": "AIGC" },
      "PageNumber": 1,
      "PageSize": 10,
      "ProjectName": "default"
    }
    ```

    ## 响应示例 [#响应示例]

    ```json
    {
      "ResponseMetadata": {
        "RequestId": "202603280000000000000000000000",
        "Action": "ListAssetGroups",
        "Version": "2024-01-01",
        "Service": "ark",
        "Region": "cn-beijing"
      },
      "Result": {
        "TotalCount": 1,
        "PageNumber": 1,
        "PageSize": 10,
        "Items": [
          {
            "Id": "grp_0a1b2c3d4e5f",
            "Name": "数字人形象库",
            "Description": "示例素材组",
            "GroupType": "AIGC",
            "ProjectName": "default",
            "CreateTime": "2026-03-28T00:00:00Z",
            "UpdateTime": "2026-03-28T00:00:00Z"
          }
        ]
      }
    }
    ```
  </div>
</ArkOperation>

## 官方文档 [#官方文档]

[查询素材资产组合列表（ListAssetGroups）](https://docs.volcengine.com/docs/82379/2318272?lang=zh)