| name | happyhorse-video |
| description | Generate and edit AI videos with Happy Horse via AceDataCloud API. Use when creating videos from text prompts, animating a first-frame image, generating scenes from up to 9 subject or style reference images, or editing an existing video with optional references. Supports 720P/1080P output, 3-15 second generation, aspect-ratio control, audio preservation, seeds, callbacks, and asynchronous task polling. |
| license | Apache-2.0 |
| metadata | {"author":"acedatacloud","version":"1.0"} |
| compatibility | Requires ACEDATACLOUD_API_TOKEN in .env file (see _shared/authentication.md). Optionally pair with mcp-happyhorse for tool-use. |
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 imagereference_to_video requires a prompt and 1-9 imagesvideo_edit requires both prompt and video URL, accepts at most 5 references, and ignores duration/ratioaudio_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
