# 查询素材资产列表
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
`POST https://ark.cn-beijing.volcengineapi.com/?Action=ListAssets&Version=2024-01-01`
查询符合筛选条件的 Assets（素材资产）列表。
> **警告：分页方式说明**
>
> 本接口支持以下两种分页方式查看返回数据：
>
> * **方式一：NextToken 分页（推荐）**：通过 *MaxResults* 参数设置每页返回的最大记录数，再通过 *NextToken* 参数传入翻页凭证，展示下一页内容。
> * 首次查询时，可传入 *MaxResults* 设置每页返回的最大记录数，无需传入 *NextToken*。存在下一页时，响应中同时返回 *NextToken*。
> * 后续查询时，传入前一次响应返回的 *NextToken*。如果未返回 *NextToken*，则表示遍历结束。
> * 后续查询建议保持 *Filter*、*ProjectName*、*SortBy* 和 *SortOrder* 与首次查询一致。
> * 使用该方式时，不返回 *TotalCount*、*PageNumber* 和 *PageSize*。
>
> * **方式二：页码分页（兼容）**：通过 *PageSize* 参数设置每页返回的记录数，通过 *PageNumber* 参数指定具体返回页码。
> * 响应返回 *TotalCount*、*PageNumber* 和 *PageSize*。
>
> **说明**：
> * 两种分页方式只能任选其一，不可同时传入两类分页参数。
> * 未传入任何分页参数时，默认使用方式一，按 *MaxResults* = `10` 查询。后续查询可使用 *NextToken* 翻页。
> * 当数据查询范围较大（即 `PageSize * PageNumber > 20000`）时，请通过 `NextToken` 方式来实现深翻页。
## 鉴权
本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。
* Access Key 鉴权，请在 [Access Key 管理](https://console.volcengine.com/iam/keymanage) 页面，获取 Access Key。本接口仅支持 Access Key 鉴权。
---
## 请求参数
### Body 参数
**Filter** `object` `必选` | 过滤条件
搜索的过滤条件
**GroupType** `string` `必选` | 素材组类型
`Filter.GroupType`
Asset Group（素材资产组合）的类型。取值：
* `AIGC`：虚拟人像；
* `LivenessFace`：真人素材
**GroupIds** `string[]` | 素材组 ID 列表
`Filter.GroupIds`
Asset（素材资产）所属的 Asset Group（素材资产组合）的 Id 列表。通过创建素材资产组合接口 (CreateAssetGroup) 返回, 或通过 ListAssetGroups 接口查询获取。
**Name** `string` | 素材名称
`Filter.Name`
Asset（素材资产）的名称，上限为 64 个字符
**Statuses** `string[]` | 状态筛选
`Filter.Statuses`
素材资产状态。取值：
* `Active`：素材资产已处理完毕，可以使用；
* `Processing`：素材资产正在预处理，无法使用；
* `Failed`：素材资产处理失败
**NextToken** `string` | 翻页凭证
NextToken 分页的翻页凭证。取值为前一次调用本接口时返回的 `NextToken`。
> **说明：使用说明**
>
> - 首次查询无需传入 `NextToken`。
> - 查询下一页时，传入前一次响应返回的 `NextToken`。
> **注意：使用限制**
>
> - 不可同时传入 `PageNumber` 或 `PageSize`。
> - 空字符串、被修改的凭证或跨接口、账号、项目使用的凭证无效。
**MaxResults** `integer` | 每页记录数
NextToken 分页时每页返回的最大记录数。
> **说明：使用说明**
>
> - 首次查询可通过该参数设置每页返回的最大记录数。
> - 未传入任何分页参数时，默认使用 NextToken 分页，`MaxResults` 的默认值为 `10`。
> - 后续查询传入 `NextToken` 时可省略该参数，省略时默认值为 `10`。
> **注意：使用限制**
>
> 不可同时传入 `PageNumber` 或 `PageSize`。
**取值范围**：`[1, 100]`
**SortBy** `string` `默认值 CreateTime` | 排序字段
用于排序的字段名称。取值：
* `CreateTime`：根据创建时间排序；
* `UpdateTime`：根据更新时间排序；
* `GroupId`：根据资产素材组的 Id 排序。
**SortOrder** `string` `默认值 Desc` | 排序顺序
排序顺序。取值：
* `Desc`：降序；
* `Asc`：升序。
**ProjectName** `string` `默认值 default` | 所属项目
资源所属的项目名称。若资源不在默认项目中，需填写正确的项目名称。
**PageNumber** `integer` | 页码（当 `PageSize * PageNumber > 20000` 时，请使用 NextToken 深翻页）
页码分页的页码，从 `1` 开始。
> **注意：使用限制**
>
> - `PageNumber` 和 `PageSize` 需同时使用。
> - 传入该参数时，不可同时传入 `MaxResults` 或 `NextToken`。
**PageSize** `integer` | 每页记录数（当 `PageSize * PageNumber > 20000` 时，请使用 NextToken 深翻页）
页码分页时每页返回的记录数。
> **注意：使用限制**
>
> - `PageNumber` 和 `PageSize` 需同时使用。
> - 传入该参数时，不可同时传入 `MaxResults` 或 `NextToken`。
**取值范围**：`[1, 100]`
## 响应参数
**Items** `object[]` | 素材列表
符合筛选条件的 Asset（素材资产）数组。没有符合条件的素材时返回空数组。
**AssetType** `string` | 素材类型
`Items.AssetType`
Asset（素材资产）的类型。取值：
* `Image`：图像；
* `Video`：视频；
* `Audio`：音频
**CreateTime** `string` | 创建时间
`Items.CreateTime`
**Error** `object` | 错误信息
`Items.Error`
**Code** `string` | 错误码
`Items.Error.Code`
**Message** `string` | 错误信息
`Items.Error.Message`
**GroupId** `string` | 所属素材组 ID
`Items.GroupId`
Asset（素材资产）所属的 Asset Group（素材资产组合）的 Id
**Id** `string` | 素材 ID
`Items.Id`
Asset（素材资产）的 Id
**LastInferenceTime** `string` | 最近推理时间
`Items.LastInferenceTime`
该素材最近一次被提交至视频生成任务的时间，采用 RFC 3339 格式（精确到秒，不含小数秒），例如 `2026-07-14T02:08:49Z` 或 `2026-07-14T10:08:49+08:00`。
该时间为任务提交时间，非任务处理时间。任务提交成功后，无论后续执行成功或失败，*LastInferenceTime* 都会更新。
对于新提交的任务，在使用 *GetAsset* 与 *ListAssets* 查询相关素材时，该字段更新可能存在 1–2 分钟延迟。若素材在 2026-07-24 之后未被任何任务调用，则不返回该字段。
**Moderation** `object` | 内容审核
`Items.Moderation`
内容审核相关信息
**Strategy** `string` | 审核策略
`Items.Moderation.Strategy`
该素材的内容审核策略，该字段返回固定值 `Default`
**Name** `string` | 素材名称
`Items.Name`
Asset（素材资产）的名称，上限为 64 个字符
**ProjectName** `string` | 所属项目
`Items.ProjectName`
资源所属的项目名称
**Status** `string` | 素材状态
`Items.Status`
任务状态。取值：`Active`；`Processing`；`Failed`
**UpdateTime** `string` | 更新时间
`Items.UpdateTime`
**URL** `string` | 访问地址
`Items.URL`
Asset（素材资产）的公共可访问地址。有效期为 12 小时，请及时保存
**NextToken** `string` | 下一页翻页凭证
下一页的翻页凭证。仅在 NextToken 分页且存在下一页时返回。
后续请求应原样传入；未返回该字段表示遍历结束。
**PageNumber** `integer` | 页码
当前页码。仅在页码分页时返回。
**PageSize** `integer` | 每页记录数
每页返回的记录数。仅在页码分页时返回。
**取值范围**：`[1, 100]`
**TotalCount** `integer` | 总数
符合筛选条件的素材总数。仅在页码分页时返回。
## 代码示例
## 默认
### cURL
#### Request
```bash
curl 'https://ark.cn-beijing.volcengineapi.com/?Action=ListAssets&Version=2024-01-01' \
-H 'Content-Type: application/json' \
-H 'X-Date: ' \
-H 'X-Content-Sha256: ' \
-H 'Authorization: HMAC-SHA256 Credential=//cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=' \
-d '{
"Filter": {
"GroupIds": ["group-20240514212750-b5e9m"],
"GroupType": "AIGC",
"Statuses": ["Active"]
},
"MaxResults": 1,
"SortBy": "CreateTime",
"SortOrder": "Desc",
"ProjectName": "default"
}
'
```
#### Response
```
{
"ResponseMetadata": {
"RequestId": "202405142130001A2B3C4D5E6F708192",
"Action": "ListAssets",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"Items": [
{
"Id": "asset-20240514212750-a3f8k",
"Name": "demo-portrait-image",
"URL": "https://ark-asset.cn-beijing.volcengine.com/asset-20240514212750-a3f8k.jpg?X-Amz-Expires=43200",
"GroupId": "group-20240514212750-b5e9m",
"AssetType": "Image",
"Status": "Active",
"Moderation": {
"Strategy": "Default"
},
"Error": {
"Code": "",
"Message": ""
},
"ProjectName": "default",
"CreateTime": "2024-05-14T21:27:50Z",
"UpdateTime": "2024-05-14T21:30:00Z",
"LastInferenceTime": "2024-05-14T22:15:30Z"
}
],
"NextToken": "****bmNyeXB0ZWRfY3Vyc29yIjoiLi4****"
}
}
```