---
url: https://limapi.com/docs/guide/videos.md
---
# 视频生成 Videos

## 提交视频生成任务

```
POST /api/v1/videos
Authorization: Bearer sk-xxx
Content-Type: application/json
```

异步视频生成接口，提交任务后返回 taskId，通过轮询获取结果。

### Request

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| model | string | \* | 视频生成模型 ID，如 `happyhorse-1.1-t2v`、`wan2.7-i2v` |
| prompt | string | \* | 视频描述文本 |

### HappyHorse 子模型参数说明

HappyHorse 系列视频模型根据子模型类型不同，所需参数也不同。**请根据你使用的模型 ID 后缀判断子模型类型：**

| 子模型类型 | 模型 ID 后缀 | 必需参数 | 可选参数 | 说明 |
|-----------|-------------|---------|---------|------|
| **t2v**（文生视频） | `-t2v` | `model`, `prompt` | `size`, `duration` | 纯文本描述生成视频，无需图片 |
| **i2v**（图生视频） | `-i2v` | `model`, `prompt`, `first_frame_url` | `size`, `duration`, `last_frame_url` | 从首帧图片生成视频 |
| **r2v**（参考图视频） | `-r2v` | `model`, `prompt`, `ref_image_urls` | `size`, `duration` | 参考一张或多张图片生成视频 |
| **video-edit**（视频编辑） | `video-edit` | `model`, `prompt`, `video_url` | `size` | 对输入视频做编辑；输出时长跟随输入视频，`duration` 对该族不生效 |

**各参数详细说明：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `first_frame_url` | string | 首帧图片 URL（i2v 必需） |
| `video_url` | string | 待编辑视频的 URL（video-edit 必需；旧写法把视频地址填进 `first_frame_url` / `image_url` 同样接受） |
| `last_frame_url` | string | 尾帧图片 URL（仅 i2v 可选，用于首尾帧控制） |
| `ref_image_urls` | array | 参考图 URL 数组（r2v 必需），如 `["https://...jpg"]` |
| `size` | string | 视频分辨率，如 `1920*1080`、`1280*720` |
| `duration` | number | 请求的视频时长（秒），不传按 5 秒。**对 video-edit 族只是预扣基数，不改变实际输出长度**，见下方「计费说明」 |

### 请求示例

**t2v 文生视频：**

```json
{
  "model": "happyhorse-1.1-t2v",
  "prompt": "一只金毛犬在海边奔跑，阳光明媚，慢动作"
}
```

**i2v 图生视频：**

```json
{
  "model": "happyhorse-1.1-i2v",
  "prompt": "图片中的人物缓缓转身微笑",
  "first_frame_url": "https://example.com/photo.jpg"
}
```

**r2v 参考图视频：**

```json
{
  "model": "happyhorse-1.1-r2v",
  "prompt": "参考图中的人物在公园里散步",
  "ref_image_urls": ["https://example.com/ref1.jpg", "https://example.com/ref2.jpg"]
}
```

**video-edit 视频编辑：**

```json
{
  "model": "happyhorse-1.0-video-edit",
  "prompt": "把画面改成夜晚，霓虹灯反光",
  "video_url": "https://example.com/input.mp4"
}
```

**Wan2.7 i2v 首尾帧控制：**

```json
{
  "model": "wan2.7-i2v",
  "prompt": "从第一帧过渡到最后一帧，花瓣飘落",
  "first_frame_url": "https://example.com/start.jpg",
  "last_frame_url": "https://example.com/end.jpg"
}
```

### 错误提示

如果缺少必需参数，接口会返回清晰的错误提示：

```json
{
  "code": 400,
  "msg": "模型 happyhorse-1.1-i2v 为图生视频(i2v)模型，必须提供 first_frame_url（首帧图片URL）。示例: {\"model\": \"happyhorse-1.1-i2v\", \"prompt\": \"...\", \"first_frame_url\": \"https://...\"}"
}
```

## 查询任务状态

```
GET /api/v1/videos/{taskId}
Authorization: Bearer sk-xxx
```

**状态说明：**

| task\_status | 含义 | 说明 |
|-------------|------|------|
| `PENDING` | 排队中 | 任务已提交，等待处理 |
| `RUNNING` | 生成中 | 视频正在生成 |
| `SUCCEEDED` | 已完成 | 生成成功，返回 video\_url |
| `FAILED` | 失败 | 生成失败，已自动退款 |

**PENDING / RUNNING 响应：**

```json
{
  "request_id": "xxx",
  "output": {
    "task_id": "6eea9a05-eb65-48eb-9ed1-4d2f0908994c",
    "task_status": "PENDING"
  }
}
```

**SUCCEEDED 响应：**

```json
{
  "request_id": "xxx",
  "output": {
    "task_id": "6eea9a05-eb65-48eb-9ed1-4d2f0908994c",
    "task_status": "SUCCEEDED",
    "video_url": "https://dashscope.oss.aliyuncs.com/xxx.mp4"
  },
  "usage": {
    "duration": 5,
    "video_count": 1
  }
}
```

> 💡 **建议轮询间隔 5~10 秒**，视频生成通常需要 1~3 分钟。

## 计费说明

视频按**秒**计价，单价由模型与分辨率档决定。**计费秒数取上游实际交付的时长，也就是轮询响应里的 `usage.duration`**，不是请求里填的那个数。

扣费分两步：

1. **提交任务时预扣** —— 按请求的 `duration`（不传按 5 秒）乘以单价先扣一笔。
2. **任务 `SUCCEEDED` 时结算差额** —— 用 `usage.duration` 与预扣基数比对，少扣了补扣、多扣了退回，差额在账单上单独成行；任务 `FAILED` 则预扣全额退回，不收费。

因此「请求填 5 秒、账单不是 5 秒」是正常的：以实际交付为准。

### video-edit（视频编辑）这一族：计费秒数 = 输入 + 输出两段

其它族（t2v / i2v / r2v）从头生成，`usage.duration` 就是输出视频时长。video-edit 是**在一段已有视频上改**，上游把「读进去的输入视频」和「改完输出的视频」两段时长相加作为计费量，`usage` 里会拆给你看：

```json
{
  "usage": {
    "duration": 12.12,
    "input_video_duration": 6.06,
    "output_video_duration": 6.06,
    "video_count": 1,
    "SR": 720
  }
}
```

两个实际影响：

* **输出时长跟随输入视频，`duration` 在这族上不生效。** 实测同一段 6.06 秒的输入，请求填 `duration: 3` 和填 `duration: 5`，交付完全一致（都是输入 6.06s + 输出 6.06s，计费 12.12 秒）。该字段在这族上只起预扣基数作用。
* **成本按输入视频长度线性增长。** 6 秒输入约计 12 秒，30 秒输入就约计 60 秒。用 video-edit 前请按输入素材的实际时长估算预算，别按 `duration` 估。