API protocol
HappyHorse: parameters, scenarios and API guide
Preview guide
Paste into an AI assistant to help with integration. Documentation and examples only; no real credentials.
Direct answerFor 1.1 use prompt/image/images with settings in parameters, not seconds/size or Wan reference_videos.
Updated · Reviewed
Purpose and workflows
t2v uses text, i2v a first frame and r2v reference images. Version 1.1 r2v does not mean video input.
This guide checks the site request contract; it does not claim paid generation acceptance for every scenario. Use the exact model, group and available endpoint shown in the marketplace. Replace example.com media and placeholder task IDs. Confirm a minimal request before adding references and advanced parameters. Consult marketplace pricing and actual billing for charges.
Models and endpoints
happyhorse-1.1-t2v, happyhorse-1.1-i2v, happyhorse-1.1-r2v
POST /v1/videos
Reference media formats
| Media | Fields | Encoding and transport | Preparation and limits |
|---|---|---|---|
| Image references | image (i2v) / images[] (r2v) | HTTP(S) image URL or full data:image/<format>;base64,... URI; no raw Base64. | Prefer PNG/JPEG/WebP. i2v takes one image; r2v takes 1–9 images, not video references. t2v accepts neither image nor images. |
| Reference / edit video | — | No reference-video input is exposed for the current 1.1 models. | Do not put MP4, video Base64 or task IDs in image/images. |
| Reference audio | — | No reference-audio or voice_id input is exposed. | Output audio does not imply audio input support; do not reuse Wan/Kling fields. |
Parameters and combinations
- For 1.1 use prompt/image/images with settings in parameters, not seconds/size or Wan reference_videos.
- t2v has no images; i2v requires image and derives aspect ratio from it, so omit parameters.ratio; r2v requires 1–9 images.
- Version 1.1 accepts 3–15 seconds and 480P/720P/1080P. Examples set values explicitly.
- Refer to images in order as [Image 1], [Image 2].
- Legacy 1.0 and video-edit have catalog entries, but their unified video examples remain unpublished. A 1.1 example is not acceptance for 1.0.
| Field | Type | Use and constraints |
|---|---|---|
Authorization | header string | Required: Bearer <site API key>, with Content-Type: application/json. Provider credentials and regional endpoints are managed by the service. |
model | string | Required: full happyhorse-1.1-t2v/i2v/r2v ID for text, first frame or references. |
prompt | string | Maps to input.prompt; required for t2v/r2v, officially optional for i2v. Official limit 2500 Chinese or 5000 non-Chinese characters, truncated beyond it. Refer to images as [Image 1], etc. |
image | string | Required for i2v only: one first image, mapped to input.media[{type:first_frame,url}]. Public URL or image data URI; JPEG/JPG/PNG/WEBP, ≤20 MB, short side ≥400px. |
images | string[] | Required for r2v only: 1–9 images, mapped to reference_image in [Image N] order. Excludes image; same media limits as above. |
parameters.duration | integer | Optional, 3–15 seconds, default 5. |
parameters.resolution | string | Optional, 480P/720P/1080P, default 1080P; uppercase P. |
parameters.ratio | string | t2v/r2v default 16:9; accepts 16:9/9:16/1:1/4:3/3:4/4:5/5:4/9:21/21:9. Omit for i2v, which follows the image. |
parameters.seed | integer | Optional, 0–2147483647, random when omitted; explicit zero is preserved, without exact reproducibility guarantees. |
parameters.watermark | boolean | Optional, official default true; false disables the bottom-right Happy Horse watermark and is preserved. |
input / input.media[].type / input.media[].url | official object | The site maps prompt/image/images to the official input shape. Use the site flat examples, not direct input. No separate audio, negative_prompt, prompt_extend or last-frame controls are exposed. |
X-DashScope-Async | official header | Official async creation requires enable; the site upstream adapter sets it. |
Scenarios and code examples
Text to video
Applies to: 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));
First-frame animation
Applies to: 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));
Multiple image references
Applies to: 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));
Task results and downloads
Save id or task_id from submission. Poll GET /v1/videos/{task_id}: queued / in_progress lead to completed or failed. Read video_url on completion (some responses also expose metadata.url). Resolve relative URLs against the API origin. The site /content endpoint uses your site key; external downloads must not receive that key. Download expiring results promptly. Resume GET after a timeout rather than automatically repeating POST.
Complete unified video Python / JavaScript polling and download examples
Troubleshooting
| Symptom | Check |
|---|---|
| Image validation / URI error | Ensure a video or task ID was not placed in an image field; check the URL returns media |
| Unsupported content type / field | Check the exact family and content/contents/input schema; voice_id cannot be an audio URL |
| 400 conflicting fields | Check prompt/input, frames/references, and seconds/response_format exclusivity |
| HTTP success but task failed | Retain the site task ID, time, model, domain and redacted request; submission 200 is not output success |
| 404 or inaccessible task | Check domain, key access and task type; do not use IDs from another site or the official API |
| Local file cannot be fetched | Use a supported upload flow or a reachable HTTPS media URL |
Sources and scope
Use cases
- Choose video models and media formats
- Diagnose request and task failures
API protocols
/v1/videos
FAQ
Does a task ID prove generation succeeded?
No. Save the site task ID, poll to a successful terminal state and verify the result. Inspect failures instead of automatically creating a new task.
Can I put a local image, video or WAV path in JSON?
No. URL fields require reachable media, not localhost, disk paths or browser-login links. Kling PCM WAV requires an enabled multipart voice endpoint (both sites returned 404 on 2026-11-15). Follow each family’s asset workflow for other media.
Can parameters and task IDs be reused across models?
Do not assume compatibility. Check the exact model, endpoint, casing, media role and exclusive fields. Editing, drafts and voices require accessible successful tasks of the correct kind. Official capabilities are not evidence of site acceptance.
Related guides
Official sources
- HappyHorse text API Official
- HappyHorse image API Official
- HappyHorse reference API Official
兔子API