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.

The service uses a dedicated HappyHorse channel in the Alibaba Cloud Model Studio Japan (Tokyo) region. Tokyo supports workspace-specific domains only. The API Host, API key, and models must belong to the same Tokyo workspace.

Channel Configuration (Alibaba Cloud Tokyo)

Setting	Value
Channel type	HappyHorse
Base URL	https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com
API key	API key from the Tokyo workspace

Enter only the Host root as the Base URL; do not append /api/v1. The service creates tasks through /api/v1/services/aigc/video-generation/video-synthesis and retrieves them through /api/v1/tasks/{task_id}.

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.1-t2v	Text to video	prompt only
happyhorse-1.1-i2v	Image to video	One first-frame image
happyhorse-1.1-r2v	Reference image to video	1–9 reference images
happyhorse-1.0-video-edit	Video editing	Source video URL

happyhorse-1.0-t2v, happyhorse-1.0-i2v, and happyhorse-1.0-r2v remain supported for compatibility, but new requests should use 1.1.

Tokyo List Prices

These are Alibaba Cloud Model Studio Tokyo list prices and do not include limited-time discounts:

Model	720P	1080P	Billable duration
happyhorse-1.1-t2v / happyhorse-1.1-i2v / happyhorse-1.1-r2v	¥0.9/s ($0.123769/s)	¥1.2/s ($0.165026/s)	Output video duration
happyhorse-1.0-video-edit	¥0.9/s ($0.123769/s)	¥1.6/s ($0.220034/s)	Input plus output video duration

Video Edit reserves the documented maximum of 30 billable seconds, then refunds or charges the difference from Alibaba Cloud's final usage.duration. Failed tasks are not billed.

Supported Modes

Mode	How to call
Text to video	Use prompt with happyhorse-1.1-t2v
Image to video	Use image, input_reference, or metadata.image_url with happyhorse-1.1-i2v
Reference image to video	Use images, metadata.image_urls, or metadata.media with happyhorse-1.1-r2v
Video editing	Use input_reference, metadata.video_url, or metadata.video_urls with happyhorse-1.0-video-edit

Request Parameters

Field	Type	Required	Description
model	string	Yes	HappyHorse model name
prompt	string	Yes	Video generation or editing prompt
duration	number	No	Generated video duration from 3 to 15 seconds. Defaults to 5. It is not sent for Video Edit
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

Examples

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.1-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.1-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.1-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"
}

Response and Retrieval

A successful create request returns a video task object:

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

Use either id or task_id to retrieve the task.

Retrieve the task:

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

Completed task response:

{
  "id": "video_xxx",
  "task_id": "video_xxx",
  "object": "video",
  "model": "happyhorse-1.1-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.