# 查询素材列表

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

按筛选条件分页查询素材。可按素材组、状态、名称过滤。返回的 URL 有效期 12 小时。



分页查询素材，可按素材组、状态、名称过滤。返回的 `URL` 为重新托管的签名地址，有效期 12 小时。接入信息与鉴权见[素材库总览](/zh-cn/api/asset-library)。

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

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

    `Filter.GroupType` 会被接受但当前不生效，见[与火山官方的差异](/zh-cn/api/asset-library#与火山官方的差异)。

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

    `Result` 结构：

    | 字段           | 类型        | 说明                                                                 |
    | ------------ | --------- | ------------------------------------------------------------------ |
    | `TotalCount` | integer   | 符合条件的总数                                                            |
    | `PageNumber` | integer   | 当前页码                                                               |
    | `PageSize`   | integer   | 每页数量                                                               |
    | `Items`      | object\[] | 素材数组，元素结构见 [GetAsset 响应参数](/zh-cn/api/asset-library/GetAsset#响应参数) |

    ## 错误码 [#错误码]

    | Code                         | 说明                |
    | ---------------------------- | ----------------- |
    | `InvalidParameter.PageSize`  | `PageSize` 超过 100 |
    | `InvalidParameter.Statuses`  | `Statuses` 含非法状态值 |
    | `InvalidParameter.SortBy`    | `SortBy` 取值非法     |
    | `InvalidParameter.SortOrder` | `SortOrder` 取值非法  |
    | `AccessDenied`               | 无该项目成员权限          |

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

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

    <ArkTryIt method="POST" action="ListAssets" body="{ Filter: { GroupIds: ['grp_0a1b2c3d4e5f'], Statuses: ['Active'] }, PageNumber: 1, PageSize: 10, ProjectName: 'default' }" />

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

    ```json
    {
      "Filter": {
        "GroupIds": ["grp_0a1b2c3d4e5f"],
        "Statuses": ["Active"]
      },
      "PageNumber": 1,
      "PageSize": 10,
      "ProjectName": "default"
    }
    ```

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

    ```json
    {
      "ResponseMetadata": {
        "RequestId": "202603280000000000000000000000",
        "Action": "ListAssets",
        "Version": "2024-01-01",
        "Service": "ark",
        "Region": "cn-beijing"
      },
      "Result": {
        "TotalCount": 1,
        "PageNumber": 1,
        "PageSize": 10,
        "Items": [
          {
            "Id": "maas-abc123def456",
            "Name": "示例素材",
            "URL": "https://maas-ark.stringx.top/assets/abc123?sign=…",
            "GroupId": "grp_0a1b2c3d4e5f",
            "AssetType": "Image",
            "Status": "Active",
            "Moderation": { "Strategy": "Default" },
            "Error": { "Code": "", "Message": "" },
            "ProjectName": "default",
            "CreateTime": "2026-03-28T00:00:00Z",
            "UpdateTime": "2026-03-28T00:00:00Z"
          }
        ]
      }
    }
    ```
  </div>
</ArkOperation>

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

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