UnityClaw Video (HappyHorse)
Generate HappyHorse video using text, reference images, or first-frame guidance and return verified local files.
Agent Workflow
1. Define the shot
Extract the subject, temporal action, camera movement, setting, composition, lighting, style, duration, target layout, and role of every reference image. Keep a short clip focused on one coherent shot.
Describe visible motion and continuity. For first-frame mode, state what should move and what should remain anchored to the source composition. For multiple references, state what each contributes rather than treating them as interchangeable.
2. Choose the mode
| Need | Action | Attachments |
|---|---|---|
| Text-only or multi-reference generation | reference_image |
0 to 9 images |
| Animate a supplied opening frame | first_frame |
Exactly 1 image |
Use 720P for a quick draft and 1080P when final detail matters. In first_frame mode, ratio is determined by the source and is not sent to the API.
3. Execute and validate
Run scripts/generate.js with --json and an explicit --output-dir. Prefer repeated --attachment flags. Quote user-derived arguments and do not issue duplicate concurrent generations.
Accept completion only when success is true and every returned video has an existing local path and positive byte size. Return the local files and state action, resolution, ratio when applicable, and duration.
Retry only when error.retryable is true. Wait for user feedback before spending another generation on a subjective change.
Configuration
Set the fixed UNITYCLAW_KEY environment variable. The runtime installation declaration installs @unityclaw/sdk; for manual execution, run npm install @unityclaw/sdk if needed.
Usage
node scripts/generate.js --prompt "A horse runs through a foggy valley at sunrise" --resolution 720P --ratio 16:9 --duration 5
node scripts/generate.js --action first_frame --attachment ./cover.png --prompt "Slow camera push-in with subtle depth" --resolution 1080P --duration 4 --json --output-dir ./tasks
Parameters
| Parameter | Short | Required | Default | Description |
|---|---|---|---|---|
--prompt |
-p |
Yes | - | Motion-aware video prompt |
--action |
-a |
No | reference_image |
reference_image or first_frame |
--attachment |
-i |
Conditional | - | Reference URL/local image; repeat or use comma-separated values |
--resolution |
-q |
No | 1080P |
720P or 1080P |
--ratio |
-r |
No | 16:9 |
Ignored for first_frame |
--duration |
-d |
No | 5 |
Integer from 3 to 15 seconds |
--output-dir |
- | No | ./tasks |
Task output directory, resolved absolutely |
--timeout |
- | No | 1800000 |
Timeout from 1,000 to 3,600,000 milliseconds |
--retries |
- | No | 1 |
Transient retry count from 0 to 3 |
--json |
- | No | false |
Emit one machine-readable JSON object |
--help |
-h |
No | - | Show help |
Supported ratios: 16:9, 9:16, 1:1, 4:3, 3:4.
Output Contract
With --json, success includes task metadata, selected settings, and verified files. Failure includes a stable error code, message, retryability, attempts, and available task information.
Resource Index
- Run
scripts/generate.jsfor HappyHorse video generation.
