API 协议
HappyHorse:参数、场景与调用指南
预览指南
粘贴给 AI,帮助理解文档并完成接入。 仅包含文档与示例,不包含真实密钥。
直接答案1.1 顶层使用 prompt/image/images,设置放在 parameters;不要混用 seconds/size 或 Wan 的 reference_videos。
更新 · 审核信息
模型定位与适用场景
按 t2v、i2v、r2v 区分纯文字、单首帧和多参考图。1.1 的 r2v 是参考图片生视频,不等同于参考视频。
本指南核对本站请求契约,不代表所有场景均已完成收费出片验收。使用模型广场显示的精确模型、分组和有效端点;示例中的 example.com 素材与占位任务 ID 必须替换。先以最小请求确认可用,再逐项添加参考素材和高级参数。价格以模型广场及实际账单为准。
型号与入口
happyhorse-1.1-t2v, happyhorse-1.1-i2v, happyhorse-1.1-r2v
POST /v1/videos
参考素材格式
| 素材 | 字段 | 传输格式 | 文件准备与限制 |
|---|---|---|---|
| 图片参考 | image (i2v) / images[] (r2v) | HTTP(S) 图片直链或完整 data:image/<格式>;base64,...;不支持裸 Base64。 | 推荐 PNG/JPEG/WebP。i2v 为 1 张;r2v 为 1–9 张图片,r2v 不代表视频参考。t2v 不传 image/images。 |
| 参考 / 编辑视频 | — | 当前 1.1 型号未开放参考视频字段。 | 不要给 image/images 填 MP4、Base64 视频或任务 ID。 |
| 参考音频 | — | 未开放参考音频或 voice_id 输入。 | 输出音轨能力不等于支持输入音频;不能套用 Wan/Kling 字段。 |
参数与组合限制
- 1.1 顶层使用 prompt/image/images,设置放在 parameters;不要混用 seconds/size 或 Wan 的 reference_videos。
- t2v 不传图片;i2v 必须传 image,画幅跟随首帧,不能传 parameters.ratio;r2v 用 1–9 张 images。
- 1.1 支持 3–15 秒,480P/720P/1080P;示例显式设定值,不依赖未发送参数的默认行为。
- 参考图在提示词中可用 [Image 1]、[Image 2] 指代,顺序与 images 一致。
- 旧 1.0 系列及 video-edit 仍有目录记录,但当前发布规则没有开放其统一视频代码示例;不能把 1.1 参数直接当作 1.0 的验收结论。
| 字段 | 类型 | 用法与限制 |
|---|---|---|
Authorization | header string | 必填。使用 Bearer <本站 API Key>;JSON 请求使用 Content-Type: application/json。官方鉴权及区域域名由本站渠道处理。 |
model | string | 必填;1.1-t2v 文生、1.1-i2v 首帧、1.1-r2v 参考;使用完整 happyhorse- 前缀。 |
prompt | string | 对应官方 input.prompt;t2v/r2v 必填,i2v 官方可选。官方上限 2500 中文或 5000 非中文字符,超出截断;参考图用 [Image 1] 等编号。 |
image | string | 仅 i2v 必填,一张首帧;映射 input.media[{type:first_frame,url}]。公网 URL 或图片 data URI;JPEG/JPG/PNG/WEBP,≤20 MB,短边 ≥400 px。 |
images | string[] | 仅 r2v 必填,1–9 张;映射 type=reference_image,顺序对应 [Image N]。不能与 image 混用,素材规格同上。 |
parameters.duration | integer | 可选,3–15 秒,默认 5。 |
parameters.resolution | string | 可选,480P/720P/1080P,默认 1080P,注意大写 P。 |
parameters.ratio | string | t2v/r2v 默认 16:9;支持 16:9/9:16/1:1/4:3/3:4/4:5/5:4/9:21/21:9。i2v 由首帧决定,不传。 |
parameters.seed | integer | 可选,0–2147483647,省略时随机;显式 0 保留,不能保证结果完全复现。 |
parameters.watermark | boolean | 可选,官方默认 true;false 关闭右下角 Happy Horse 水印,显式 false 保留。 |
input / input.media[].type / input.media[].url | official object | 官方结构由本站 prompt/image/images 转换;本站入口使用平铺示例,不直接发送官方 input。未公开独立 audio、negative_prompt、prompt_extend 或尾帧控制。 |
X-DashScope-Async | official header | 官方异步创建要求 enable,由本站上游适配器设置。 |
场景与代码示例
文生视频
适用型号:happyhorse-1.1-t2v
POST /v1/videos
{
"model": "happyhorse-1.1-t2v",
"prompt": "一只白兔在晨光草地上奔跑。",
"parameters": {
"duration": 5,
"resolution": "720P",
"ratio": "16:9",
"seed": 0,
"watermark": false
}
}
curl
curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "happyhorse-1.1-t2v",
"prompt": "一只白兔在晨光草地上奔跑。",
"parameters": {
"duration": 5,
"resolution": "720P",
"ratio": "16:9",
"seed": 0,
"watermark": false
}
}'
python
import json
import os
import requests
url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
if not os.environ.get(name, "").strip():
raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"happyhorse-1.1-t2v\",\"prompt\":\"一只白兔在晨光草地上奔跑。\",\"parameters\":{\"duration\":5,\"resolution\":\"720P\",\"ratio\":\"16:9\",\"seed\":0,\"watermark\":false}}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))
javascript
// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
"model": "happyhorse-1.1-t2v",
"prompt": "一只白兔在晨光草地上奔跑。",
"parameters": {
"duration": 5,
"resolution": "720P",
"ratio": "16:9",
"seed": 0,
"watermark": false
}
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));
首帧图生视频
适用型号:happyhorse-1.1-i2v
POST /v1/videos
{
"model": "happyhorse-1.1-i2v",
"prompt": "保持主体外观,镜头缓慢推进。",
"image": "https://example.com/subject.png",
"parameters": {
"duration": 5,
"resolution": "720P",
"seed": 0,
"watermark": false
}
}
curl
curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "happyhorse-1.1-i2v",
"prompt": "保持主体外观,镜头缓慢推进。",
"image": "https://example.com/subject.png",
"parameters": {
"duration": 5,
"resolution": "720P",
"seed": 0,
"watermark": false
}
}'
python
import json
import os
import requests
url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
if not os.environ.get(name, "").strip():
raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"happyhorse-1.1-i2v\",\"prompt\":\"保持主体外观,镜头缓慢推进。\",\"image\":\"https://example.com/subject.png\",\"parameters\":{\"duration\":5,\"resolution\":\"720P\",\"seed\":0,\"watermark\":false}}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))
javascript
// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
"model": "happyhorse-1.1-i2v",
"prompt": "保持主体外观,镜头缓慢推进。",
"image": "https://example.com/subject.png",
"parameters": {
"duration": 5,
"resolution": "720P",
"seed": 0,
"watermark": false
}
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));
多参考图一致性
适用型号:happyhorse-1.1-r2v
POST /v1/videos
{
"model": "happyhorse-1.1-r2v",
"prompt": "[Image 1] 中的人物走入 [Image 2] 的场景。",
"images": [
"https://example.com/subject.png",
"https://example.com/end.png"
],
"parameters": {
"duration": 5,
"resolution": "720P",
"ratio": "9:16",
"watermark": false
}
}
curl
curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "happyhorse-1.1-r2v",
"prompt": "[Image 1] 中的人物走入 [Image 2] 的场景。",
"images": [
"https://example.com/subject.png",
"https://example.com/end.png"
],
"parameters": {
"duration": 5,
"resolution": "720P",
"ratio": "9:16",
"watermark": false
}
}'
python
import json
import os
import requests
url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
if not os.environ.get(name, "").strip():
raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"happyhorse-1.1-r2v\",\"prompt\":\"[Image 1] 中的人物走入 [Image 2] 的场景。\",\"images\":[\"https://example.com/subject.png\",\"https://example.com/end.png\"],\"parameters\":{\"duration\":5,\"resolution\":\"720P\",\"ratio\":\"9:16\",\"watermark\":false}}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))
javascript
// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
"model": "happyhorse-1.1-r2v",
"prompt": "[Image 1] 中的人物走入 [Image 2] 的场景。",
"images": [
"https://example.com/subject.png",
"https://example.com/end.png"
],
"parameters": {
"duration": 5,
"resolution": "720P",
"ratio": "9:16",
"watermark": false
}
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));
任务结果与下载
保存提交返回的 id 或 task_id。统一视频查询使用 GET /v1/videos/{task_id},等待 queued / in_progress 到 completed 或 failed;完成后读取 video_url(部分响应同时在 metadata.url 提供)。本站相对路径需与调用域名拼接,/content 入口使用本站 Key;外部下载 URL 不携带本站 Key。结果可能过期,请及时下载。网络超时保留任务 ID 继续 GET,不自动重试创建 POST。
统一视频完整 Python / JavaScript 轮询下载示例
常见问题定位
| 现象 | 检查方式 |
|---|---|
| Error validating image / 图片 URI 错误 | 视频或任务 ID 是否误填到了图片字段;检查媒体 URL 是否返回真实素材 |
| unsupported content type / 字段不支持 | 检查系列、版本和 content/contents/input 的准确类型;不要把音频 URL 填入 voice_id |
| 400 参数冲突 | 检查 prompt 与 input、首尾帧与多参考、秒数与 response_format 的互斥项 |
| HTTP 成功但任务 failed | 记录本站任务 ID、时间、模型、域名和已脱敏参数;按任务错误定位,不能依据提交 200 宣称成功 |
| 404 或不可访问任务 | 确认域名、Key 权限、本站任务类型;不要使用其他站点或官方任务 ID |
| 本地文件无法访问 | 使用系列明确支持的上传方式,或提供可读取的 HTTPS 媒体 URL |
资料与适用范围
适用场景
- 选择视频模型和素材协议
- 排查参数与任务失败
API 协议
/v1/videos
常见问题
拿到 task_id 就代表生成成功吗?
不代表。保存本站任务 ID,查询到成功终态并确认结果可读取后才算完成;failed 要查看错误,不要自动重建任务。
本地图片、视频和 WAV 能直接填写路径吗?
不能。URL 字段需要服务可读取的媒体地址;localhost、电脑路径及需要浏览器登录的链接不可用。Kling 本地 PCM WAV 的 multipart 音色上传需本站先启用该接口(2026-11-15 两站实测均为 404);其他素材按该系列上传或素材流程处理。
能把不同模型的参数和任务 ID 互换吗?
不能假定兼容。核对精确型号、入口、大小写、媒体角色及互斥字段。编辑、草稿和音色都要求对应类型、本人可访问的成功任务;官方能力也不等于本站已验收。
兔子API