Doubao · 查询素材组列表

按类型、素材组 ID 或名称筛选素材组，并使用凭证或页码分页。

POSThttps://app.ai.kedang.net/ark?Action=ListAssetGroups&Version=2024-01-01

豆包素材库 · Ark Action API

查看响应字段说明

查询素材组列表响应字段
字段	类型	说明
`ResponseMetadata`	object	请求元信息。
`ResponseMetadata.RequestId`	string	请求标识，可用于定位一次接口请求。错误响应中可能省略。
`ResponseMetadata.Action`	string	本次请求的动作名称。
`ResponseMetadata.Version`	string	本次请求的接口版本。错误响应中可能省略。
`ResponseMetadata.Service`	string	服务名称，示例为 ark。
`ResponseMetadata.Region`	string	服务地域，示例为 cn-beijing。
`ResponseMetadata.Error`	object\|null	请求级业务错误；非空表示本次操作失败，HTTP 状态可能仍为 200。错误响应可能没有 Result。
`ResponseMetadata.Error.CodeN`	integer\|null	兼容错误编号，可为 null 或省略；错误判断与排查优先使用 Code。
`ResponseMetadata.Error.Code`	string	请求级错误码，例如 ResourceNotFound 表示指定素材不存在。
`ResponseMetadata.Error.Message`	string	请求级错误说明，和 Code 一起读取。
`Result`	object	动作的返回结果；各动作的字段见下文。
`Result.Items`	array<object>	符合筛选条件的素材组列表；没有匹配结果时为空数组。
`Result.Items[].CreateTime`	string	素材组的创建时间。
`Result.Items[].Description`	string	素材组的描述，最长 300 个字符。
`Result.Items[].GroupType`	string	素材组类型：AIGC 为虚拟人像，LivenessFace 为真人素材。查询可能返回两种类型；本页创建接口仅支持 AIGC。
`Result.Items[].Id`	string	素材组 ID。完整复制接口返回的 ID，不要自行添加前缀。
`Result.Items[].Name`	string	素材组名称，最长 64 个字符。
`Result.Items[].ProjectName`	string	素材组所属的项目名称。
`Result.Items[].UpdateTime`	string	素材组的更新时间。
`Result.NextToken`	string	仅在凭证分页且还有下一页时返回的翻页凭证；下次请求应原样传入，未返回表示遍历结束。
`Result.PageNumber`	integer	当前页码，仅在页码分页时返回。
`Result.PageSize`	integer	每页记录数，范围为 1 至 100，仅在页码分页时返回。
`Result.TotalCount`	integer	符合筛选条件的记录总数，仅在页码分页时返回。

Headers请求头

左右滑动查看完整参数表

请求头
参数名	类型	必填	说明	默认值 / 示例
`Authorization`	string	必填	可当平台的 API Key，请替换示例中的密钥占位值。	示例 `sk-YOUR_API_KEY`
`Content-Type`	string	必填	请求体使用 JSON 格式。	示例 `application/json`

Query Parameters查询参数

左右滑动查看完整参数表

查询参数
参数名	类型	必填	说明	默认值 / 示例
`Action`	string	必填	需要执行的素材库管理动作。	示例 `ListAssetGroups`
`Version`	string	必填	素材库管理接口的固定版本号。	示例 `2024-01-01`

Request Body请求体

application/json

左右滑动查看完整参数表

参数名类型必填说明默认值 / 示例

Filter

object

必填

查询过滤条件。

—

Filter 的子字段 3

Filter 子字段
参数名	类型	必填	说明	默认值 / 示例
`GroupType`	string	必填	待查询的素材组类型，AIGC 表示虚拟人像，LivenessFace 表示真人素材；该查询枚举不代表创建接口支持真人素材组。可选值`AIGCLivenessFace`	示例 `AIGC`
`GroupIds`	array<string>	可选	按素材组 ID 列表筛选；可从创建素材组接口或素材组列表获取 ID。完整复制接口返回的 ID，不要自行添加前缀。	示例 `["YOUR_GROUP_ID"]`
`Name`	string	可选	按完整名称筛选，最长 64 个字符；不要依赖名称前缀或片段匹配。	示例 `demo-portrait`

NextToken

string

可选

凭证分页的翻页凭证；首次查询不填写，后续查询原样填写前次响应中的值。与 PageNumber、PageSize 互斥。

示例: NEXT_TOKEN

MaxResults

integer

可选

凭证分页每页最多返回的记录数，范围为 1 至 100，默认 10；与 PageNumber、PageSize 互斥。

默认值: 10
示例: 10

SortBy

string

可选

排序字段，默认按创建时间排序。

可选值CreateTimeUpdateTime

默认值: CreateTime
示例: CreateTime

SortOrder

string

可选

排序方向，Desc 为降序，Asc 为升序，默认降序。

可选值DescAsc

默认值: Desc
示例: Desc

ProjectName

string

可选

资源所属的项目名称，默认使用 default；资源位于其他项目时，应填写该项目的名称。

默认值: default
示例: default

PageNumber

integer

可选

页码从 1 开始，须与 PageSize 同时使用，且与 NextToken、MaxResults 互斥；PageSize × PageNumber 大于 10000 时应改用凭证分页。

示例: 1

PageSize

integer

可选

页码分页每页记录数，范围为 1 至 100；须与 PageNumber 同时使用，且与 NextToken、MaxResults 互斥；PageSize × PageNumber 大于 10000 时应改用凭证分页。

示例: 10

使用说明

