AI API Gateway

Appearance

HappyHorse 参考视频生成操作指南 ​

本指南演示如何使用 AI API Gateway 的 HappyHorse 1.0 参考视频生成功能，通过参考图片和文字描述生成高质量视频。

📋 前置准备 ​

1. 获取 API 密钥 ​

联系管理员获取 Open.OspreyAI 的访问密钥（格式：sk-xxx）。

2. 了解 HappyHorse R2V ​

HappyHorse 1.0 R2V（Reference-to-Video）是参考视频生成模型，核心特性：

特性说明
参考图片支持 1-6 张参考图片
分辨率720P / 1080P 高清
画面比例16:9（横屏）、9:16（竖屏）、1:1（方形）
视频时长3-15 秒可调
引用方式通过 [Image N] 引用图片内容
生成时间1-3 分钟（视分辨率和时长而定）

3. 与图生视频（I2V）的区别 ​

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

🎬 生成视频 ​

方法一：AI 助手对话式生成（推荐） ​

这是最简单的方式，只需将 Skill 文件发送给 AI 助手，然后用自然语言描述需求。

步骤 1：学习 Skill ​

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

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

📷 待补充截图：AI 助手确认学习 HappyHorse 参考视频 Skill 的对话截图

步骤 2：用自然语言描述视频 ​

向 AI 助手发送视频生成需求：

请使用刚学习的 HappyHorse 参考视频技能，生成一段视频：
参考图片：https://example.com/clothes.webp
提示词："[Image 1]中的衣服缓缓旋转，背景光影流转"
分辨率 1080P，横屏 16:9，时长 5 秒

AI 助手会自动：

  1. 提交参考视频任务到 HappyHorse 模型
  2. 轮询任务状态，等待生成完成
  3. 下载最终视频文件并提供给你
📸 查看生成过程截图

📷 待补充截图：AI 助手调用 HappyHorse R2V API 生成视频后的返回界面

步骤 3：获取视频 ​

生成完成后（通常需要 1-3 分钟），AI 助手会提供视频文件的下载链接和播放。

方法二：API 直接调用 ​

适合开发者集成到自己的应用中。详细参数说明请参考 HappyHorse 参考视频 Skill。

快速示例 ​

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]中的衣服缓缓旋转，背景光影流转",
    "images": ["https://example.com/clothes.webp"],
    "resolution": "1080P",
    "ratio": "16:9",
    "duration": 5
  }'

# 返回: {"task_id": "task_xxx", "status": "queued"}

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

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

Python 示例 ​

python
import requests
import time

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

# 提交任务
resp = requests.post(f"{GW}/v1/video/generations",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
        "X-DashScope-Async": "enable"
    },
    json={
        "model": "happyhorse-1.0-r2v",
        "prompt": "[Image 1]中的衣服缓缓旋转，背景光影流转",
        "images": ["https://example.com/clothes.webp"],
        "resolution": "1080P",
        "ratio": "16:9",
        "duration": 5
    })

task = resp.json()
task_id = task["task_id"]
print(f"任务已提交: {task_id}")

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

    if status == "SUCCESS":
        video_url = data.get("result_url")
        print(f"视频已就绪: {video_url}")
        break
    elif status == "FAILED":
        print(f"生成失败: {data.get('fail_reason')}")
        break

    print(f"状态: {status} ({data.get('progress', '')})")
    time.sleep(5)

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

🎥 效果演示 ​

以下是使用本指南生成的「衣服旋转」视频：

🎬 HappyHorse 参考视频生成（1080P, 16:9, 5 秒）

参考图片 ​

参考图片

📷 参考图片：条纹毛衣

提示词 ​

[Image 1]中的衣服缓缓旋转，背景光影流转

视频参数 ​

参数值
模型happyhorse-1.0-r2v
分辨率1080P
画面比例16:9
时长5 秒
格式MP4

💡 提示词技巧 ​

