下载原始 Skill 文件

bash

curl https://ai.ospreyai.cn/docs/raw/skills/happyhorse-reference-to-video.md -o happyhorse-reference-to-video.md

对话式接入

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

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

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

更多接入方式和使用示例详见 API 文档 — AI 助手对话式接入。

HappyHorse 1.0 参考图片视频生成 (Reference-to-Video)

Overview

通过 Open.OspreyAI 网关 https://open.ospreyai.cn 使用 HappyHorse 1.0 模型，以 1-6 张参考图片为素材，配合文字描述，生成融合多图片元素的高清视频。

HappyHorse R2V 是参考图片视频生成模型，可输入多张参考图片（最多 6 张），在 prompt 中通过 [Image 1]、[Image 2] 等引用对应图片元素，生成将多张图片内容融合在一起的连贯视频。采用异步任务模式：提交任务 → 轮询状态 → 下载视频。

核心特性：

多图融合：支持 1-6 张参考图片，将不同图片元素融合到同一视频
Prompt 引用：通过 [Image N] 语法精确引用对应图片内容
高清输出：支持 720P、1080P 分辨率
多种比例：16:9（横屏）、9:16（竖屏）、1:1（方形）
灵活时长：3-15 秒可调
异步任务：提交后立即返回 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 视频	纯文字驱动
HappyHorse 图生视频	HappyHorse 1.0 I2V	1 张首帧 + 文字	3-15s 视频	图片动态化
本 Skill	HappyHorse 1.0 R2V	1-6 张参考图 + 文字	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-r2v",
    "prompt": "[Image 1]中的女性微笑着向镜头挥手，背景是[Image 2]中的城市风景",
    "images": [
      "https://example.com/girl.jpg",
      "https://example.com/city.jpg"
    ],
    "resolution": "720P",
    "ratio": "16:9",
    "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-r2v",
    "prompt": "[Image 1]中身着红色旗袍的女性，轻抬玉手展开[Image 2]中的折扇，[Image 3]中的流苏耳坠随头部转动轻盈摆动",
    "images": [
      "https://example.com/girl.jpg",
      "https://example.com/fan.jpg",
      "https://example.com/earrings.jpg"
    ],
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 5,
    "watermark": false
  }'

响应：

json

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

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

请求参数

字段	类型	必填	说明	示例值
model	string	✅	模型名称	`"happyhorse-1.0-r2v"`
prompt	string	✅	视频描述，用 `[Image N]` 引用图片	`"[Image 1]中的女性..."`
images	array	✅	图片 URL 数组，1-6 张	`["url1", "url2"]`
resolution	string	❌	分辨率：`720P` / `1080P`	`"720P"`
ratio	string	❌	画面比例：`16:9` / `9:16` / `1:1`	`"16:9"`
duration	integer	❌	视频时长（秒），3-15，默认 5	`5`
watermark	boolean	❌	是否添加水印，默认 `true`	`false`
seed	integer	❌	随机种子 `[0, 2147483647]`	`42`

images 字段说明

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

json

"images": [
  "https://example.com/photo1.jpg",
  "https://example.com/photo2.jpg",
  "https://example.com/photo3.jpg"
]

图片顺序对应 prompt 中的引用：第 1 张图片对应 [Image 1]，第 2 张对应 [Image 2]，以此类推。

支持两种格式：

公网 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-6 张

请求头

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": 720,
                "ratio": "16:9",
                "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": "[Image 1]中身着红色旗袍的女性...",
                "task_status": "SUCCEEDED"
            }
        }
    }
}

任务状态流转

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

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

720P 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-r2v",
    "prompt": "[Image 1]中身着红色旗袍的女性，轻抬玉手展开[Image 2]中的折扇",
    "images": [
        "https://example.com/girl.jpg",
        "https://example.com/fan.jpg"
    ],
    "resolution": "720P",
    "ratio": "16:9",
    "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_r2v_output.mp4", "wb") as f:
        f.write(resp.content)
    print(f"Downloaded: happyhorse_r2v_output.mp4 ({len(resp.content)} bytes)")

Route D: Tune Parameters

分辨率

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

画面比例

值	适用场景
`16:9`	横屏视频（适合 PC/电视）
`9:16`	竖屏视频（适合手机/短视频）
`1:1`	方形视频（适合社交媒体）

