Doubao · 上传素材

向指定素材组提交一个图像、视频或音频文件，返回素材 ID 后查询预处理状态。

POSThttps://app.ai.kedang.net/ark?Action=CreateAsset&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	必填	需要执行的素材库管理动作。	示例 `CreateAsset`
`Version`	string	必填	素材库管理接口的固定版本号。	示例 `2024-01-01`

Request Body请求体

application/json

左右滑动查看完整参数表

请求体
参数名	类型	必填	说明	默认值 / 示例
`GroupId`	string	必填	素材所属的素材组 ID。完整复制接口返回的 ID，不要自行添加前缀。	示例 `YOUR_GROUP_ID`
`URL`	string	必填	素材文件的公共可访问地址，仅支持 URL，不支持 Base64 编码。	示例 `https://example.com/virtual-portrait.png`
`AssetType`	string	必填	素材类型，必须与文件实际类型一致。可选值`ImageVideoAudio`	示例 `Image`
`Name`	string	可选	素材名称，最长 64 个字符；用于完整名称检索，不会被带入模型推理。	示例 `demo-portrait`
`ProjectName`	string	可选	平台管理项目名称，默认 default；应与建组请求的项目保持一致。GetAsset 返回的上游项目不直接作为下一次管理请求的 ProjectName。	默认值 `default` 示例 `default`

使用说明

先检查 HTTP 状态，再检查 ResponseMetadata.Error；即使 HTTP 200，该字段非空也表示本次请求失败。请求级错误与 Result.Error 中的素材处理错误分别判断。
每次请求提交一个文件，仅支持公共可访问的文件 URL，不支持 Base64 编码内容。
上传属于异步处理，可能排队且不承诺固定入库耗时；视频素材通常需要更长处理时间。
获取素材 ID 后调用 GetAsset 查询状态：Processing 继续等待，Active 方可用于后续推理，Failed 应检查错误原因并处理。
图像支持 jpeg、png、webp、tiff、gif、heic、heif；宽高比范围为 (0.4, 2.5)，宽高长度范围为 (300, 6000) 像素，两个区间均不含边界；单张大小须小于 30 MB。
视频支持 mp4、mov，分辨率可为 480p、720p、1080p、4K；时长为 2–30 秒，宽高比为 0.4–2.5，宽高长度为 300–6000 像素，总像素数为 407696–8295044，帧率为 24–60，以上区间均含边界；大小不超过 200 MB。
音频支持 wav、mp3；时长为 2–30 秒，包含区间边界，大小不超过 15 MB。不同模型支持的音视频输入时长可能不同，应保留原文件的时长信息。
素材名称用于管理与搜索，不作为模型提示词或推理输入；素材项目名称必须与所属素材组一致。
官方指南面向拥有合法使用与处分权限的虚拟人像素材，并要求素材不侵犯第三方权益；平台的权限、服务开通与收费配置应另行核实。

调用示例

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

const response = await fetch("https://app.ai.kedang.net/ark?Action=CreateAsset&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  \"GroupId\": \"YOUR_GROUP_ID\",\n  \"URL\": \"https://example.com/virtual-portrait.png\",\n  \"AssetType\": \"Image\",\n  \"Name\": \"demo-portrait\",\n  \"ProjectName\": \"default\"\n}")
	req, err := http.NewRequest("POST", "https://app.ai.kedang.net/ark?Action=CreateAsset&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": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "YOUR_ASSET_ID"
  }
}