Happy Horse Video Generation and Editing

Use Happy Horse through AceDataCloud for text-to-video, first-frame animation, reference-guided generation, and video editing.

Setup: See authentication for token setup.

Choose an Action

Goal	`action`	Valid models	Required input
Generate from text	`generate`	`happyhorse-1.0-t2v`, `happyhorse-1.1-t2v`	`prompt`
Animate one image	`image_to_video`	`happyhorse-1.0-i2v`, `happyhorse-1.1-i2v`	`image_url`
Generate from references	`reference_to_video`	`happyhorse-1.0-r2v`, `happyhorse-1.1-r2v`	`prompt`, 1-9 `image_urls`
Edit a video	`video_edit`	`happyhorse-1.0-video-edit`	`prompt`, `video_url`

The 1.1 model is the default where available. Video editing currently has only a 1.0 model.

Quick Start

Submit text-to-video asynchronously:

curl -X POST https://api.acedata.cloud/happyhorse/videos \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "generate",
    "model": "happyhorse-1.1-t2v",
    "prompt": "A cinematic white horse crossing a snowy ridge at sunrise, wind moving its mane, slow camera push",
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 5,
    "async": true
  }'

The response contains a task_id. Poll it after about 15 seconds:

curl -X POST https://api.acedata.cloud/happyhorse/tasks \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "<task_id>", "action": "retrieve"}'

Async: See async task polling. Continue until response.data[].video_url appears or a terminal error is returned.

Workflows

Text-to-Video

Use generate when no visual input exists. Describe the subject, action, environment, camera, lighting, and style.

POST /happyhorse/videos
{
  "action": "generate",
  "model": "happyhorse-1.1-t2v",
  "prompt": "A white horse gallops across a moonlit beach, side tracking shot, silver reflections, cinematic realism",
  "resolution": "1080P",
  "ratio": "16:9",
  "duration": 8,
  "seed": 42
}

First-Frame Image-to-Video

Use image_to_video to animate one image. prompt is optional but useful for motion and camera direction. The output ratio follows the first-frame image, so omit ratio.

POST /happyhorse/videos
{
  "action": "image_to_video",
  "model": "happyhorse-1.1-i2v",
  "image_url": "https://example.com/horse.jpg",
  "prompt": "The horse slowly lifts its head as the mane moves in the breeze, gentle camera push",
  "resolution": "1080P",
  "duration": 5
}

Reference-to-Video

Use reference_to_video with 1-9 reference images. Mention images as character1, character2, and so on in list order when the prompt needs to distinguish them.

POST /happyhorse/videos
{
  "action": "reference_to_video",
  "model": "happyhorse-1.1-r2v",
  "prompt": "character1 walks through a sunrise meadow wearing the leather and gold style from character2",
  "image_urls": [
    "https://example.com/subject.jpg",
    "https://example.com/style.jpg"
  ],
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}

Video Editing

Use video_edit with an existing video and editing instructions. Add at most 5 reference images for wardrobe, subject, style, or local replacement guidance. Use audio_setting: "origin" to preserve the source audio.

POST /happyhorse/videos
{
  "action": "video_edit",
  "model": "happyhorse-1.0-video-edit",
  "prompt": "Apply the warm leather and gold style from the reference while preserving camera motion",
  "video_url": "https://example.com/source.mp4",
  "image_urls": ["https://example.com/style.jpg"],
  "resolution": "720P",
  "audio_setting": "origin"
}

Do not send duration or ratio for video editing. Output duration follows the source video.

Parameters

Parameter	Values	Notes
`action`	`generate`, `image_to_video`, `reference_to_video`, `video_edit`	Defaults to `generate`
`model`	See action table	The model family must match the action
`prompt`	string	Required except for `image_to_video`
`image_url`	URL	First frame for `image_to_video`
`image_urls`	URL array	1-9 for reference generation; 0-5 for editing
`video_url`	URL	Required only for editing
`resolution`	`720P`, `1080P`	Uppercase `P` is required; default `1080P`
`ratio`	`16:9`, `9:16`, `1:1`, `4:3`, `3:4`	Text/reference generation only
`duration`	integer 3-15	Generation only; default 5 seconds
`watermark`	boolean	Default `false`
`audio_setting`	`auto`, `origin`	Video editing only; `origin` preserves source audio
`seed`	integer 0-2147483647	Optional reproducibility seed
`callback_url`	URL	Webhook for final result; returns immediately
`async`	boolean	Set `true` to return a task ID for polling

Task Queries

Retrieve one task:

POST /happyhorse/tasks
{"id": "<task_id>", "action": "retrieve"}

Retrieve several tasks:

POST /happyhorse/tasks
{"ids": ["<task_id_1>", "<task_id_2>"], "action": "retrieve_batch"}

A completed single-task response stores the original request in request and the final API result in response. Read the media URL from response.data[].video_url.

Gotchas

Match the model family to action; for example, an *-i2v model is invalid for generate
Resolution values are 720P and 1080P, not lowercase 720p / 1080p
Generated duration must be an integer from 3 through 15 seconds
image_to_video requires image_url; its prompt is optional and its ratio follows the image
reference_to_video requires a prompt and 1-9 images
video_edit requires both prompt and video URL, accepts at most 5 references, and ignores duration/ratio
audio_setting applies to video editing; use origin to preserve source audio
A task_id is not a completed result; poll until a final video URL or terminal error appears
Failed tasks are not billed; video edits use the upstream-reported input plus output duration for billing

MCP: pip install mcp-happyhorse | Hosted: https://happyhorse.mcp.acedata.cloud/mcp | See all MCP servers

happyhorse-video