创建素材

Authorization

AuthorizationBearer <token>

兼容网关 API Key，例如 sk-...。

In: header

Query Parameters

Action*string

Default"CreateAsset"

Version*string

Default"2024-01-01"

Header Parameters

X-Date?string

使用 HMAC-SHA256 时必填，格式为 YYYYMMDDTHHMMSSZ。

X-Content-Sha256?string

使用 HMAC-SHA256 时必填，请求体 SHA-256 小写十六进制。

Request Body

application/json

GroupId?string

素材所属的素材组 ID。

URL?string

公共可访问的素材 URL，不支持 Base64。

Formaturi

Name?string

仅用于列表搜索，不会带入模型推理。

Lengthlength <= 64

AssetType?string

Value in"Image" | "Video" | "Audio"

ProjectName?string

资源所属项目名称，必须与目标素材组的 ProjectName 一致。

Default"default"

Response Body

application/json

curl -X POST "https://jieyun.cc/?Action=CreateAsset&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId": "group-202607210001-example",
    "URL": "https://example.com/assets/product.png",
    "Name": "产品主图",
    "AssetType": "Image",
    "ProjectName": "default"
  }'

curl -X POST "https://jieyun.cc/?Action=CreateAsset&Version=2024-01-01" \  -H "Content-Type: application/json" \  -d '{    "GroupId": "group-202607210001-example",    "URL": "https://example.com/assets/product.png",    "Name": "产品主图",    "AssetType": "Image",    "ProjectName": "default"  }'

{
  "ResponseMetadata": {
    "RequestId": "20260721000000000000000000000000",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-202607210001-example"
  }
}

{
  "ResponseMetadata": {
    "RequestId": "string",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing",
    "Error": {
      "Code": "string",
      "Message": "string"
    }
  }
}

Empty

接口说明

通过公共可访问 URL，在指定素材组中创建图片、视频或音频素材。该接口为异步接口，返回素材 ID 只表示素材已进入预处理队列。本文档已按火山引擎官方接口说明校对。

POST https://jieyun.cc/?Action=CreateAsset&Version=2024-01-01
Content-Type: application/json
Authorization: Bearer <API_KEY>

也可使用 AK/SK HMAC-SHA256 签名，详见素材库认证与签名。

异步处理

素材创建后可能处于 Processing。系统不承诺入库时间 SLA，视频素材通常需要更长处理时间。请轮询 GetAsset，直到状态变为 Active 或 Failed。

请求参数

字段	类型	必选	说明
`GroupId`	string	业务必选	素材所属的素材组 ID。
`URL`	string	业务必选	公共可访问的素材 URL；不支持 Base64。
`Name`	string	否	素材名称，最长 64 个字符；仅用于列表搜索，不会带入模型推理。
`AssetType`	string	业务必选	`Image`、`Video` 或 `Audio`。
`ProjectName`	string	否	默认 `default`；必须与目标素材组的项目名称一致。

素材限制

类型	格式	时长 / 尺寸	大小限制
图片	jpeg、png、webp、bmp、tiff、gif、heic、heif	宽高比 `(0.4, 2.5)`，边长 `(300, 6000)` px	小于 30 MB
视频	mp4、mov	480p/720p/1080p，2–15 秒，宽高比 `[0.4, 2.5]`，24–60 FPS	不超过 200 MB
音频	wav、mp3	2–15 秒	不超过 15 MB

{
  "GroupId": "group-2026-example",
  "URL": "https://example.com/image.jpg",
  "Name": "产品正面图",
  "AssetType": "Image",
  "ProjectName": "default"
}

响应内容

成功响应的 Result.Id 是素材 ID。请使用该 ID 调用 GetAsset 查询预处理状态。

{
  "ResponseMetadata": {
    "RequestId": "20260328000000000000000000000000",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "Asset-2026-example"
  }
}

200application/json

400application/json

401

403

404

503

application/json

application/json