Doubao · 查询素材列表

按素材组、素材名称和状态筛选素材，查询素材信息并分页遍历。

POSThttps://app.ai.kedang.net/ark?Action=ListAssets&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[].AssetType`	string	素材类型：Image 为图像，Video 为视频，Audio 为音频。
`Result.Items[].CreateTime`	string	素材的创建时间。
`Result.Items[].Error`	object\|null	素材处理失败时的错误信息，可结合 Status 判断素材是否可用。素材可用时可能为 null 或空错误信息对象，不能仅按此字段是否存在判断失败。
`Result.Items[].Error.Code`	string	素材处理失败的错误码，例如 DownloadFailed 表示下载素材失败，FormatUnsupported 表示素材格式不受支持。
`Result.Items[].Error.Message`	string	素材处理失败的错误说明，与 Error.Code 一同用于排查原因。
`Result.Items[].GroupId`	string	素材所属的平台素材组 ID，GroupIds 筛选使用此值或 CreateAssetGroup 返回的 ID；完整复制，不自行添加前缀。
`Result.Items[].Id`	string	素材 ID。完整复制接口返回的 ID，不要自行添加前缀。
`Result.Items[].LastInferenceTime`	string\|null	素材最近一次提交至视频生成任务的时间，使用 RFC 3339 格式，精确到秒且不含小数秒。记录的是任务提交时间，非任务处理时间；提交成功后，无论任务后续成功或失败均会更新。新任务提交后可能延迟 1–2 分钟才在查询结果中更新；若素材在 2026-07-24 之后未被任务调用，则不返回该字段。平台可返回 null；空值与省略均不能据此判定素材从未使用。
`Result.Items[].Moderation`	object	素材的内容审核信息。
`Result.Items[].Moderation.Strategy`	string	素材的内容审核策略，官方定义为 Default；平台处理中记录的策略也可能为空字符串。使用 Status 判断是否可用，不以此字段代替素材状态。
`Result.Items[].Name`	string	素材名称，最长 64 个字符；用于管理与名称搜索，不会传入模型推理。
`Result.Items[].ProjectName`	string	素材所属的平台管理项目名称；与请求项目对应，和 GetAsset 的上游项目可能不同。
`Result.Items[].Status`	string	素材状态：Active 表示预处理完成、可用于推理；Processing 表示正在预处理、暂不可用；Failed 表示处理失败、不可用。
`Result.Items[].UpdateTime`	string	素材的更新时间。
`Result.Items[].URL`	string	素材的可访问地址，有效期为 12 小时；如需保存，应在地址失效前完成。
`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	必填	需要执行的素材库管理动作。	示例 `ListAssets`
`Version`	string	必填	素材库管理接口的固定版本号。	示例 `2024-01-01`

Request Body请求体

application/json

左右滑动查看完整参数表

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

Filter

object

必填

查询过滤条件。

—

Filter 的子字段 4

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

NextToken

string

可选

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

示例: NEXT_TOKEN

MaxResults

integer

可选

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

默认值: 10
示例: 10

SortBy

string

可选

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

可选值CreateTimeUpdateTimeGroupId

默认值: CreateTime
示例: CreateTime

SortOrder

string

可选

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

可选值DescAsc

默认值: Desc
示例: Desc

ProjectName

string

可选

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

默认值: default
示例: default

PageNumber

integer

可选

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

示例: 1

PageSize

integer

可选

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

示例: 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 大于 20000 时，改用 NextToken 实现深翻页。
Filter.GroupType 为必填筛选条件；AIGC 与 LivenessFace 是查询类型，本页的创建动作仅面向虚拟人像素材组。
返回的素材访问地址有效期为 12 小时，应在失效前完成需要的保存操作。
最近推理时间记录任务提交而非处理时间，任务提交成功后无论后续成功或失败都会更新；查询可能有 1–2 分钟延迟。
最近推理时间可能为 null 或省略；按官方规则，省略只表示素材在 2026-07-24 之后没有任务调用记录，不能据此判断素材从未使用。
Name 筛选请填写完整名称；名称片段不保证匹配。Items 为空只表示当前筛选没有匹配资源，不代表素材不存在。
GetAsset 的 GroupId、ProjectName 可能保留上游值，ListAssets 则提供平台管理值。后续分组筛选使用平台组 ID，管理请求沿用原平台项目，不从详情的上游字段反推。

调用示例

# 需要安装 jq，用于检查 Ark 同步业务错误。
response=$(curl --fail-with-body \
  --max-time 120 \
  --request POST \
  'https://app.ai.kedang.net/ark?Action=ListAssets&Version=2024-01-01' \
  -H 'Authorization: sk-YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "Filter": {
    "GroupType": "AIGC",
    "GroupIds": [
      "YOUR_GROUP_ID"
    ],
    "Statuses": [
      "Active"
    ]
  },
  "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=ListAssets&Version=2024-01-01'
headers = {'Authorization': 'sk-YOUR_API_KEY', 'Content-Type': 'application/json'}
payload = {'Filter': {'GroupType': 'AIGC',
            'GroupIds': ['YOUR_GROUP_ID'],
            'Statuses': ['Active']},
 '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",
    "GroupIds": [
      "YOUR_GROUP_ID"
    ],
    "Statuses": [
      "Active"
    ]
  },
  "MaxResults": 10,
  "SortBy": "CreateTime",
  "SortOrder": "Desc",
  "ProjectName": "default"
};

const response = await fetch("https://app.ai.kedang.net/ark?Action=ListAssets&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    \"GroupIds\": [\n      \"YOUR_GROUP_ID\"\n    ],\n    \"Statuses\": [\n      \"Active\"\n    ]\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=ListAssets&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": "ListAssets",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Items": [
      {
        "AssetType": "Image",
        "CreateTime": "2026-10-01T02:01:00Z",
        "GroupId": "YOUR_GROUP_ID",
        "Id": "YOUR_ASSET_ID",
        "LastInferenceTime": null,
        "Moderation": {
          "Strategy": "Default"
        },
        "Name": "demo-portrait",
        "ProjectName": "default",
        "Status": "Active",
        "UpdateTime": "2026-10-01T02:01:05Z",
        "URL": "https://example.com/virtual-portrait.png",
        "Error": {
          "Code": "",
          "Message": ""
        }
      }
    ]
  }
}