Create a Happy Horse Video Task

In this page's examples, {BASE_URL} is https://api.uniall.ai.

Updated: 2026-08-10

Overview

Use the single public model happy-horse. Select text generation, image animation, multi-reference generation, or video editing through operation, and select the output tier through resolution.

Do not use the removed tier-specific model IDs. They are intentionally incompatible with the current public contract.

Endpoint

POST /v1/videos

Compatible create paths:

POST /v1/videos/generations
POST /v1/video/generations

New integrations should use /v1/videos.

Authentication

Authorization: Bearer sk-***
Content-Type: application/json

Operation Matrix

`operation`	Prompt	Image input	Video input	Resolution	`duration`	`aspect_ratio`
`text_to_video`	Required	None	None	`720p`, `1080p`	Optional, default `5`	Optional, default `16:9`
`image_to_video`	Optional	Exactly 1	None	`720p`, `1080p`	Optional, default `5`	Not supported
`reference_to_video`	Required	1 to 9	None	`720p`, `1080p`	Optional, default `5`	Optional, default `16:9`
`edit_video`	Required	0 to 5	Exactly 1	`720p`, `1080p`	Not supported	Not supported

Request Body Parameters

Parameter	Type	Required	Description
`model`	string	Yes	Must be `happy-horse`.
`operation`	string	Yes	`text_to_video`, `image_to_video`, `reference_to_video`, or `edit_video`.
`resolution`	string	Yes	`720p` or `1080p` for every operation.
`prompt`	string	Conditional	Required except for `image_to_video`; maximum `2500` characters.
`duration`	integer	No	Generation only. `3` to `15`, default `5`. Do not send it for editing.
`aspect_ratio`	string	No	Text and multi-reference generation only. Do not send it for image animation or editing.
`image`	string	Conditional	Recommended field for the one HTTP(S) image used by `image_to_video`.
`images`	string[]	Conditional	1 to 9 HTTP(S) images for `reference_to_video`.
`reference_image_urls`	string[]	No	Alias for multi-reference images; also supports up to 5 edit reference images.
`video`	string	Conditional	One HTTP(S) source video for `edit_video`.
`seed`	integer	No	Random seed from `0` to `2147483647`.
`watermark`	boolean	No	Whether to add a watermark. Default `false`.
`audio_setting`	string	No	Editing only: `auto` or `origin`. Default `auto`.

Supported aspect_ratio values for text and multi-reference generation:

16:9
9:16
1:1
4:3
3:4
4:5
5:4
9:21
21:9

size and enable_safety_checker are not Happy Horse public parameters and are rejected.

480p is not available for the public HappyHorse 1.0 contract. Requests that set resolution to 480p are rejected before a task is created.

Input Rules

Mode	Valid media fields
Text-to-video	No image or video field
Image-to-video	`image`, or one item through a supported image alias
Multi-reference video	`images` or `reference_image_urls`, with 1 to 9 URLs
Video editing	`video`, plus up to 5 optional `reference_image_urls`

All media inputs must be complete public HTTP or HTTPS URLs. File uploads, bare Base64 values, and Data URLs are not accepted by this model contract.

Request Examples

Text-to-video

curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "text_to_video",
    "resolution": "1080p",
    "prompt": "A white horse runs across a misty grassland at sunrise, realistic movement and soft rim light.",
    "duration": 7,
    "aspect_ratio": "21:9",
    "seed": 12345,
    "watermark": false
  }'

Image-to-video

The output composition follows the source image, so do not send aspect_ratio.

curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "image_to_video",
    "resolution": "720p",
    "image": "https://example.com/source-frame.png",
    "prompt": "The subject walks forward naturally while the camera slowly pushes in.",
    "duration": 5,
    "seed": 67890,
    "watermark": false
  }'

The prompt may be omitted for image_to_video.

Multi-reference video

Use character1 through character9 in the prompt to refer to images in array order.

curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "reference_to_video",
    "resolution": "720p",
    "prompt": "character1 drives character2 across the lunar surface while both identities remain consistent.",
    "reference_image_urls": [
      "https://example.com/character.png",
      "https://example.com/vehicle.png"
    ],
    "duration": 8,
    "aspect_ratio": "16:9",
    "seed": 24680,
    "watermark": false
  }'

