Bind [image_1] to the little handmade felt explorer and [image_2] to the explorer’s exact copper lantern. A three-second continuous side-tracking shot inside a dark miniature cave with softly glowing pale-green fungi. The explorer takes two slow steps while holding the lantern by its handle; its amber light brushes the felt face and stone wall. Preserve the teal coat, round tan felt face, ochre cap, and the lantern’s hexagonal copper cage and blue glass star. Tactile stop-motion craftsmanship, steady coherent anatomy and prop shape, soft felt footsteps and tiny metal-handle creak, no dialogue or music. No logos, brands, advertising, captions, subtitles or watermarks.
Happy Horse 1.1 Reference to Video API
alibaba/happyhorse-1.1/reference-to-videoHappy Horse 1.1 Reference to Video 将 1 至 9 张参考图与文本提示词融合成 3–15 秒 720p 或 1080p 电影级视频,支持多主体身份一致性、原生同步音频生成与 7 种语言口型对齐。它能够在跨镜头与多视角调度中稳固锚定角色容貌、服饰形制与商品外观,显著消除多镜头叙事中的角色形变漂移。
请添加 1–9 张参考图片。
生成的视频会显示在这里
填写提示词并添加所需素材,确认设置后点击“运行”。
示例
REST API
快速开始
使用 API 认证,提交参考图数组与指引提示词,通过任务 ID 获取生成的一致性视频。
连接到 Vidgo API
创建 API 密钥,仅保存在服务器上,并发送 Authorization: Bearer VIDGO_API_KEY。
- 端点
- POST
https://api.vidgo.ai/api/generate/submit - 认证
- Authorization: Bearer VIDGO_API_KEY
提交一次参考图生视频任务
设置 reference_image_urls 并在 prompt 中描述主体与动作,model 必须是 alibaba/happyhorse-1.1/reference-to-video。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "alibaba/happyhorse-1.1/reference-to-video",
"input": {
"prompt": "Use [image_1] for the older woman and [image_2] for the younger man, keeping their separate faces and clothing exactly recognizable. One continuous medium two-shot inside a quiet mountaintop observatory beside a telescope, both uncovered faces readable. During seconds 0-2 the older woman on the left asks exactly in English, \"Found it?\" During seconds 2-5 the younger man on the right answers exactly, \"There it is.\", and points toward the telescope eyepiece. Only the speaking person moves their lips. Subtle camera drift, accurate dialogue lip-sync, restrained gestures, quiet room tone and a faint telescope motor, no music. No logos, brands, advertising, captions, subtitles or watermarks.",
"duration": 5,
"resolution": "1080p",
"seed": 11201,
"aspect_ratio": "16:9",
"reference_image_urls": [
"https://cdn.vidgo.ai/apis/models/alibaba/happyhorse-1.1/reference-to-video/v1/01/input-01.png",
"https://cdn.vidgo.ai/apis/models/alibaba/happyhorse-1.1/reference-to-video/v1/01/input-02.png"
]
}
}
JSON
)
RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
CODE=$(printf '%s' "$RESPONSE" | jq -r '.code // empty')
if [ "$CODE" != "0" ] && [ "$CODE" != "200" ]; then
printf 'API error: %s
' "$RESPONSE" >&2
exit 1
fi
printf '%s
' "$RESPONSE"等待结果
用 task_id 查询,not_started/running 时继续,finished/failed 时停止。成功后读取 data.files[].file_url。
跟踪状态
GET https://api.vidgo.ai/api/generate/status/{task_id}以 2 秒为基准轮询状态,任务较长时加大间隔。仅在 not_started 或 running 时继续,finished 或 failed 时停止。也可以在请求中指定 callback_url 接收 webhook。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "2ZW2ZK57CMZC1EK2",
"status": "running",
"created_time": "2026-09-21T17:18:09"
}
}{
"code": 200,
"data": {
"task_id": "task-unified-...",
"status": "finished",
"files": [
{
"file_url": "https://storage.vidgo.ai/generated/video.mp4",
"file_type": "video"
}
],
"created_time": "2026-08-22T10:00:00Z",
"progress": 100,
"error_message": null
}
}完整可运行示例
展开查看包含 HTTP 与业务码检查、task_id 校验、轮询、终态处理和超时边界的完整代码。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "alibaba/happyhorse-1.1/reference-to-video",
"input": {
"prompt": "Use [image_1] for the older woman and [image_2] for the younger man, keeping their separate faces and clothing exactly recognizable. One continuous medium two-shot inside a quiet mountaintop observatory beside a telescope, both uncovered faces readable. During seconds 0-2 the older woman on the left asks exactly in English, \"Found it?\" During seconds 2-5 the younger man on the right answers exactly, \"There it is.\", and points toward the telescope eyepiece. Only the speaking person moves their lips. Subtle camera drift, accurate dialogue lip-sync, restrained gestures, quiet room tone and a faint telescope motor, no music. No logos, brands, advertising, captions, subtitles or watermarks.",
"duration": 5,
"resolution": "1080p",
"seed": 11201,
"aspect_ratio": "16:9",
"reference_image_urls": [
"https://cdn.vidgo.ai/apis/models/alibaba/happyhorse-1.1/reference-to-video/v1/01/input-01.png",
"https://cdn.vidgo.ai/apis/models/alibaba/happyhorse-1.1/reference-to-video/v1/01/input-02.png"
]
}
}
JSON
)
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
BUSINESS_CODE=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Submit failed:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
START_TIME=$(date +%s)
POLL_DELAY=2
while true; do
if [ $(( $(date +%s) - START_TIME )) -ge 600 ]; then
printf 'Timed out after 600 seconds
' >&2
exit 1
fi
STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
--url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
--header "Authorization: Bearer $VIDGO_API_KEY")
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
BUSINESS_CODE=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Status request failed:
%s
' "$STATUS_RESPONSE" >&2
exit 1
fi
case "$STATUS" in
finished)
printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
break
;;
failed)
printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
exit 1
;;
not_started|running)
sleep "$POLL_DELAY"
if [ "$POLL_DELAY" -lt 10 ]; then POLL_DELAY=$((POLL_DELAY + 1)); fi
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
done输入参数
下表列出可用输入参数、类型和默认值。请求示例还包含顶层 model 字段。
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| prompt | string | 是 | — | 去除首尾空白后最多 2500 个 Unicode 字符。必须填写非空提示词。 |
| reference_image_urls | string[] | 是 | — | 1–9 张参考图片,保留顺序,支持公开 HTTP(S) URL、图片 Data URI 或原始 Base64。 |
| resolution | string | 否 | 1080p | 720p 或 1080p,默认 1080p。 |
| duration | integer | 否 | 5 | 3–15 秒整数,默认 5 秒。 |
| aspect_ratio | string | 否 | 16:9 | 支持 21:9, 16:9, 4:3, 1:1, 3:4, 4:5, 5:4, 9:16, 9:21,默认 16:9。 |
| seed | integer | 否 | — | 可选整数,范围 0–2147483647。不指定时省略。 |
| enable_safety_checker | boolean | 否 | — | 可选布尔值;未指定时不发送。 |
响应字段
提交任务返回 task_id;状态查询接口返回生命周期进度和视频资源。
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 业务响应码,成功为 200。 |
| data.task_id | string | 用于轮询进度的唯一任务标识。 |
| data.status | string | 生命周期状态:not_started、running、finished 或 failed。 |
| data.progress | integer | 生成进度百分比 (0–100)。 |
| data.files[].file_url | string | 生成的视频资源公开下载链接。 |
| data.files[].file_type | string | 文件类型标识,例如 video。 |
| data.error_message | string | null | 任务失败时的具体错误说明。 |
任务生命周期
仅在 not_started 或 running 时继续轮询,进入 finished 或 failed 时停止。
not_started任务已在队列中排队,等待执行。
running任务正在生成中,请保持轮询。
finished任务已完成,可从 data.files[].file_url 读取视频地址。
failed任务生成失败,请读取 data.error_message 并停止轮询。
轮询与错误处理
- 认证遇到 401 时,检查 Authorization 中的 Bearer API key,更新凭证后重试。
- 校验遇到 400 时,根据响应检查必填输入、参数值和可用积分,再重新提交。
- 网络和超时状态查询遇到网络错误或超时,保留原 task_id 并重试查询。
- 轮询间隔以 2 秒为基准轮询状态,任务较长时逐步加大间隔。
- 终态仅在 not_started 或 running 时继续。finished 或 failed 立即停止。
- 回调选项可在请求顶层提供 callback_url 接收最终任务对象;投递失败时仍可轮询。
端点限制
| 规格 | 值 | 详情 |
|---|---|---|
| prompt | 2500 | 去除首尾空白后最多 2500 个 Unicode 字符。必须填写非空提示词。 |
| reference_image_urls | 1–9 | 1–9 张参考图片,保留顺序,支持公开 HTTP(S) URL、图片 Data URI 或原始 Base64。 |
| resolution | 1080p | 720p 或 1080p,默认 1080p。 |
| duration | 5 | 3–15 秒整数,默认 5 秒。 |
| aspect_ratio | 16:9 | 支持 21:9, 16:9, 4:3, 1:1, 3:4, 4:5, 5:4, 9:16, 9:21,默认 16:9。 |
Happy Horse 1.1 Reference to Video
Happy Horse 1.1 Reference to Video 专门解决长序列短剧与多镜头创作中的主体一致性难题。你只需提交 1 至 9 张参考图片(涵盖同一角色的不同视角、多种服饰、多个互动角色或关键道具,支持公开 URL、Data URI 或 Base64 编码),并搭配最多 2,500 字符的动作与对白提示词。模型能够根据参考素材精准锁定形象特征,同时提供 9 种画幅选择,一体化生成包含对白与拟音的成片。
核心能力与优势
支持 1–9 张多图联合参考单次任务可同时传入多达 9 张参考图片,全面覆盖角色多角度肖像、特写表情、服饰纹理或关键道具。
稳固的多主体身份保持在双人对话或群戏互动场景中稳定区分多位角色,避免面部特征交叉混淆或走样形变。
灵活的角色显式语义绑定支持在提示词中自然描述或使用 [image_1]、[image_2] 标签精准指代特定素材,实现精确的剧本导演级调度。
原生声画一体与唇形对齐视频画面与台词声效单次推理同步完成,说话角色的嘴形与 7 种指定语言音素严丝合缝。
多角度三维体量感构建通过正面、侧面、斜侧面等多张参考图,帮助模型建立完整空间结构,支撑复杂的 360 度环绕运镜。
独立自由选择 9 种成片画幅成片比例不受参考图片原始尺寸束缚,原生支持 16:9 横屏、9:16 竖屏及 21:9 宽银幕等 9 种规格。
参数
| 参数 | 要求 | 说明 |
|---|---|---|
| prompt | 必填 | 去除首尾空白后最多 2500 个 Unicode 字符。必须填写非空提示词。 |
| reference_image_urls | 必填 | 1–9 张参考图片,保留顺序,支持公开 HTTP(S) URL、图片 Data URI 或原始 Base64。 |
| resolution | 可选 | 720p 或 1080p,默认 1080p。 |
| duration | 可选 | 3–15 秒整数,默认 5 秒。 |
| aspect_ratio | 可选 | 支持 21:9, 16:9, 4:3, 1:1, 3:4, 4:5, 5:4, 9:16, 9:21,默认 16:9。 |
| seed | 可选 | 可选整数,范围 0–2147483647。不指定时省略。 |
| enable_safety_checker | 可选 | 可选布尔值;未指定时不发送。 |
如何调用 Happy Horse 1.1 Reference to Video API
准备 1–9 张参考图片收集目标主体多角度肖像、关键服饰或交互道具的清晰照片。
填入参考图数组将图片地址依序填入 reference_image_urls 数组参数中。
编写剧本调度提示词在 prompt 中细致描述剧情事件、动作顺序、角色对白台词以及运镜轨迹。
选定画幅与时长档位按需指定 3–15 秒生成时长、720p 或 1080p 分辨率,以及期望的画面比例。
提交任务发起计算调用统一 API 生成接口提交任务,获取用于跟踪的 task_id。
下载一致性成片视频轮询任务至 finished 状态,提取并下载包含同步音频的高保真 MP4 成品。
价格
费用 = 输出时长 × 分辨率每秒费率。1 积分 = $0.005;三种模式同价。生成失败全额返还点数。
| 用途 | 费率 | 详情 |
|---|---|---|
| 720p | 22 积分/秒 ($0.11/秒) | 5 秒:110 积分 ($0.55) |
| 1080p | 28 积分/秒 ($0.14/秒) | 5 秒:140 积分 ($0.70) |
适用场景
连续短剧与分镜叙事创作在剧集多集连续镜头中严格维持核心主角的面孔、发型与服装不变,彻底告别每镜换脸。
双人或多角色对话互动分别为两位主演提供面部参考图,通过台词提示词编排有来有往的双人对手戏与同步口型。
品牌 IP 与虚拟代言人营销将企业固定吉祥物形象或虚拟代言人置入不同节庆氛围与发布会场景中制作系列宣传片。
服饰试穿与商品动态展示结合特定模特面部图与服装款式参考图,生成身着目标服饰在真实环境走秀展示的动态视频。
使用技巧
- 指导两名角色演戏时,可为两人分别提供肖像参考,并在提示词中使用显式标注(如:蓝衣女子 [image_1] 看着黑衣男子 [image_2],用普通话说:“我们终于到了”),可确保角色对白与口型精准对应。
- 为同一角色提供正面、正侧面及四分之三侧面等多张参考照片,能够帮助模型完整理解三维轮廓,在镜头大幅度旋转或走位时始终保持五官立体稳定。
- 确保参考图片采光充分、对焦锐利,避免严重眩光、严重涂抹或畸变透视,以保留最优质的纹理细节。
- 与根据首帧自适应画幅的 Image to Video 不同,Reference to Video 必须明确配置 aspect_ratio,请根据目标投放平台直接指定 16:9 或 9:16。
使用说明
- reference_image_urls 数组必须包含 1 至 9 个有效图片链接,传入空数组将在校验时被拒绝且不扣费。
- 必须填写非空 prompt 提示词(最多 2,500 字符),用于明确参考素材在镜头中的具体动作与行为。
- 成片画幅由 aspect_ratio 参数独立决定(默认为 16:9),不受参考素材自身尺寸限制。
- 输出包含原生对白、拟音与环境配乐的一体化 MP4 文件,无需二次后期配音混音。
相关模型
Happy Horse 1.1 Reference to Video API 常见问题
Happy Horse 1.1 Reference to Video API 是什么?
Happy Horse 1.1 Reference to Video 是阿里巴巴研发的多参考图视频生成模型。它将 1 至 9 张参考图与指导提示词结合,生成 3–15 秒 720p 或 1080p 电影级高保真视频,具备多主体身份一致性、原生同步音频生成与 7 种语言口型对齐能力。基于统一的单流自注意力 Transformer 架构,它在跨镜头多视角调度中稳固锚定角色容貌、服装形制与道具结构,大幅减轻多镜头叙事中的角色走样。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Happy Horse 1.1 Reference to Video 最多支持上传多少张参考图片?
你可以在 reference_image_urls 数组中传入 1 至 9 张参考图片。你可以利用多张图片提供同一角色的正面、侧面特写,也可以分别传入不同互动角色的参考素材。
如何在 Happy Horse 1.1 Reference to Video 提示词中指定参考图对应的角色?
你可以通过外貌特征自然描述,也可以使用形如 [image_1]、[image_2] 的位置标签(对应数组传入顺序)显式绑定(例如:[image_1] 将文件递给 [image_2]),引导模型准确安排角色走位与互动。
Happy Horse 1.1 Reference to Video 支持同时保持多个角色的外观一致吗?
支持。只要分别传入不同角色的清晰肖像图,并在提示词中清晰界定各自的行动与对白,模型即可保持多位角色的容貌独立,避免换脸或特征杂糅。
Happy Horse 1.1 Reference to Video 必须填写提示词吗?
必须填写。与支持自主推演的 Image to Video 不同,Reference to Video 必须在 prompt 中提供非空描述(最多 2,500 字符),以指导模型理解参考主体在场景中的剧情任务与互动逻辑。
Happy Horse 1.1 Reference to Video 支持哪些画面宽高比?
支持 9 种画幅比例:21:9、16:9、4:3、1:1、3:4、4:5、5:4、9:16 与 9:21。成片比例不受参考素材自身尺寸限制,可由参数 aspect_ratio 自由设定。
Happy Horse 1.1 Reference to Video 支持多参考图下的多语言对白口型同步吗?
支持。在提示词中包含双引号对白并指明语种后,模型在生成视频帧的同时会自动合成逼真对白,并使说话角色的嘴形肌肉精准匹配发音,支持包括普通话、英语等 7 种语言。
Happy Horse 1.1 Reference to Video 如何计费?
计费规则与基础分辨率时长挂钩:720p 为每秒 22 点数,1080p 为每秒 28 点数。传入参考图数量(1–9 张)不产生额外附加费,任务失败将全额返还点数。















