创建素材

提交公网 HTTPS 素材 URL，平台会先下载、校验并保存到素材库，然后返回素材 ID 和 uri。

POST /v1/assets
Authorization: Bearer <API_KEY>
Content-Type: application/json

创建素材是一个异步接口。受理后通常先返回 status=processing，需要轮询查询素材直到变成 status=active，之后才能在视频生成中使用。

视频生成请求中请使用 uri 字段的值，也就是 asset://asset_xxx 这种格式，不要直接传 id。传入时请保留 asset:// 前缀。

请求参数

参数	类型	必填	说明
`asset_type`	string	是	素材类型：`image`、`video`、`audio`。
`source_url`	string	是	可公网访问的 HTTPS URL。平台会下载并保存该素材。
`name`	string	否	素材名称，仅用于展示；不传时使用默认名称。

素材格式要求

类型	格式	大小限制
图片	`jpeg`、`png`、`webp`、`bmp`、`tiff`、`gif`	小于 30 MB，建议分辨率 300 到 4000 px
视频	`mp4`、`mov`	小于 50 MB，建议 2 到 5 秒
音频	`wav`、`mp3`	小于 15 MB，建议 2 到 5 秒

示例

curl -X POST "https://{your-domain}/v1/assets" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "avatar-reference",
    "asset_type": "image",
    "source_url": "https://example.com/avatar-reference.png"
  }'

成功响应

HTTP 状态码：202 Accepted

{
  "id": "asset_6f9a4c2b8d1e3a90",
  "uri": "asset://asset_6f9a4c2b8d1e3a90",
  "object": "asset",
  "asset_type": "image",
  "name": "avatar-reference",
  "status": "processing",
  "created_at": 1779782400,
  "updated_at": 1779782400
}

响应字段

字段	类型	说明
`id`	string	平台素材 ID，格式为 `asset_xxx`。
`uri`	string	素材 URI，格式为 `asset://asset_xxx`。视频生成时使用这个字段。
`object`	string	固定为 `asset`。
`asset_type`	string	素材类型。
`name`	string	素材名称。
`status`	string	素材状态，见下方说明。
`created_at`	integer	创建时间，Unix 秒。
`updated_at`	integer	最近更新时间，Unix 秒。

素材状态

状态	说明	是否可用于视频生成	下一步
`processing`	平台已受理，正在保存或处理。	否	继续轮询
`active`	素材可用。	是	可以用于视频生成
`failed`	素材处理失败。	否	重新上传
`disabled`	素材已被平台禁用。	否	联系平台

错误码

HTTP 状态码	`error.type`	场景
400	`invalid_asset_type`	`asset_type` 不是 `image`、`video` 或 `audio`。
400	`invalid_asset_name`	`name` 包含不支持的字符。
400	`invalid_asset_url`	`source_url` 不是 HTTPS、不可公网访问，或格式不合法。
503	`asset_store_unavailable`	平台素材存储未配置。

开始使用

模型与计费

指南

请求参数

素材格式要求

示例

成功响应

响应字段

素材状态

错误码

​请求参数

​素材格式要求

​示例

​成功响应

​响应字段

​素材状态

​错误码

请求参数

素材格式要求

示例

成功响应

响应字段

素材状态

错误码