先检查 HTTP 状态，再检查 ResponseMetadata.Error；即使 HTTP 200，该字段非空也表示本次请求失败。请求级错误与 Result.Error 中的素材处理错误分别判断。
推荐使用 NextToken 和 MaxResults 进行凭证分页；首次查询省略 NextToken，有下一页时使用响应中的凭证继续查询。
凭证分页与页码分页互斥：NextToken、MaxResults 不能与 PageNumber、PageSize 混用；页码分页的 PageNumber、PageSize 必须同时提供。
未提供分页参数时默认采用凭证分页，MaxResults 为 10；后续提供 NextToken 时若省略 MaxResults，仍按 10 查询。每页记录数范围为 1 至 100。
凭证分页不返回 TotalCount、PageNumber、PageSize；页码分页会返回这三个字段。未返回 NextToken 表示遍历结束，本页响应模板展示已到最后一页的情况。
后续查询应保持 Filter、ProjectName、SortBy、SortOrder 与首次查询一致；空凭证、被改写的凭证或跨接口、账号、项目复用的凭证无效。
当 PageSize × PageNumber 大于 10000 时，改用 NextToken 实现深翻页。
Filter.GroupType 为必填筛选条件；AIGC 与 LivenessFace 是查询类型，本页的创建动作仅面向虚拟人像素材组。
Name 筛选请填写完整名称；名称片段不保证匹配。Items 为空只表示当前筛选没有匹配资源，不代表素材不存在。

调用示例

# 需要安装 jq，用于检查 Ark 同步业务错误。
response=$(curl --fail-with-body \
  --max-time 120 \
  --request POST \
  'https://app.ai.kedang.net/ark?Action=ListAssetGroups&Version=2024-01-01' \
  -H 'Authorization: sk-YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "Filter": {
    "GroupType": "AIGC"
  },
  "MaxResults": 10,
  "SortBy": "CreateTime",
  "SortOrder": "Desc",
  "ProjectName": "default"
}') || {
  curl_status=$?
  printf '%s\n' "$response" >&2
  exit "$curl_status"
}
if ! printf '%s\n' "$response" | jq -e '.ResponseMetadata.Error == null' >/dev/null; then
  printf '%s\n' "$response" >&2
  exit 1
fi
printf '%s\n' "$response"

# pip install requests
import requests

url = 'https://app.ai.kedang.net/ark?Action=ListAssetGroups&Version=2024-01-01'
headers = {'Authorization': 'sk-YOUR_API_KEY', 'Content-Type': 'application/json'}
payload = {'Filter': {'GroupType': 'AIGC'},
 'MaxResults': 10,
 'SortBy': 'CreateTime',
 'SortOrder': 'Desc',
 'ProjectName': 'default'}

response = requests.request(
    'POST', url, headers=headers, timeout=120, json=payload
)
response.raise_for_status()
data = response.json()
error = (data.get("ResponseMetadata") or {}).get("Error")
if error is not None:
    raise RuntimeError(f"Ark business error: {error}")
print(data)

// Node.js 18+ · 保存为 example.mjs 后运行

const headers = {
  "Authorization": "sk-YOUR_API_KEY",
  "Content-Type": "application/json"
};
const payload = {
  "Filter": {
    "GroupType": "AIGC"
  },
  "MaxResults": 10,
  "SortBy": "CreateTime",
  "SortOrder": "Desc",
  "ProjectName": "default"
};

const response = await fetch("https://app.ai.kedang.net/ark?Action=ListAssetGroups&Version=2024-01-01", {
  method: "POST",
  headers,
  signal: AbortSignal.timeout(120_000),
  body: JSON.stringify(payload),
});
if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}
const data = await response.json();
const error = data.ResponseMetadata?.Error;
if (error != null) {
  throw new Error(`Ark business error: ${JSON.stringify(error)}`);
}
console.log(data);

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"strings"
	"time")

func main() {
	payload := strings.NewReader("{\n  \"Filter\": {\n    \"GroupType\": \"AIGC\"\n  },\n  \"MaxResults\": 10,\n  \"SortBy\": \"CreateTime\",\n  \"SortOrder\": \"Desc\",\n  \"ProjectName\": \"default\"\n}")
	req, err := http.NewRequest("POST", "https://app.ai.kedang.net/ark?Action=ListAssetGroups&Version=2024-01-01", payload)
	if err != nil { log.Fatal(err) }
	req.Header.Set("Authorization", "sk-YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")
	client := &http.Client{Timeout: 120 * time.Second}
	resp, err := client.Do(req)
	if err != nil { log.Fatal(err) }
	defer resp.Body.Close()
	data, err := io.ReadAll(resp.Body)
	if err != nil { log.Fatal(err) }
	if resp.StatusCode >= 400 { log.Fatalf("%s: %s", resp.Status, data) }
	var result struct {
		ResponseMetadata struct {
			Error *struct {
				Code string `json:"Code"`
				Message string `json:"Message"`
			} `json:"Error"`
		} `json:"ResponseMetadata"`
	}
	if err := json.Unmarshal(data, &result); err != nil { log.Fatal(err) }
	if result.ResponseMetadata.Error != nil {
		log.Fatalf("Ark business error: %s: %s", result.ResponseMetadata.Error.Code, result.ResponseMetadata.Error.Message)
	}
	fmt.Println(string(data))
}

响应示例

{
  "ResponseMetadata": {
    "RequestId": "REQUEST_ID",
    "Action": "ListAssetGroups",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Items": [
      {
        "CreateTime": "2026-10-10 16:03:48",
        "Description": "虚拟人像素材组示例",
        "GroupType": "AIGC",
        "Id": "YOUR_GROUP_ID",
        "Name": "demo-portrait-group",
        "ProjectName": "default",
        "UpdateTime": "2026-10-10 16:04:01"
      }
    ]
  }
}