---
name: happyhorse-video
description: HappyHorse (Happy Horse) video by Ace Data Cloud. Generate videos from text or images, use subject or style references, and edit existing videos. Use when the user asks for HappyHorse video generation or editing.
license: Apache-2.0
metadata:
  author: acedatacloud
  version: "1.0"
compatibility: Requires ACEDATACLOUD_API_TOKEN in the agent process environment and HTTPS access to api.acedata.cloud. See README.md for installation and key setup.
---

# HappyHorse by Ace Data Cloud

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

## Install and connect from skills.sh

This integration is maintained by **Ace Data Cloud**; it is not an official HappyHorse publisher listing. Install only this Skill with `npx skills add acedatacloud/skills --skill happyhorse-video --yes`, or use the [public skills.sh page](https://skills.sh/acedatacloud/skills/happyhorse-video). Keep the slug `happyhorse-video` when selecting it.

Read the [illustrated first-run guide](README.md) ([简体中文](readme.zh-CN.md)) for registration, **Applications → General application**, API key access and price checks, and the environment variable location for your coding agent. For skills.sh installations, use this guide; any ClawHub-specific setup applies only to OpenClaw. The shared references linked here are online because focused installs do not include sibling `_shared/` folders.

> **Setup:** See [authentication](https://github.com/AceDataCloud/Skills/blob/main/skills/_shared/authentication.md) 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:

```bash
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:

```bash
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](https://github.com/AceDataCloud/Skills/blob/main/skills/_shared/async-tasks.md). 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.

```json
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`.

```json
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.

```json
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.

```json
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:

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

Retrieve several tasks:

```json
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](https://github.com/AceDataCloud/Skills/blob/main/skills/_shared/mcp-servers.md)