# 视频生成概览

> 使用统一任务生命周期创建、查询并获取 UniAI 视频生成结果。

Canonical URL: https://docs.uniai.tv/models/video/overview
Locale: zh-CN

UniAI 视频模型默认共用一套异步任务生命周期。模型 ID、输入字段和能力限制以各模型页面为准；任务轮询、状态处理、错误和结果获取统一以本页为准。

## 模型

- [Hailuo](/models/video/hailuo)
- [Happy Horse](/models/video/happy-horse)
- [Kling](/models/video/kling)
- [MiniMax H3 / H3 Max](/models/video/minimax-h3)
- [Seedance 2.0](/models/video/seedance-2-0)
- [Seedance 2.5](/models/video/seedance-2-5)
- [Vidu Q3](/models/video/vidu)
- [完整模型目录](/models)

## 默认接口

`{BASE_URL}` 为 `https://api.uniai.tv`。

| 操作 | 方法 | 接口 |
| --- | --- | --- |
| 创建任务 | `POST` | `/v1/videos` |
| 查询状态与结果 | `GET` | `/v1/videos/{task_id}` |
| 下载已完成的视频 | `GET` | `/v1/videos/{task_id}/content` |

每次请求都要携带 `Authorization: Bearer sk-***`。部分模型页面会注明兼容创建路径或特定协议例外；模型 ID 和请求体仍以对应模型页面为准。

## 视频任务生命周期

### 1. 保存任务 ID

创建成功后会返回公开 `id`。部分响应还会在 `task_id` 中返回同一个值用于兼容。离开创建流程前应保存其中任意一个。

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "model-name",
  "status": "queued",
  "progress": 0,
  "created_at": 1785801600
}
```

### 2. 轮询任务

每 3 到 10 秒查询一次任务：

```bash
curl "{BASE_URL}/v1/videos/task_xxxxxxxxxxxxx" \
  -H "Authorization: Bearer sk-***"
```

仅当 `status` 变为 `completed` 或 `failed` 时停止轮询。任务仍为 `queued` 或 `in_progress` 时，不要重复创建同一任务。

| 状态 | 终态 | 含义 |
| --- | --- | --- |
| `queued` | 否 | 任务已受理，正在等待处理。 |
| `in_progress` | 否 | 正在生成视频或处理结果。 |
| `completed` | 是 | 最终结果已就绪。 |
| `failed` | 是 | 任务未生成结果；检查 `error`。 |

### 3. 读取结果

任务完成后，可从 `video_url`、`result.video_url` 或 `result.outputs[0]` 读取公开结果。这几个字段可能指向同一个视频。

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "model-name",
  "status": "completed",
  "progress": 100,
  "video_url": "https://example.com/generated-video.mp4",
  "result": {
    "video_url": "https://example.com/generated-video.mp4",
    "outputs": [
      "https://example.com/generated-video.mp4"
    ]
  },
  "error": null
}
```

完成后优先使用返回的 `video_url` 下载视频，也可使用带鉴权的内容接口：

```bash
curl -L "{BASE_URL}/v1/videos/task_xxxxxxxxxxxxx/content" \
  -H "Authorization: Bearer sk-***" \
  -o output.mp4
```

任务完成前不要调用内容接口。生成媒体应及时下载，不要把结果 URL 当作永久存储地址。

### 4. 处理失败

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "model-name",
  "status": "failed",
  "progress": 100,
  "result": null,
  "error": {
    "code": "task_failed",
    "message": "Video generation failed"
  }
}
```

参数错误应先修正输入再创建新任务。临时服务错误可使用退避策略重试，但原任务仍在运行时不要反复提交同一请求。

Seedance 2.5 创建请求失败、客户端超时或结果不确定时，不得自动重试。继续查询已有任务 ID，或先核对原请求结果再重新提交。Draft 转成片也遵守此规则，见[模型专属流程](/models/video/seedance-2-5#draft-to-final)。

## 公共响应字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 用于轮询的公开任务 ID。 |
| `task_id` | string | 存在时为 `id` 的兼容别名。 |
| `object` | string | 任务对象类型，通常为 `video.generation.job`。 |
| `model` | string | 创建任务时使用的公开模型 ID。 |
| `status` | string | `queued`、`in_progress`、`completed` 或 `failed`。 |
| `progress` | integer | 可用时为 `0` 到 `100`；不能代替 `status` 判断终态。 |
| `video_url` | string 或 null | 任务完成后的公开结果 URL。 |
| `result` | object 或 null | 完成后的输出详情，包括 `video_url` 或 `outputs`。 |
| `error` | object 或 null | 失败任务的公开 `code` 和 `message`。 |
| `created_at` | integer | 可用时为 Unix 创建时间戳。 |
| `completed_at` | integer | 可用时为 Unix 完成时间戳。 |

## 模型例外

MiniMax H3 任务详情使用 `task` 对象，状态为 `queued`、`running`、`succeeded`、`failed` 或 `cancelled`。请求与响应示例见 [H3 原生 API](/models/video/minimax-h3)。