# 创建素材

向指定素材分组中添加一个素材。素材文件需通过 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

> Create asset

Add an asset to a specified asset group. Asset files are referenced via URL and support image, video, and audio types.

After creation, the asset status is `Processing`. Once processing completes, it changes to `Active`.
Poll asset status via `GET /v1/assets/{assetId}`.

After successful creation, assets can be referenced in video generation and other endpoints using the `asset://<ASSET_ID>` format.

**File size limits:**

| Type | Formats | Max Size |
|---|---|---|
| Image | JPEG, PNG, WebP, GIF, BMP, TIFF, HEIC, HEIF | 30 MB |
| Video | MP4, MOV | 50 MB |
| Audio | WAV, MP3 | 15 MB |

## Image Asset Upload Guidelines

**Per-image requirements:**
- Formats: JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC / HEIF
- Aspect ratio (width/height): `(0.4, 2.5)`
- Width/height pixels: `(300, 6000)`
- Size: under 30 MB per image

**Multi-asset group recommendations:**
To ensure generated video preserves facial features and clothing details consistent with uploaded assets, it is recommended to upload multiple images of the same person into the same asset group following these guidelines:

**Face close-up**
- Purpose: Upload a facial close-up to ensure the generated video face matches the asset
- Orientation: Portrait, face occupying approximately 2/3 of the frame
- Content: Front-facing, neutral expression close-up, shoulders and above

**Clothing detail**
- Purpose: Upload three-view images (front / side / back) of the same person to ensure clothing details match
- Orientation: Landscape, three views arranged side by side

### Authentication

`Authorization: Bearer tr-xxx`

### Request Body

Content-Type: `application/json`

- **group_id** `string` **(required)**  
  Target asset group ID (must be a group owned by the current user)
- **url** `string` **(required)**  
  Publicly accessible URL of the asset file
- **asset_type** ``Image` | `Video` | `Audio`` **(required)**  
  Asset type:
- **name** `string`  
  Asset name (optional; auto-generated by the system if not provided)

### Response

- **Id** `string`  
  Asset ID. Can be referenced in video generation and other endpoints using `asset://<Id>` format
- **Name** `string`  
  Asset name
- **AssetType** ``Image` | `Video` | `Audio``  
  Asset type
- **Status** ``Active` | `Processing` | `Failed``  
  Asset processing status:
- **GroupId** `string`  
  Parent group ID
- **URL** `string`  
  Asset file URL
- **CreateTime** `string`  
  Creation time
- **UpdateTime** `string`  
  Last updated time
- **Error** `object`  
  Error information. Only present when `Status: Failed`
- **Error.Code** `string`  
  Error code
- **Error.Message** `string`  
  Error description

### Error Codes

- `400`: 
- `401`: 
- `403`: Asset group does not belong to the current user
- `429`: 
- `502`: