# Seedance 2.0 素材库

> 使用 UniAI API Key 创建素材，等待可用后将返回的 URI 用于 Seedance 视频生成，并查询列表或删除素材。

Canonical URL: https://docs.uniai.tv/models/video/seedance-2-0/material-library
Locale: zh-CN

创建可复用的图片、视频或音频素材，再将返回的 `uri` 用于 Seedance 视频请求。

所有请求使用 `https://api.uniai.tv`，通过 `Authorization: Bearer $UNIAI_API_KEY` 鉴权。

## 1. 创建素材

`POST /v1/materials` 需携带 `Idempotency-Key` 请求头，正文使用 JSON：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `url` | string | 是 | 公网可访问的 HTTP(S) 媒体 URL，最长 4,096 个字符。 |
| `type` | string | 是 | `image`、`video` 或 `audio`，须与素材类型一致。 |
| `name` | string | 否 | 素材名称，最多 64 个字符。 |

```bash
curl "https://api.uniai.tv/v1/materials" \
  -H "Authorization: Bearer $UNIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-reference-001" \
  -d '{
    "url": "https://cdn.example.com/product.png",
    "type": "image",
    "name": "Product reference"
  }'
```

HTTP `202` 响应：

```json
{
  "id": "mat_EXAMPLE",
  "object": "material",
  "name": "Product reference",
  "type": "image",
  "status": "processing",
  "uri": null,
  "preview_url": null,
  "created_at": "2026-10-29T10:00:00Z",
  "available_at": null,
  "expires_at": null
}
```

- 幂等键使用 1–200 个不含空格的可见 ASCII 字符。同一请求使用原键重试会返回同一素材；参数不同则返回 HTTP `409`（`material_idempotency_conflict`）。请求超时后使用原键重试。
- URL 在处理期间须保持公网可访问，不依赖登录、Cookie 或自定义请求头。当前网页“创建素材”填写来源 URL；此 API 接收 JSON URL，不接收 multipart 文件或 Base64。本地文件请先准备为可公开访问的 HTTP(S) URL。

<p className="uni-material-important"><strong>真人图片、视频也使用相同创建请求；如接口返回额外验证提示，以接口提示为准。</strong></p>

## 2. 等待素材可用

使用创建响应中的 `id`，每 3–5 秒查询一次，直到 `status` 为 `available`：

```bash
curl "https://api.uniai.tv/v1/materials/mat_EXAMPLE" \
  -H "Authorization: Bearer $UNIAI_API_KEY"
```

响应示例，时间仅作示意：

```json
{
  "id": "mat_EXAMPLE",
  "object": "material",
  "name": "Product reference",
  "type": "image",
  "status": "available",
  "uri": "asset://asset-EXAMPLE",
  "preview_url": "https://cdn.example.com/preview.png",
  "created_at": "2026-10-29T10:00:00Z",
  "available_at": "2026-10-29T10:01:00Z",
  "expires_at": "2026-10-30T12:00:00Z"
}
```

直接使用接口返回的 `uri`。`mat_*` 是查询和删除素材的 ID，不要用它自行拼接 `asset://` URI。素材有效期以 `expires_at` 为准，请在到期前使用。

| 状态 | 处理方式 |
| --- | --- |
| `creating`、`processing` | 继续查询。 |
| `available` | 可以使用返回的 `uri`。 |
| `failed` | 查看 `error.code` 和 `error.message`；需要重新创建时使用新的幂等键。 |
| `delete_pending`、`deleted` | 停止使用素材。 |

## 3. 使用 URI 生成视频

将下方 `asset://asset-EXAMPLE` 替换为可用图片素材返回的 `uri`：

```bash
curl "https://api.uniai.tv/v1/videos" \
  -H "Authorization: Bearer $UNIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0-fast",
    "resolution": "480p",
    "duration": 4,
    "aspect_ratio": "16:9",
    "generate_audio": false,
    "content": [
      {
        "type": "text",
        "text": "Keep the product appearance consistent as the camera slowly moves around it."
      },
      {
        "type": "image_url",
        "image_url": {"url": "asset://asset-EXAMPLE"},
        "role": "reference_image"
      }
    ]
  }'
```

URI 放在 `image_url.url` 等结构化媒体字段中，不要写进提示词。视频和音频素材分别使用对应的 `video_url`、`audio_url` 字段。素材须属于同一 UniAI 用户，状态可用且未过期。

创建后使用返回的视频任务 ID [查询视频并获取结果](/models/video/overview#视频任务生命周期)。

## 素材列表

```bash
curl "https://api.uniai.tv/v1/materials?type=image&status=available&limit=20" \
  -H "Authorization: Bearer $UNIAI_API_KEY"
```

响应包含 `data`、`has_more` 和 `next_cursor`。可用 `type`、`status` 筛选；`limit` 为 1–100，默认 `50`。下一页将返回的 `next_cursor` 原样放入 `after`。已过期或已删除素材不出现在列表中。

## 删除素材

```bash
curl -X DELETE "https://api.uniai.tv/v1/materials/mat_EXAMPLE" \
  -H "Authorization: Bearer $UNIAI_API_KEY"
```

HTTP `200` 且 `status: "deleted"` 表示删除完成；HTTP `202` 且 `status: "delete_pending"` 表示仍在处理中。可以重复 DELETE。删除完成后素材从列表消失，详情接口返回 `404 material_not_found`。

## 请求错误

| 错误码 | 检查方式 |
| --- | --- |
| `invalid_idempotency_key` | 创建时携带有效的 `Idempotency-Key`。 |
| `invalid_material_request` | 检查 URL、素材类型及名称长度。 |
| `material_idempotency_conflict` | 使用原请求和原键重试，或为不同素材换用新键。 |
| `material_not_found` | 检查 ID 和当前用户；素材可能已删除或过期。 |
| `material_not_available` | 等待 `available`，并检查 `expires_at`。 |
| `material_not_managed` | 从素材响应复制 `uri`，不要自行拼接。 |

视频生成参数见 [Seedance 2.0 系列指南](/models/video/seedance-2-0/series-guide)。