> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iviker.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建素材

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

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

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

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

## 请求参数

| 参数           | 类型     | 必填 | 说明                            |
| ------------ | ------ | -- | ----------------------------- |
| `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 秒          |

## 示例

```bash theme={null}
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`

```json theme={null}
{
  "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` | 平台素材存储未配置。                                 |