Doubao · 创建素材组

创建用于归类与管理虚拟人像素材的素材组。

POSThttps://app.ai.kedang.net/ark?Action=CreateAssetGroup&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.Id`	string	素材组 ID。完整复制接口返回的 ID，不要自行添加前缀。

Headers请求头

左右滑动查看完整参数表

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

Query Parameters查询参数

左右滑动查看完整参数表

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

Request Body请求体

application/json

左右滑动查看完整参数表

请求体
参数名	类型	必填	说明	默认值 / 示例
`Name`	string	必填	素材组名称，最长 64 个字符。	示例 `demo-portrait-group`
`Description`	string	可选	素材组描述，最长 300 个字符。	示例 `虚拟人像素材组示例`
`GroupType`	string	可选	素材组类型，目前创建仅支持虚拟人像类型 AIGC，省略时默认为 AIGC。可选值`AIGC`	默认值 `AIGC` 示例 `AIGC`
`ProjectName`	string	可选	资源所属的项目名称，默认使用 default；资源位于其他项目时，应填写该项目的名称。	默认值 `default` 示例 `default`

使用说明

先检查 HTTP 状态，再检查 ResponseMetadata.Error；即使 HTTP 200，该字段非空也表示本次请求失败。请求级错误与 Result.Error 中的素材处理错误分别判断。
本页创建的是虚拟人像素材组，当前仅支持 AIGC 类型。
官方上游文档要求首次创建素材组前在其控制台签署授权函；这项上游要求不代表可当平台已经完成相同的开通或权限配置。
素材库按项目隔离。未填写项目名称时使用默认项目，后续上传与查询应沿用素材组所属的项目。
官方上游管理接口采用访问密钥签名鉴权；本页模板使用可当平台转发入口与平台密钥，平台账户的权限及配置以实际开通情况为准。

调用示例

# 需要安装 jq，用于检查 Ark 同步业务错误。
response=$(curl --fail-with-body \
  --max-time 120 \
  --request POST \
  'https://app.ai.kedang.net/ark?Action=CreateAssetGroup&Version=2024-01-01' \
  -H 'Authorization: sk-YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "Name": "demo-portrait-group",
  "Description": "虚拟人像素材组示例",
  "GroupType": "AIGC",
  "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=CreateAssetGroup&Version=2024-01-01'
headers = {'Authorization': 'sk-YOUR_API_KEY', 'Content-Type': 'application/json'}
payload = {'Name': 'demo-portrait-group',
 'Description': '虚拟人像素材组示例',
 'GroupType': 'AIGC',
 '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 = {
  "Name": "demo-portrait-group",
  "Description": "虚拟人像素材组示例",
  "GroupType": "AIGC",
  "ProjectName": "default"
};

const response = await fetch("https://app.ai.kedang.net/ark?Action=CreateAssetGroup&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  \"Name\": \"demo-portrait-group\",\n  \"Description\": \"虚拟人像素材组示例\",\n  \"GroupType\": \"AIGC\",\n  \"ProjectName\": \"default\"\n}")
	req, err := http.NewRequest("POST", "https://app.ai.kedang.net/ark?Action=CreateAssetGroup&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": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "YOUR_GROUP_ID"
  }
}