character1 stands at the workshop stage from character3 and brings the knight marionette character2 to life, making it bow and raise its wooden sword while warm lamp light flickers, cinematic slow push in, no text, no logos, no watermark, no promotional marks
Happy Horse 1.0 Reference to Video API
alibaba/happyhorse-1.0/reference-to-videoHappy Horse 1.0 Reference to Video 将 1–9 张参考图像与文本提示词转化为电影感短视频,支持 3–15 秒时长控制、720p 与 1080p 输出,以及提示词引导的角色描述。它能够跨运镜保持多角色面容特征、服饰质感与艺术风格的高度一致,同时在自由定义的全新机位与剧本空间中演绎生动动作。
拖拽文件、粘贴剪贴板素材,或输入 URL。
生成的视频会显示在这里
填写提示词并添加所需素材,确认设置后点击“运行”。
示例
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 描述主体与动作;角色标记可选。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "alibaba/happyhorse-1.0/reference-to-video",
"input": {
"prompt": "character1 stands at the workshop stage from character3 and brings the knight marionette character2 to life, making it bow and raise its wooden sword while warm lamp light flickers, cinematic slow push in, no text, no logos, no watermark, no promotional marks",
"duration": 5,
"resolution": "1080p",
"aspect_ratio": "16:9",
"reference_image_urls": [
"https://cdn.vidgo.ai/apis/models/alibaba/happyhorse-1.0/reference-to-video/v1/01/input-01.png",
"https://cdn.vidgo.ai/apis/models/alibaba/happyhorse-1.0/reference-to-video/v1/01/input-02.png",
"https://cdn.vidgo.ai/apis/models/alibaba/happyhorse-1.0/reference-to-video/v1/01/input-03.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": "task-unified-...",
"status": "running",
"created_time": "2026-09-17T10:00:00Z"
}
}{
"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.0/reference-to-video",
"input": {
"prompt": "character1 stands at the workshop stage from character3 and brings the knight marionette character2 to life, making it bow and raise its wooden sword while warm lamp light flickers, cinematic slow push in, no text, no logos, no watermark, no promotional marks",
"duration": 5,
"resolution": "1080p",
"aspect_ratio": "16:9",
"reference_image_urls": [
"https://cdn.vidgo.ai/apis/models/alibaba/happyhorse-1.0/reference-to-video/v1/01/input-01.png",
"https://cdn.vidgo.ai/apis/models/alibaba/happyhorse-1.0/reference-to-video/v1/01/input-02.png",
"https://cdn.vidgo.ai/apis/models/alibaba/happyhorse-1.0/reference-to-video/v1/01/input-03.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 字段。
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| reference_image_urls | array | Yes | — | 字符串数组。包含 1–9 个参考图片 URL。 |
| prompt | string | Yes | — | 必填,非空且最多 2,500 个字符。描述参考主体、动作与运镜;无需特定角色标记。 |
| resolution | string | No | 1080p | 字符串。输出分辨率。支持 720p 与 1080p。 |
| duration | integer | No | 5 | 整数。输出时长 3–15 秒。 |
| aspect_ratio | string | No | 16:9 | 字符串。输出画面比例。支持 16:9、9:16、1:1、4:3、3:4。 |
| seed | integer | No | — | 整数。0 到 2147483647,用于稳定生成基底并复现镜头。 |
| enable_safety_checker | boolean | No | — | 布尔值。启用输入和输出的内容安全审核。 |
响应字段
任务提交返回 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 | 生成视频的公开 URL。 |
| data.files[].file_type | string | 文件类型,例如 video。 |
| data.error_message | string | null | status 为 failed 时的失败详情。 |
任务生命周期
在 not_started 或 running 时继续查询。在 finished 或 failed 时结束轮询。
not_started任务已接受,等待开始。
running生成进行中。继续轮询同一 task_id。
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 接收最终任务对象;投递失败时仍可轮询。
端点限制
| 规格 | 值 | 详情 |
|---|---|---|
| 输入模式 | 1–9 张参考图片 + 点名提示词 | 提供参考图片并在提示词中点名绑定角色。 |
| 参考图数量 | 1 至 9 张图片 URL | 传入 reference_image_urls 数组。 |
| 指代语法 | 自然语言描述;角色标记可选 | 按数组索引顺序在提示词中对应指代。 |
| 输出规格 | MP4 视频文件 | 异步生成返回 task_id;完成后提供视频下载地址。 |
| 分辨率 | 720p / 1080p | 默认预选 1080p。 |
| 时长 | 3–15 秒 | 默认预选 5 秒。 |
| 画面比例 | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 | 默认预选 16:9。 |
| 计费方式 | 按秒计费 | 720p 16 credits/s,1080p 32 credits/s。 |
相关模型
Happy Horse 1.0 Reference to Video API 常见问题
Happy Horse 1.0 Reference to Video API 是什么?
Happy Horse 1.0 Reference to Video 是阿里巴巴研发的基于参考图像生成视频的模型。它接收 1–9 张参考图片与结构化提示词,生成 3–15 秒、可选 720p 或 1080p 的电影感短视频,具备突出的角色身份绑定与多主体一致性控制能力。基于先进的多模态交叉注意力与特征解耦机制,它在保持人物容貌、服饰与道具特征稳定的同时,在全新运镜与叙事场景中生成连贯的动态交互。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Happy Horse 1.0 Reference to Video 最多支持几张参考图?
支持传入 1 到 9 张参考图片 URL。可自由混合角色的正侧面特写肖像、标志性服饰单品或特定道具图像,以提供多维度的视觉锚定特征。
如何在提示词中指代 Happy Horse 1.0 Reference to Video 的参考图?
描述各参考主体的外观、动作与相对位置。character1、character2 可用于示例表达,但并非必填格式。
Happy Horse 1.0 Reference to Video 可以用于多角色互动场景吗?
可以。传入各角色的参考图,并描述他们的外观、动作和相对位置;无需使用特定角色标记。
Happy Horse 1.0 Reference to Video 生成时画面会受首帧约束吗?
不会。该端点不是首帧定格起动模式,而是从多张参考图中提取核心特征嵌入,并在提示词所描述的全新空间视角、起始构图与运镜调度下自由生成动作。
Happy Horse 1.0 Reference to Video 支持 1080p 输出吗?
支持。可通过 resolution 参数在 720p 与 1080p 之间灵活选择。1080p 输出能完整呈现参考图中细致的布料纹理、发丝质感与眼神光彩。
什么时候该选用 Happy Horse 1.0 Reference to Video 而不是 Text to Video?
当需要指定某个特定角色、虚拟偶像、固定商品道具或独特画风跨镜头出场时,必须使用 Reference to Video;若仅需根据纯文本想象场景而无特定主角约束,则使用 Text to Video。















