下载原始 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 助手对话式接入。

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

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

Skill	模型	输入	输出	适用场景
ComfyUI 视频生成	Wan 2.2 I2V	1 张起始图	~5s 视频	图生视频（开源）
ComfyUI 关键帧视频	Wan 2.2 FLF2V	6 张关键帧	~5s 视频	多关键帧过渡
ComfyUI Fun Inpaint	Wan 2.2 Fun Inpaint	首帧 + 尾帧	~5s 视频	首尾帧过渡
HappyHorse 文生视频	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"]

支持两种格式：

公网 URL：HTTP 或 HTTPS 协议

json

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

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 文件并可正常播放
[ ] 视频分辨率、时长与请求参数一致

对话式接入 ​

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

Overview ​

Quick Start ​

Task Routing ​

Route A: Submit Task ​

服务信息 ​

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

请求参数 ​

images 字段说明 ​

图片要求 ​

请求头 ​

Route B: Check Status ​

查询任务状态 ​

任务状态流转 ​

Route C: Download ​

Python 调用示例 ​

Route D: Tune Parameters ​

分辨率 ​

时长 ​

水印 ​

种子 ​

提示词技巧 ​

输出视频参数 ​

Route E: Troubleshoot ​

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

与 T2V 的关键差异 ​

与 ComfyUI 图生视频的对比 ​

Verification Checklist ​

对话式接入

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

Overview

Quick Start

Task Routing

Route A: Submit Task

服务信息

Step 1: 提交图生视频任务

请求参数

images 字段说明

图片要求

请求头

Route B: Check Status

查询任务状态

任务状态流转

Route C: Download

Python 调用示例

Route D: Tune Parameters

分辨率

时长

水印

种子

提示词技巧

输出视频参数

Route E: Troubleshoot

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

与 T2V 的关键差异

与 ComfyUI 图生视频的对比

Verification Checklist