Video editing

Editing follows the source video duration and does not accept duration or aspect_ratio.

curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "edit_video",
    "resolution": "1080p",
    "prompt": "Replace the jacket with the referenced red jacket while preserving identity, motion, camera movement, and background.",
    "video": "https://example.com/source-video.mp4",
    "reference_image_urls": [
      "https://example.com/red-jacket.png"
    ],
    "audio_setting": "origin",
    "seed": 13579,
    "watermark": false
  }'

Use audio_setting: "origin" to preserve the original audio. Use auto to let the service choose the audio handling behavior.

`extra_body` Compatibility

Top-level parameters are recommended. operation, resolution, seed, watermark, and audio_setting may also be placed in extra_body for compatible clients. Do not send conflicting top-level and nested values.

{
  "model": "happy-horse",
  "prompt": "Turn the room into a warm wooden studio.",
  "video": "https://example.com/source-video.mp4",
  "extra_body": {
    "operation": "edit_video",
    "resolution": "720p",
    "audio_setting": "auto",
    "watermark": false
  }
}

Response Examples

Task accepted

{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "happy-horse",
  "status": "queued",
  "progress": 0,
  "created_at": 1785801600,
  "video_url": null
}

Task Status And Result

After creation, save id or task_id, then poll GET /v1/videos/{task_id} until the task reaches completed or failed. See Video Generation Overview for the shared polling interval, status fields, error contract, result URL, and authenticated download flow.

For final-settlement operations such as video editing, read billing_contract again after completion.

Media Constraints

Image-to-video source image

Formats: JPEG, JPG, PNG, BMP, or WebP.
Minimum dimensions: 300px.
Aspect ratio: from 1:2.5 through 2.5:1.
Maximum file size: 10MB.

Multi-reference images

Formats: JPEG, JPG, PNG, or WebP.
Count: 1 to 9.
Minimum short edge: 400px; 720p or higher is recommended.
Maximum file size: 10MB per image.

Video-editing source

Formats: MP4 or MOV; H.264 is recommended.
Input duration: 3 to 60 seconds; the editing service processes at most 15 seconds.
Dimensions: long edge up to 2160px, short edge at least 320px.
Aspect ratio: from 1:2.5 through 2.5:1.
Frame rate: greater than 8fps.
Maximum file size: 100MB.

Edit reference images support JPEG, JPG, PNG, or WebP, must be at least 300px, and are limited to 10MB each.

Billing Notes

Text, image, and multi-reference generation use the requested output duration and resolution tier for settlement.
Editing is finally settled from the actual input and output video durations. The final charge can differ from the initial estimate.
resolution is a service tier and does not guarantee one exact pixel dimension for every aspect ratio or source image.
Refer to the current UniAll pricing page and task settlement record for the final amount.

Common Errors

Error	Cause	Fix
Invalid model	A removed tier-specific model ID was used	Set `model` to `happy-horse`
Missing parameter	`operation` or `resolution` is absent	Send both parameters explicitly
Unsupported parameter	`size` or `enable_safety_checker` was sent	Remove the unsupported field
Invalid media count	The selected operation received the wrong number of images or videos	Follow the operation matrix
Invalid resolution	`resolution` is `480p` or another unsupported value	Use `720p` or `1080p`
Invalid edit options	Editing includes `duration` or `aspect_ratio`	Remove the unsupported fields
Media download failed	A media URL is private, expired, redirected incorrectly, or unreachable	Use a stable public HTTPS URL

Overview​

Endpoint​

Authentication​

Operation Matrix​

Request Body Parameters​

Input Rules​

Request Examples​

Text-to-video​

Image-to-video​

Multi-reference video​

Video editing​

extra_body Compatibility​

Response Examples​

Task accepted​

Task Status And Result​

Media Constraints​

Image-to-video source image​

Multi-reference images​

Video-editing source​

Billing Notes​

Common Errors​

Related Pages​