HappyHorse Video

HappyHorse Video uses an asynchronous video task API. Create a task first, then poll the task endpoint for status and the final video URL.

Endpoints

Capability	Method	Path
Create video task	POST	/v1/video/generations
Retrieve video task	GET	/v1/video/generations/{task_id}

Every request requires an API key:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Models

Model	Use case	Required media
happyhorse-1.0-t2v	Text to video	prompt only
happyhorse-1.0-i2v	Image to video	One first-frame image
happyhorse-1.0-r2v	Reference image to video	One or more reference images
happyhorse-1.0-video-edit	Video editing	Source video URL

Request Parameters

Field	Type	Required	Description
model	string	Yes	HappyHorse model name
prompt	string	Yes	Video generation or editing prompt
duration	number	No	Video duration in seconds. Defaults to 5 if omitted
seconds	string	No	Duration as a string. Use either duration or seconds
size	string	No	Size or aspect ratio, such as 1920x1080, 1080x1920, 1:1, 16:9
image	string	No	Single image URL for image-to-video or reference image use cases
images	string[]	No	Multiple image URLs for reference images or editing references
input_reference	string	No	Reference media URL. It can be an image or a video
metadata	object	No	HappyHorse-specific options

metadata Fields

Field	Type	Description
resolution	string	Output resolution, 720P or 1080P
ratio	string	Output aspect ratio, such as 16:9, 9:16, 1:1, 4:3, 3:4
watermark	boolean	Whether to add a watermark
seed	number	Random seed
audio_setting	string	Audio setting, such as origin
image_url	string	Single image URL
image_urls	string[]	Multiple image URLs
video_url	string	Source video URL for video editing
video_urls	string[]	Source video URL list. The first URL is used by default
media	object[]	Explicit media list for advanced use cases

media item example:

{
  "type": "first_frame",
  "url": "https://example.com/first-frame.png"
}

Common type values:

type	Description
first_frame	First-frame image
reference_image	Reference image
video	Source video

Text to Video

curl -X POST https://cubicspaces.cloud/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "happyhorse-1.0-t2v",
    "prompt": "A cinematic aerial shot of a futuristic cubic city at sunrise, slow camera push-in, realistic lighting",
    "duration": 5,
    "size": "1920x1080",
    "metadata": {
      "resolution": "1080P",
      "ratio": "16:9",
      "watermark": false
    }
  }'

Image to Video

curl -X POST https://cubicspaces.cloud/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "happyhorse-1.0-i2v",
    "prompt": "Animate the product from the first frame with a slow clockwise rotation, keep the original composition and product shape stable",
    "image": "https://example.com/first-frame.png",
    "duration": 5,
    "metadata": {
      "resolution": "1080P",
      "watermark": false
    }
  }'

You can also provide the first-frame image as:

{
  "input_reference": "https://example.com/first-frame.png"
}

or:

{
  "metadata": {
    "image_url": "https://example.com/first-frame.png"
  }
}

Reference Image to Video

curl -X POST https://cubicspaces.cloud/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "happyhorse-1.0-r2v",
    "prompt": "Use the reference images to generate a short product showcase video, maintain the product identity and lighting consistency",
    "images": [
      "https://example.com/ref-1.png",
      "https://example.com/ref-2.png"
    ],
    "duration": 6,
    "metadata": {
      "resolution": "1080P",
      "ratio": "16:9",
      "watermark": false
    }
  }'

Video Editing

curl -X POST https://cubicspaces.cloud/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "happyhorse-1.0-video-edit",
    "prompt": "Replace the background with a clean studio scene while preserving the person, motion path, and timing of the source video",
    "metadata": {
      "video_url": "https://example.com/source.mp4",
      "resolution": "720P",
      "watermark": false
    }
  }'

You can also provide the source video as input_reference:

{
  "input_reference": "https://example.com/source.mp4"
}

Create Response

A successful create request returns a video task object:

{
  "id": "video_xxx",
  "task_id": "video_xxx",
  "object": "video",
  "model": "happyhorse-1.0-t2v",
  "status": "queued",
  "progress": 0,
  "created_at": 1770000000
}

Use either id or task_id to retrieve the task.

Retrieve Task

curl https://cubicspaces.cloud/v1/video/generations/video_xxx \
  -H "Authorization: Bearer YOUR_API_KEY"

Retrieve Response

{
  "id": "video_xxx",
  "task_id": "video_xxx",
  "object": "video",
  "model": "happyhorse-1.0-t2v",
  "status": "completed",
  "progress": 100,
  "created_at": 1770000000,
  "completed_at": 1770000120,
  "metadata": {
    "url": "https://example.com/output.mp4"
  }
}

Status Values

status	Description
queued	The task is queued
in_progress	The task is running
completed	The task has completed
failed	The task failed

When the task is completed, read the video URL from metadata.url.