> ## 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.

# 创建视频生成任务

提交异步视频生成任务。平台受理后立即返回任务 ID，结果通过 [查询视频生成任务](/api/videos/query-task) 获取。

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

## 请求参数

| 参数                        | 类型        | 必填 | 说明                                                                                                                          |
| ------------------------- | --------- | -- | --------------------------------------------------------------------------------------------------------------------------- |
| `model`                   | string    | 是  | 平台开通的视频模型名称，例如 `dreamina-seedance-2-0`、`dreamina-seedance-2-0-mini`、`dreamina-seedance-2-0-fast`。实际可用名称以 `/v1/models` 返回为准。 |
| `content`                 | object\[] | 是  | 输入内容数组，至少包含一项。支持 `text`、`image_url`、`video_url`、`audio_url` 混合。                                                             |
| `generate_audio`          | boolean   | 否  | 是否生成同步音频。`true` 为有声视频，`false` 为无声视频。                                                                                        |
| `resolution`              | string    | 否  | 视频分辨率：`480p`、`720p`、`1080p`。部分快速模型可能不支持 `1080p`。                                                                            |
| `ratio`                   | string    | 否  | 视频宽高比，如 `16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`21:9`、`adaptive`。                                                                  |
| `duration`                | integer   | 否  | 视频时长（秒）。常见范围为 `[4, 15]`，也可能支持 `-1` 让模型自选。                                                                                   |
| `watermark`               | boolean   | 否  | 是否添加水印。                                                                                                                     |
| `seed`                    | integer   | 否  | 随机种子。                                                                                                                       |
| `safety_identifier`       | string    | 否  | 终端用户唯一标识，用于安全审核。                                                                                                            |
| `execution_expires_after` | integer   | 否  | 任务超时时间，单位秒。                                                                                                                 |
| `service_tier`            | string    | 否  | 服务等级。当前只开放控制台允许的值。                                                                                                          |
| `callback_url`            | string    | 否  | 任务状态回调地址。                                                                                                                   |
| `return_last_frame`       | boolean   | 否  | 是否返回尾帧图片。                                                                                                                   |

<Warning>
  以下字段当前不支持，传入返回 400：`frames`、`service_tier=flex`、`dreamina-seedance-2-0-fast + resolution=1080p`。

  不要在请求中传入 `price_class_code` 或其他平台内部字段。
</Warning>

## content 输入

### 文本 `type: text`

```json theme={null}
{
  "type": "text",
  "text": "生成一段城市夜景视频，镜头缓慢推进，霓虹反射在雨后的路面上"
}
```

### 图片 `type: image_url`

```json theme={null}
{
  "type": "image_url",
  "image_url": { "url": "https://example.com/product.png" },
  "role": "first_frame"
}
```

`role` 建议值包括 `first_frame`、`last_frame`、`reference_image`.

### 视频 `type: video_url`

```json theme={null}
{
  "type": "video_url",
  "video_url": { "url": "https://example.com/reference.mp4" },
  "role": "reference_video"
}
```

### 音频 `type: audio_url`

```json theme={null}
{
  "type": "audio_url",
  "audio_url": { "url": "https://example.com/bgm.mp3" },
  "role": "reference_audio"
}
```

## 示例

### 文生视频

```bash theme={null}
curl -X POST "https://{your-domain}/v1/videos/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0",
    "content": [
      {
        "type": "text",
        "text": "生成一段 5 秒的城市夜景视频，镜头缓慢推进，霓虹灯反射在雨后的路面上"
      }
    ],
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "generate_audio": true,
    "watermark": false
  }'
```

### 图生视频

```bash theme={null}
curl -X POST "https://{your-domain}/v1/videos/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0-mini",
    "content": [
      {
        "type": "text",
        "text": "让画面中的产品在干净的工作台上缓慢旋转，镜头轻微推进"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/product.png" },
        "role": "first_frame"
      }
    ],
    "duration": 5,
    "resolution": "720p",
    "ratio": "1:1",
    "watermark": false
  }'
```

### 使用素材

先调用 [创建素材](/api/videos/create-asset) 上传素材，再把返回的 `uri` 传给视频任务。

```bash theme={null}
curl -X POST "https://{your-domain}/v1/videos/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0-fast",
    "content": [
      {
        "type": "text",
        "text": "参考图人物站在城市街道上，镜头缓慢推进，电影感强"
      },
      {
        "type": "image_url",
        "image_url": { "url": "asset://asset_6f9a4c2b8d1e3a90" },
        "role": "reference_image"
      }
    ],
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "watermark": false
  }'
```

## 成功响应

HTTP 状态码：`202 Accepted`

```json theme={null}
{
  "id": "vidtask_3cb6299b32d24f93a82e8a74b3e06161",
  "object": "video.generation.task",
  "created": 1779782400,
  "model": "dreamina-seedance-2-0",
  "status": "queued",
  "expires_at": 1779955200
}
```

## 错误码

| HTTP 状态码 | `error.type`              | 场景                          |
| -------- | ------------------------- | --------------------------- |
| 400      | `invalid_request_error`   | 缺少 `model`、`content`，或参数超范围 |
| 400      | `endpoint_not_configured` | 模型视频能力未启用                   |
| 400      | `model_endpoint_mismatch` | 模型不能通过视频接口调用                |
| 402      | `insufficient_balance`    | 余额不足，无法创建任务                 |
| 403      | `model_not_allowed`       | API Key 白名单未包含该模型           |
| 404      | `task_not_found`          | 任务不存在，或不属于当前 API Key        |
| 429      | `quota_exceeded`          | API Key 配额不足                |