diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index b98a22c..5c337f4 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,7 +11,7 @@ "plugins": [ { "name": "acedatacloud-ai-media", - "description": "AI media generation: music (Suno, Producer, Fish Audio), images (Flux, Seedream, NanoBanana), video (Luma, Sora, Veo, Kling, Hailuo, Seedance, Maestro)", + "description": "AI media generation: music (Suno, Producer, Fish Audio), images (Flux, Seedream, NanoBanana), video (Luma, Sora, Veo, Kling, Hailuo, Happy Horse, Seedance, Maestro)", "source": "./", "strict": false, "skills": [ @@ -26,6 +26,7 @@ "./skills/veo-video", "./skills/kling-video", "./skills/hailuo-video", + "./skills/happyhorse-video", "./skills/seedance-video", "./skills/maestro-video", "./skills/wan-video" diff --git a/AGENTS.md b/AGENTS.md index 601a47a..ef1b613 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,6 +22,7 @@ Skills are located in the `skills/` directory (also mirrored to `.agents/skills/ - **veo-video** — Generate videos with Google Veo (native audio) - **kling-video** — Generate videos with Kuaishou Kling (motion control) - **hailuo-video** — Generate videos with Hailuo / MiniMax +- **happyhorse-video** — Generate and edit videos with Happy Horse - **seedance-video** — Generate dance/motion videos with ByteDance Seedance - **wan-video** — Generate videos with Alibaba Wan - **maestro-video** — Produce complete videos from a brief with scripting, media, voiceover, editing, captions, and multilingual variants diff --git a/README.md b/README.md index 529f930..ed4f9f1 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,7 @@ Compatible with **30+ AI coding agents** via the [agentskills.io](https://agents | [veo-video](skills/veo-video/) | Generate videos with Google Veo (native audio) | | [kling-video](skills/kling-video/) | Generate videos with Kuaishou Kling (motion control) | | [hailuo-video](skills/hailuo-video/) | Generate videos with Hailuo / MiniMax | +| [happyhorse-video](skills/happyhorse-video/) | Generate and edit videos with Happy Horse | | [seedance-video](skills/seedance-video/) | Generate dance/motion videos with ByteDance Seedance | | [maestro-video](skills/maestro-video/) | Produce complete videos from a brief with script, media, voiceover, captions, and editing | @@ -211,6 +212,7 @@ Skills provide **knowledge** (when to use, parameters, gotchas). MCP servers pro | veo-video | [mcp-veo](https://pypi.org/project/mcp-veo/) | `pip install mcp-veo` | `https://veo.mcp.acedata.cloud/mcp` | | seedream-image | [mcp-seedream](https://pypi.org/project/mcp-seedream/) | `pip install mcp-seedream` | `https://seedream.mcp.acedata.cloud/mcp` | | seedance-video | [mcp-seedance](https://pypi.org/project/mcp-seedance/) | `pip install mcp-seedance` | `https://seedance.mcp.acedata.cloud/mcp` | +| happyhorse-video | [mcp-happyhorse](https://pypi.org/project/mcp-happyhorse/) | `pip install mcp-happyhorse` | `https://happyhorse.mcp.acedata.cloud/mcp` | | maestro-video | [mcp-maestro](https://pypi.org/project/mcp-maestro/) | `pip install mcp-maestro` | `https://maestro.mcp.acedata.cloud/mcp` | | nano-banana-image | [mcp-nano-banana](https://pypi.org/project/mcp-nano-banana/) | `pip install mcp-nano-banana` | `https://nano-banana.mcp.acedata.cloud/mcp` | | short-url | [mcp-shorturl](https://pypi.org/project/mcp-shorturl/) | `pip install mcp-shorturl` | `https://short-url.mcp.acedata.cloud/mcp` | diff --git a/package.json b/package.json index 95f2017..9e56d36 100644 --- a/package.json +++ b/package.json @@ -16,6 +16,7 @@ "luma", "sora", "veo", + "happyhorse", "ai-music", "ai-image", "ai-video", diff --git a/skills/_shared/mcp-servers.md b/skills/_shared/mcp-servers.md index 1bee10a..3b55be0 100644 --- a/skills/_shared/mcp-servers.md +++ b/skills/_shared/mcp-servers.md @@ -15,6 +15,7 @@ Each AceDataCloud service has a corresponding MCP server that provides tool-use | veo-video | `pip install mcp-veo` | `https://veo.mcp.acedata.cloud/mcp` | | seedream-image | `pip install mcp-seedream` | `https://seedream.mcp.acedata.cloud/mcp` | | seedance-video | `pip install mcp-seedance` | `https://seedance.mcp.acedata.cloud/mcp` | +| happyhorse-video | `pip install mcp-happyhorse` | `https://happyhorse.mcp.acedata.cloud/mcp` | | maestro-video | `pip install mcp-maestro` | `https://maestro.mcp.acedata.cloud/mcp` | | nano-banana-image | `pip install mcp-nano-banana` | `https://nano-banana.mcp.acedata.cloud/mcp` | | short-url | `pip install mcp-shorturl` | `https://short-url.mcp.acedata.cloud/mcp` | diff --git a/skills/happyhorse-video/SKILL.md b/skills/happyhorse-video/SKILL.md new file mode 100644 index 0000000..7c4bd10 --- /dev/null +++ b/skills/happyhorse-video/SKILL.md @@ -0,0 +1,190 @@ +--- +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](../_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": "", "action": "retrieve"}' +``` + +> **Async:** See [async task polling](../_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": "", "action": "retrieve"} +``` + +Retrieve several tasks: + +```json +POST /happyhorse/tasks +{"ids": ["", ""], "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](../_shared/mcp-servers.md) \ No newline at end of file