R2V 的核心能力是通过 [Image N] 引用参考图片内容。

引用语法 ​

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

提示词结构 ​

推荐按以下结构组织提示词：

[Image N]中的主体 + 动作描述 + 场景/氛围 + 镜头运动（可选）

示例对比 ​

类型提示词效果
❌ 过于简单"一件衣服"画面单调，缺乏动态感
⚠️ 基本描述"[Image 1]中的衣服在旋转"有动作但缺乏细节
✅ 详细描述"[Image 1]中的衣服缓缓旋转，背景光影流转，镜头缓慢推进"画面丰富，动态自然

更多提示词示例 ​

单图 + 简单描述：

[Image 1]中的产品缓缓旋转，背景光影流转

双图 + 场景融合：

[Image 1]中的人物漫步在[Image 2]所示的海滩上，夕阳余晖洒满全身

三图 + 多元素叙事：

[Image 1]中的女性展开[Image 2]中的折扇，[Image 3]的耳坠轻轻摆动

复杂场景：

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

Prompt 编写建议 ​

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

📐 参数选择指南 ​

分辨率 ​

场景推荐分辨率原因
快速预览/测试720P生成更快（~1-2 分钟）
最终输出/展示1080P画质更高（~2-3 分钟）

画面比例 ​

比例适用场景示例
16:9PC/电视/YouTube电影感、风景
9:16手机/短视频/TikTok竖屏社交媒体
1:1Instagram/朋友圈方形展示

时长 ​

时长适用场景
3-5 秒简短动效、产品展示
5 秒默认值，平衡质量和时间
8-15 秒完整叙事、多元素融合

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

参考图片要求 ​

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

🔄 HappyHorse 模型家族 ​

除了参考视频（R2V），HappyHorse 还提供多种视频生成模型：

模型类型输入适用场景
happyhorse-1.0-t2v文生视频文字提示词创意视频、营销素材
happyhorse-1.0-i2v图生视频图片 + 文字图片动态化、产品动画
happyhorse-1.0-r2v参考视频参考图 + 文字多图融合、风格迁移
happyhorse-1.0-video-edit视频编辑视频 + 文字视频内容修改、增强

📚 其他模型的使用方式与 R2V 类似，参数细节请参考对应的 Skill 文档。

❓ 常见问题 ​

Q: 生成时间太长怎么办？ A: 1080P 视频生成通常需要 2-3 分钟，这是正常的。可以：

  • 降低分辨率为 720P 以加快生成速度
  • 减少视频时长
  • 减少参考图片数量
  • 避开高峰时段

Q: 参考图片应该如何选择？ A: 建议选择：

  • 清晰度高、主体明确的图片
  • 风格一致的图片（如果是多张）
  • 符合宽高比要求（1:2.5 ~ 2.5:1）

Q: 视频 URL 过期了怎么办？ A: 视频 URL 是阿里云 OSS 临时链接，有效期约 24 小时。过期后只需重新查询任务状态（GET /v1/video/generations/{task_id}），即可获取新的下载链接。

Q: 生成失败是什么原因？ A: 常见原因包括：

  • 提示词包含违规内容（检查 fail_reason 字段）
  • 参考图片不符合要求（格式、大小、分辨率）
  • 模型服务暂时过载（稍后重试）
  • API 密钥无效或配额不足

Q: 可以只用一张参考图吗？ A: 可以！R2V 支持 1-6 张参考图。单张图片适合产品展示、风格迁移等场景。

Q: 与 I2V（图生视频）有什么区别？ A: R2V 支持多张参考图融合，可以通过 [Image N] 引用不同图片的元素，适合多图融合、风格迁移场景。I2V 只支持单张首帧图片，输出视频宽高比由输入图片决定。

Q: 与 ComfyUI 关键帧视频有什么区别？

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

📚 延伸阅读 ​

🔗 相关资源 ​

AI API Gateway Documentation