与 I2V 不同，R2V 支持 ratio 参数来控制输出视频的画面比例。

时长

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

时长越长，生成时间越久，消耗配额越多。

水印

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

种子

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

Prompt 引用语法

R2V 的核心能力是在 prompt 中通过 [Image N] 引用参考图片：

[Image 1] — 引用 images 数组中第 1 张图片
[Image 2] — 引用第 2 张图片
以此类推，最多 [Image 6]

Prompt 编写技巧：

[Image 1]中身着红色旗袍的女性，镜头先以侧面中景勾勒旗袍修身剪裁，
随即切换至低角度仰拍，捕捉她轻抬玉手展开[Image 2]中的折扇的同时，
[Image 3]中的流苏耳坠随头部转动轻盈摆动

建议：

每个 [Image N] 后描述该图片元素的动作或状态变化
描述镜头运动（推、拉、摇、移）来控制视频节奏
可以只引用部分图片，未引用的图片作为风格参考

多图融合示例

单图 + 简单描述：

json

{
  "images": ["https://example.com/product.jpg"],
  "prompt": "[Image 1]中的产品缓缓旋转，背景光影流转"
}

双图 + 场景融合：

json

{
  "images": [
    "https://example.com/person.jpg",
    "https://example.com/beach.jpg"
  ],
  "prompt": "[Image 1]中的人物漫步在[Image 2]所示的海滩上，夕阳余晖洒满全身"
}

三图 + 多元素叙事：

json

{
  "images": [
    "https://example.com/girl.jpg",
    "https://example.com/fan.jpg",
    "https://example.com/earrings.jpg"
  ],
  "prompt": "[Image 1]中的女性展开[Image 2]中的折扇，[Image 3]的耳坠轻轻摆动"
}

输出视频参数

分辨率: 720P 或 1080P（按请求参数）
比例: 16:9 / 9:16 / 1:1
时长: 3-15 秒
格式: MP4
文件大小: 约 5-20 MB（5 秒视频）

Route E: Troubleshoot

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

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

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

⚠️ 关键差异：网关将 DashScope 的 input.media 数组格式简化为 images 字符串数组。不再需要 type: "reference_image" 包装，直接传图片 URL 即可。图片顺序对应 prompt 中 [Image 1]、[Image 2] 的引用。

与 HappyHorse I2V 的关键差异

特性	R2V（本 Skill）	I2V（图生视频）
模型	`happyhorse-1.0-r2v`	`happyhorse-1.0-i2v`
输入	1-6 张参考图片 + 文字	1 张首帧图片 + 文字
图片数量	1-6 张	1 张
Prompt 引用	`[Image N]` 语法引用图片	直接描述动作
ratio	✅ 支持 `16:9`/`9:16`/`1:1`	无（由图片决定）
适合场景	多图融合、风格迁移、产品展示	单图动态化

与 ComfyUI 关键帧视频的对比

特性	HappyHorse R2V	ComfyUI FLF2V
输入	1-6 张参考图（非关键帧）	6 张关键帧
分辨率	720P / 1080P	640×640 / 720×720
时长	3-15 秒	~5 秒（固定）
生成时间	1-5 分钟	30 秒-2 分钟
模型	闭源大模型	开源 Wan 2.2
图片角色	参考素材，通过 prompt 编排	关键帧，固定过渡节点
适合场景	创意融合、营销素材	精确控制帧间过渡

Verification Checklist

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

对话式接入 ​

HappyHorse 1.0 参考图片视频生成 (Reference-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 ​

分辨率 ​

画面比例 ​

时长 ​

水印 ​

种子 ​

Prompt 引用语法 ​

多图融合示例 ​

输出视频参数 ​

Route E: Troubleshoot ​

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

与 HappyHorse I2V 的关键差异 ​

与 ComfyUI 关键帧视频的对比 ​

Verification Checklist ​

对话式接入

HappyHorse 1.0 参考图片视频生成 (Reference-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

分辨率

画面比例

时长

水印

种子

Prompt 引用语法

多图融合示例

输出视频参数

Route E: Troubleshoot

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

与 HappyHorse I2V 的关键差异

与 ComfyUI 关键帧视频的对比

Verification Checklist