Doubao · 查询素材

查询单个素材的预处理状态、错误原因、访问地址和最近任务提交时间。

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

查看请求错误示例

HTTP 200，但 ResponseMetadata.Error 非空，表示请求失败；此时没有 Result。

{
  "ResponseMetadata": {
    "Action": "GetAsset",
    "Service": "ark",
    "Region": "cn-beijing",
    "Error": {
      "CodeN": null,
      "Code": "ResourceNotFound",
      "Message": "素材不存在: YOUR_ASSET_ID"
    }
  }
}

Headers请求头

左右滑动查看完整参数表

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

Query Parameters查询参数

左右滑动查看完整参数表

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

Request Body请求体

application/json

左右滑动查看完整参数表

请求体
参数名	类型	必填	说明	默认值 / 示例
`Id`	string	必填	需要查询的素材 ID，可从对应的创建接口或列表接口获取。完整复制接口返回的 ID，不要自行添加前缀。	示例 `YOUR_ASSET_ID`
`ProjectName`	string	可选	资源所属的项目名称，默认使用 default；资源位于其他项目时，应填写该项目的名称。	默认值 `default` 示例 `default`

使用说明

先检查 HTTP 状态，再检查 ResponseMetadata.Error；即使 HTTP 200，该字段非空也表示本次请求失败。请求级错误与 Result.Error 中的素材处理错误分别判断。
HTTP 200 不代表操作或素材预处理成功；先检查 ResponseMetadata.Error，再检查 Result.Status，并在 Failed 时读取 Result.Error.Code 与 Result.Error.Message。
只有 Active 状态的素材可用于后续推理；Processing 表示尚在预处理，Failed 表示素材处理失败。
处理失败可能与下载、媒体格式、类型、尺寸、时长、帧率、人脸一致性或内容审核有关，具体原因以返回的错误码和错误说明为准。
返回的素材访问地址有效期为 12 小时，应在失效前完成需要的保存操作。
最近推理时间记录任务提交而非处理时间，任务提交成功后无论后续成功或失败都会更新；查询可能有 1–2 分钟延迟。
最近推理时间可能为 null 或省略；按官方规则，省略只表示素材在 2026-07-24 之后没有任务调用记录，不能据此判断素材从未使用。
GetAsset 的 GroupId、ProjectName 可能保留上游值，ListAssets 则提供平台管理值。后续分组筛选使用平台组 ID，管理请求沿用原平台项目，不从详情的上游字段反推。

调用示例

# 需要安装 jq，用于检查 Ark 同步业务错误。
response=$(curl --fail-with-body \
  --max-time 120 \
  --request POST \
  'https://app.ai.kedang.net/ark?Action=GetAsset&Version=2024-01-01' \
  -H 'Authorization: sk-YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "Id": "YOUR_ASSET_ID",
  "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=GetAsset&Version=2024-01-01'
headers = {'Authorization': 'sk-YOUR_API_KEY', 'Content-Type': 'application/json'}
payload = {'Id': 'YOUR_ASSET_ID', '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 = {
  "Id": "YOUR_ASSET_ID",
  "ProjectName": "default"
};

const response = await fetch("https://app.ai.kedang.net/ark?Action=GetAsset&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  \"Id\": \"YOUR_ASSET_ID\",\n  \"ProjectName\": \"default\"\n}")
	req, err := http.NewRequest("POST", "https://app.ai.kedang.net/ark?Action=GetAsset&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": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "AssetType": "Image",
    "CreateTime": "2026-10-01T02:01:00Z",
    "GroupId": "UPSTREAM_GROUP_ID",
    "Id": "YOUR_ASSET_ID",
    "LastInferenceTime": null,
    "Moderation": {
      "Strategy": "Default"
    },
    "Name": "demo-portrait",
    "ProjectName": "UPSTREAM_PROJECT",
    "Status": "Active",
    "UpdateTime": "2026-10-01T02:01:05Z",
    "URL": "https://example.com/virtual-portrait.png",
    "Error": null
  }
}