---
name: happyhorse-image-to-video
description: 通过 Open.OspreyAI 网关使用 HappyHorse 1.0 图生视频 API。以首帧图片为基础，配合文字引导，生成 720P/1080P 高清视频，3-15 秒可调。
version: "1.0"
category: video-generation
triggers:
  - HappyHorse 图生视频
  - happyhorse i2v
  - 图片生成视频
  - 图生视频
  - happyhorse-1.0-i2v
  - image to video
  - 首帧视频
---

::: info 下载原始 Skill 文件
```bash
curl https://ai.ospreyai.cn/docs/raw/skills/happyhorse-image-to-video.md -o happyhorse-image-to-video.md
```
:::

## 对话式接入

本 Skill 文件可被 AI 助手（Claude Code、Cursor、ChatGPT 等）学习，通过自然语言对话完成图生视频。

在 AI 对话中发送以下指令即可：

```
学习：https://ai.ospreyai.cn/docs/raw/skills/happyhorse-image-to-video.md，保存为本地的技能 skills
```

> 更多接入方式和使用示例详见 [API 文档 — AI 助手对话式接入](/api#ai-助手对话式接入)。

---

# HappyHorse 1.0 图生视频 (Image-to-Video)

## Overview

通过 Open.OspreyAI 网关 `https://open.ospreyai.cn` 使用 HappyHorse 1.0 模型，以首帧图片为基础，配合文字描述引导，生成物理真实、运动流畅的高清视频。

**HappyHorse I2V** 是图生视频模型，输入一张首帧图片和文字提示词，引导运动方向和内容，输出 720P/1080P 高清视频，最长 15 秒。采用异步任务模式：提交任务 → 轮询状态 → 下载视频。

核心特性：
- **首帧驱动**：以输入图片为视频第一帧，生成连贯运动
- **文字引导**：prompt 描述期望的运动和内容（必填）
- **高清输出**：支持 720P、1080P 分辨率
- **保持比例**：输出视频宽高比与输入图片一致
- **灵活时长**：3-15 秒可调（比 T2V 的 1-10 秒更长）
- **异步任务**：提交后立即返回 task_id，后台生成完成后通过 OSS 临时链接下载

**API 参考文档**：[阿里云 — HappyHorse 图生视频 API](https://help.aliyun.com/zh/model-studio/happyhorse-image-to-video-api-reference)

与其他视频生成 Skill 的对比：

| Skill | 模型 | 输入 | 输出 | 适用场景 |
|-------|------|------|------|---------|
| [ComfyUI 视频生成](/skills/comfyui-video-generation) | Wan 2.2 I2V | 1 张起始图 | ~5s 视频 | 图生视频（开源） |
| [ComfyUI 关键帧视频](/skills/comfyui-keyframes-video-generation) | Wan 2.2 FLF2V | 6 张关键帧 | ~5s 视频 | 多关键帧过渡 |
| [ComfyUI Fun Inpaint](/skills/comfyui-fun-inpaint-video-generation) | Wan 2.2 Fun Inpaint | 首帧 + 尾帧 | ~5s 视频 | 首尾帧过渡 |
| [HappyHorse 文生视频](/skills/happyhorse-text-to-video) | HappyHorse 1.0 T2V | 文字提示词 | 1-10s 视频 | 纯文字驱动 |
| **本 Skill** | HappyHorse 1.0 I2V | 首帧图片 + 文字 | 3-15s 视频 | 图片动态化、产品展示 |

所有 API 均需 Bearer Token 鉴权（`Authorization: Bearer sk-xxx`）。

## Quick Start

```bash
export GW="https://open.ospreyai.cn"
export API_KEY="sk-your-api-key"

# 1. 提交图生视频任务
curl -s -X POST "$GW/v1/video/generations" \
  -H "X-DashScope-Async: enable" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-i2v",
    "prompt": "一只猫在草地上奔跑",
    "images": ["https://your-image-url.com/photo.png"],
    "resolution": "1080P",
    "duration": 5,
    "watermark": false
  }'

# 响应: {"task_id": "task_xxx", "status": "queued"}

# 2. 轮询任务状态
curl -s "$GW/v1/video/generations/{task_id}" \
  -H "Authorization: Bearer $API_KEY"

# 3. 下载视频（从响应中的 result_url 字段获取）
curl -sL "{result_url}" -o output.mp4
```

## Task Routing

| 场景 | 动作 |
|------|------|
| 首次生成视频 | → Route A: Submit Task |
| 需要查看任务是否完成 | → Route B: Check Status |
| 需要获取或下载视频 | → Route C: Download |
| 需要调优参数（分辨率、时长） | → Route D: Tune Parameters |
| 需要排查错误 | → Route E: Troubleshoot |

## Route A: Submit Task

### 服务信息

- 网关地址: `https://open.ospreyai.cn`
- 提交接口: `POST /v1/video/generations`
- 查询接口: `GET /v1/video/generations/{task_id}`
- 鉴权方式: `Authorization: Bearer sk-xxx`
- 异步头: `X-DashScope-Async: enable`

### Step 1: 提交图生视频任务

```bash
curl -s -X POST "$GW/v1/video/generations" \
  -H "X-DashScope-Async: enable" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-i2v",
    "prompt": "A girl smiling and turning to look at the camera",
    "images": ["https://your-image-url.com/photo.png"],
    "resolution": "720P",
    "duration": 5,
    "watermark": false
  }'
```

**响应：**

```json
{
    "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxx",
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxx",
    "object": "video",
    "model": "happyhorse-1.0-i2v",
    "status": "queued",
    "progress": 0,
    "created_at": 1780000000
}
```

> 记住 `task_id`，用于后续查询任务状态和获取视频。

### 请求参数

| 字段 | 类型 | 必填 | 说明 | 示例值 |
|------|------|------|------|--------|
| model | string | ✅ | 模型名称 | `"happyhorse-1.0-i2v"` |
| prompt | string | ✅ | 视频描述（引导运动方向和内容，中英文均可） | `"一只猫在草地上奔跑"` |
| images | array | ✅ | 图片 URL 数组，有且仅有 1 个元素 | `["https://..."]` |
| resolution | string | ❌ | 分辨率：`720P` / `1080P`（默认） | `"1080P"` |
| duration | integer | ❌ | 视频时长（秒），3-15，默认 5 | `5` |
| watermark | boolean | ❌ | 是否添加水印，默认 `true` | `false` |
| seed | integer | ❌ | 随机种子 `[0, 2147483647]`，固定可提高复现性 | `42` |

### images 字段说明

`images` 是一个字符串数组，包含 1 个图片 URL：

```json
"images": ["https://example.com/photo.png"]
```

支持两种格式：

1. **公网 URL**：HTTP 或 HTTPS 协议
   ```json
   "images": ["https://example.com/photo.png"]
   ```

2. **Base64 编码**：
   ```json
   "images": ["data:image/png;base64,iVBORw0KGgo..."]
   ```

### 图片要求

| 限制项 | 要求 |
|--------|------|
| 格式 | JPEG、JPG、PNG、WEBP |
| 分辨率 | 宽和高均不小于 300 像素 |
| 宽高比 | 1:2.5 ~ 2.5:1 |
| 文件大小 | 不超过 20MB |
| 数量 | 有且仅有 1 张 |

### 请求头

| Header | 说明 |
|--------|------|
| `X-DashScope-Async: enable` | 启用异步任务模式（必传） |
| `Authorization: Bearer sk-xxx` | API 鉴权 |
| `Content-Type: application/json` | JSON 请求体 |

## Route B: Check Status

### 查询任务状态

```bash
curl -s "$GW/v1/video/generations/{task_id}" \
  -H "Authorization: Bearer $API_KEY"
```

**进行中：**

```json
{
    "code": "success",
    "data": {
        "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxx",
        "status": "IN_PROGRESS",
        "progress": "50%",
        "submit_time": 1780000000,
        "start_time": 1780000001,
        "finish_time": 0,
        "data": {
            "output": {
                "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "task_status": "RUNNING"
            }
        }
    }
}
```

**已完成：**

```json
{
    "code": "success",
    "data": {
        "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxx",
        "status": "SUCCESS",
        "progress": "100%",
        "result_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/...",
        "submit_time": 1780000000,
        "start_time": 1780000001,
        "finish_time": 1780000120,
        "data": {
            "usage": {
                "SR": 1080,
                "duration": 5,
                "video_count": 1,
                "input_video_duration": 0,
                "output_video_duration": 5
            },
            "output": {
                "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/...",
                "orig_prompt": "A cat running on the grass...",
                "task_status": "SUCCEEDED"
            }
        }
    }
}
```

### 任务状态流转

```
queued → IN_PROGRESS (50%) → SUCCESS (100%) / FAILED
```

| 状态 | 说明 |
|------|------|
| `queued` | 任务已提交，排队等待 |
| `IN_PROGRESS` | 正在生成中 |
| `SUCCESS` | 生成成功，可下载视频 |
| `FAILED` | 生成失败，查看 `fail_reason` |

> 1080P 5秒视频生成通常需要 1-3 分钟。

## Route C: Download

任务成功后，从响应中获取视频下载链接：

- **`data.result_url`**：顶层字段，直接的下载 URL
- **`data.data.output.video_url`**：嵌套字段，同上

两个 URL 相同，均为阿里云 OSS 临时链接（有效期约 24 小时）。

```bash
# 直接下载（URL 从任务状态响应中获取）
curl -sL "{result_url}" -o output.mp4
```

> ⚠️ 视频 URL 带签名参数，有效期约 24 小时（`Expires` 参数控制），过期后需重新查询任务获取新链接。

### Python 调用示例

```python
import requests
import time

GW = "https://open.ospreyai.cn"
API_KEY = "sk-your-api-key"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "X-DashScope-Async": "enable"
}

# 1. 提交图生视频任务
resp = requests.post(f"{GW}/v1/video/generations", headers=headers, json={
    "model": "happyhorse-1.0-i2v",
    "prompt": "A girl smiling and turning to look at the camera",
    "images": ["https://your-image-url.com/photo.png"],
    "resolution": "720P",
    "duration": 5,
    "watermark": false
})
task = resp.json()
task_id = task["task_id"]
print(f"Task submitted: {task_id}")

# 2. 轮询任务状态
headers_query = {"Authorization": f"Bearer {API_KEY}"}
while True:
    resp = requests.get(f"{GW}/v1/video/generations/{task_id}", headers=headers_query)
    data = resp.json().get("data", {})
    status = data.get("status", "")
    progress = data.get("progress", "")

    if status == "SUCCESS":
        video_url = data.get("result_url") or data.get("data", {}).get("output", {}).get("video_url")
        print(f"Video ready: {video_url}")
        break
    elif status == "FAILED":
        print(f"Failed: {data.get('fail_reason')}")
        break

    print(f"Status: {status} ({progress})")
    time.sleep(5)

# 3. 下载视频
if status == "SUCCESS":
    resp = requests.get(video_url)
    with open("happyhorse_i2v_output.mp4", "wb") as f:
        f.write(resp.content)
    print(f"Downloaded: happyhorse_i2v_output.mp4 ({len(resp.content)} bytes)")
```

## Route D: Tune Parameters

### 分辨率

| 值 | 说明 | 生成时间 |
|----|------|---------|
| `720P` | 720p 标清 | 较快（~1-2 分钟） |
| `1080P` | 1080p 高清（默认） | 较慢（~2-3 分钟） |

> 模型根据选择的分辨率档位，自动缩放至相近总像素。**输出视频宽高比与输入首帧近似一致**（无 `ratio` 参数）。

### 时长

| 值 | 说明 |
|----|------|
| `3` - `15` | 视频时长（秒），整数 |
| `5` | 默认值，平衡质量和生成时间 |

> ⚠️ I2V 的时长范围为 **3-15 秒**（T2V 为 1-10 秒），支持更长的视频生成。

### 水印

| 值 | 说明 |
|----|------|
| `false` | 不添加水印（推荐，示例中默认使用） |
| `true` | 添加水印，右下角显示 "Happy Horse"（API 默认值） |

### 种子

| 值 | 说明 |
|----|------|
| `0` - `2147483647` | 固定 seed 可提高结果复现性 |
| 不传 | 系统自动生成随机种子 |

> 由于模型生成具有概率性，即使使用相同 seed 也不能保证每次结果完全一致。

### 提示词技巧

I2V 的 prompt 用于**引导运动方向和内容**：

- **简短 prompt**：引导运动方向
  ```
  "镜头缓慢推进"
  "slow camera zoom in"
  ```
- **详细 prompt**：描述期望的运动和内容
  ```
  "一只猫突然站起来，向镜头跑来，阳光明媚"
  "A girl smiling and turning to look at the camera"
  ```
- **建议**：描述动作 + 运动方向 + 光影氛围

### 输出视频参数

- **分辨率**: 720P 或 1080P（按请求参数）
- **比例**: 与输入首帧图片一致（无 `ratio` 参数）
- **时长**: 3-15 秒
- **格式**: MP4
- **文件大小**: 约 5-20 MB（5 秒视频）

## Route E: Troubleshoot

| 问题 | 排查方法 |
|------|---------|
| `Invalid URL` | 检查 URL 是否为 `/v1/video/generations`（不是 `/v1/services/aigc/...`） |
| `prompt is required` | `prompt` 是必填字段，必须在顶层，不能省略 |
| `i2v requires exactly 1 first_frame media item` | 使用了错误的图片字段名。必须用 `images`（字符串数组），不是 `media` |
| `happyhorse supports video task relay only` | 不能走 `/v1/chat/completions` 或 `/v1/images/generations`，必须走 `/v1/video/generations` |
| 401 鉴权失败 | 检查 Bearer Token 是否有效 |
| 任务长时间 IN_PROGRESS | 1080P 视频生成可能需要 2-3 分钟，耐心等待 |
| 任务 FAILED | 检查 `fail_reason` 字段，可能是图片不合规或模型过载 |
| 视频 URL 过期 | 重新查询任务状态获取新的 `result_url` |
| 图片不符合要求 | 检查格式（JPEG/PNG/WEBP）、分辨率（≥300px）、宽高比（1:2.5~2.5:1）、大小（≤20MB） |
| duration 不生效 | I2V 取值范围是 [3, 15]，不是 T2V 的 [1, 10] |

### 请求格式对比（常见错误）

| 项目 | ❌ 错误（DashScope 原始格式） | ✅ 正确（网关适配格式） |
|------|------|------|
| URL | `/v1/services/aigc/video-generation/video-synthesis` | `/v1/video/generations` |
| prompt | `{"input": {"prompt": "..."}}` | `{"prompt": "..."}` |
| 图片 | `{"input": {"media": [{"type": "first_frame", "url": "..."}]}}` | `{"images": ["..."]}` |
| 参数 | `{"parameters": {"resolution": "720P"}}` | `{"resolution": "720P"}` |

> ⚠️ **关键差异**：网关将 DashScope 的 `input.media` 数组格式简化为 `images` 字符串数组。不再需要 `type: "first_frame"` 包装，直接传图片 URL 即可。

### 与 T2V 的关键差异

| 特性 | I2V（本 Skill） | T2V（文生视频） |
|------|----------------|----------------|
| 模型 | `happyhorse-1.0-i2v` | `happyhorse-1.0-t2v` |
| 输入 | 首帧图片 + 文字 | 纯文字 |
| 图片字段 | `images`（必填） | 不需要 |
| ratio | 无（由图片决定） | `16:9` / `9:16` / `1:1` |
| duration | 3-15 秒 | 1-10 秒 |
| 分辨率默认 | `1080P` | 无默认 |

### 与 ComfyUI 图生视频的对比

| 特性 | HappyHorse I2V | ComfyUI I2V |
|------|---------------|-------------|
| 输入 | 1 张首帧图片 | 1 张起始图片 |
| 分辨率 | 720P / 1080P | 640×640 / 720×720 |
| 时长 | 3-15 秒 | ~5 秒（固定） |
| 生成时间 | 1-3 分钟 | 30 秒-2 分钟 |
| 输出格式 | MP4（OSS 临时链接） | MP4（ComfyUI 文件） |
| 模型 | 闭源大模型 | 开源 Wan 2.2 |
| 适合场景 | 产品展示、图片动态化 | 精确控制、图驱动动画 |
| 宽高比 | 自动跟随输入图片 | 固定比例 |

## Verification Checklist

- [ ] 请求 URL 为 `POST /v1/video/generations`（不是 DashScope 原始路径）
- [ ] 请求头包含 `X-DashScope-Async: enable`
- [ ] `prompt` 在顶层（必填，不嵌套在 `input` 中）
- [ ] `images` 在顶层，为包含 1 个 URL 字符串的数组（不是 `media` 对象数组）
- [ ] 图片 URL 可公网访问，格式符合要求
- [ ] 提交成功，返回 `task_id` 和 `status: "queued"`
- [ ] 轮询 `GET /v1/video/generations/{task_id}` 直到 `status: "SUCCESS"`
- [ ] 从 `result_url` 获取视频下载链接
- [ ] 下载 MP4 文件并可正常播放
- [ ] 视频分辨率、时长与请求参数一致