# 创建素材

向指定素材分组中添加一个素材。素材文件需通过 URL 引用，支持图片、视频、音频三种类型。

素材创建后状态为 `Processing`（处理中），处理完成后变为 `Active`（可用）。
可通过 `GET /v1/assets/{assetId}` 轮询素材状态。

素材创建成功后，可在视频生成等接口中通过 `asset://<素材ID>` 格式引用。

**文件大小限制：**

| 类型 | 格式 | 最大大小 |
|---|---|---|
| Image | JPEG, PNG, WebP, GIF, BMP, TIFF, HEIC, HEIF | 30 MB |
| Video | MP4, MOV | 50 MB |
| Audio | WAV, MP3 | 15 MB |

## 图像素材上传规范

**单张图片要求：**
- 格式：JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC / HEIF
- 宽高比（宽/高）：`(0.4, 2.5)`
- 宽高像素：`(300, 6000)`
- 大小：单张小于 30 MB

**多素材同组建议：**
为保证生成视频中人物面部、服装细节与上传素材一致，推荐按以下规则将同一人物的多张素材传入同一资产组：

**人物面部**
- 用途：通过上传面部特写图，让生成视频的人物面部与素材一致
- 版式：竖版，面部占画面 2/3 左右
- 内容：正面无表情特写，肩部以上

**人物服装 + 定妆（推荐单张合成）**
- 用途：同一张图同时锁定面部与服装细节，供视频生成保持人物与穿搭一致
- 版式：横版四联合成图（定妆照 + 前 / 侧 / 后三视图），一次上传即可
- 内容布局（从左到右）：
  1. 定妆照：肩部以上特写，正面或微侧，无夸张表情，面部占本格约 2/3
  2. 全身正面
  3. 全身侧面
  4. 全身背面
- 要求：同一人物、同一套服装；背景简洁统一；光照一致；禁止文字 / 水印

## POST /v1/assets

> 创建素材

向指定素材分组中添加一个素材。素材文件需通过 URL 引用，支持图片、视频、音频三种类型。

素材创建后状态为 `Processing`（处理中），处理完成后变为 `Active`（可用）。
可通过 `GET /v1/assets/{assetId}` 轮询素材状态。

素材创建成功后，可在视频生成等接口中通过 `asset://<素材ID>` 格式引用。

**文件大小限制：**

| 类型 | 格式 | 最大大小 |
|---|---|---|
| Image | JPEG, PNG, WebP, GIF, BMP, TIFF, HEIC, HEIF | 30 MB |
| Video | MP4, MOV | 50 MB |
| Audio | WAV, MP3 | 15 MB |

## 图像素材上传规范

**单张图片要求：**
- 格式：JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC / HEIF
- 宽高比（宽/高）：`(0.4, 2.5)`
- 宽高像素：`(300, 6000)`
- 大小：单张小于 30 MB

**多素材同组建议：**
为保证生成视频中人物面部、服装细节与上传素材一致，推荐按以下规则将同一人物的多张素材传入同一资产组：

**人物面部**
- 用途：通过上传面部特写图，让生成视频的人物面部与素材一致
- 版式：竖版，面部占画面 2/3 左右
- 内容：正面无表情特写，肩部以上

**人物服装 + 定妆（推荐单张合成）**
- 用途：同一张图同时锁定面部与服装细节，供视频生成保持人物与穿搭一致
- 版式：横版四联合成图（定妆照 + 前 / 侧 / 后三视图），一次上传即可
- 内容布局（从左到右）：
  1. 定妆照：肩部以上特写，正面或微侧，无夸张表情，面部占本格约 2/3
  2. 全身正面
  3. 全身侧面
  4. 全身背面
- 要求：同一人物、同一套服装；背景简洁统一；光照一致；禁止文字 / 水印

### Authentication

`Authorization: Bearer tr-xxx`

### Request Body

Content-Type: `application/json`

- **group_id** `string` **(required)**  
  目标素材分组 ID（必须是当前用户拥有的分组）
- **url** `string` **(required)**  
  素材文件的公网可访问 URL
- **asset_type** ``Image` | `Video` | `Audio`` **(required)**  
  素材类型：
- **name** `string`  
  素材名称（可选，不传则由系统自动生成）

### Response

- **Id** `string`  
  素材 ID，可通过 `asset://<Id>` 格式在视频生成等接口中引用
- **Name** `string`  
  素材名称
- **AssetType** ``Image` | `Video` | `Audio``  
  素材类型
- **Status** ``Active` | `Processing` | `Failed``  
  素材处理状态：
- **GroupId** `string`  
  所属分组 ID
- **URL** `string`  
  素材文件 URL
- **CreateTime** `string`  
  创建时间
- **UpdateTime** `string`  
  最后更新时间
- **Error** `object`  
  错误信息，仅当 `Status: Failed` 时有值
- **Error.Code** `string`  
  错误码
- **Error.Message** `string`  
  错误描述

### Error Codes

- `400`: 
- `401`: 
- `403`: 素材分组不属于当前用户
- `429`: 
- `502`: