> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a HappyHorse video
> Create a HappyHorse text-to-video or reference-image video task through CometAPI with POST /v1/videos, then poll the task and download the completed MP4 file.
Use this endpoint to create a HappyHorse video task. The API returns a task ID immediately, so store the returned `id` and poll the task until it reaches a terminal status.
`POST /v1/videos` uses `multipart/form-data`; pass scalar controls as form fields and reference images as `input_reference` file fields.
## Choose an input mode
| Goal | Model | Required fields | Optional fields |
| ------------------ | ---------------------------------- | --------------------------------------------- | ---------------------------------------- |
| Text-to-video | `happyhorse-1.0`, `happyhorse-1.1` | `model`, `prompt` | `seconds`, `size` |
| Reference-to-video | `happyhorse-1.0`, `happyhorse-1.1` | `model`, `prompt`, one `input_reference` file | `seconds`, `size`, more reference images |
For reference-to-video, upload 1-9 reference images by repeating the `input_reference` multipart field. CometAPI sends each uploaded file as a HappyHorse reference image. Use JPEG, JPG, PNG, or WEBP images up to 20 MB each; for best results, use images with a shortest side of at least 400 px.
## Set duration and size
| Model ID | `seconds` | Default |
| ---------------- | ---------------- | ------------------------ |
| `happyhorse-1.0` | integer `3`-`15` | `5` seconds, `1920x1080` |
| `happyhorse-1.1` | integer `3`-`15` | `5` seconds, `1920x1080` |
Set `size` to an exact `WxH` value.
| Model | Frame shape | `size` values |
| ---------------- | --------------------- | ----------------------- |
| `happyhorse-1.0` | Landscape | `1280x720`, `1920x1080` |
| | Portrait | `720x1280`, `1080x1920` |
| | Square | `1440x1440` |
| `happyhorse-1.1` | Landscape | `1280x720`, `1920x1080` |
| | Portrait | `720x1280`, `1080x1920` |
| | Square | `1440x1440` |
| | Classic landscape | `1440x1080` |
| | Classic portrait | `720x960`, `1080x1440` |
| | Wide landscape | `2520x1080` |
| | Wide portrait | `1080x2520` |
| | Near-square landscape | `900x720`, `1350x1080` |
| | Near-square portrait | `720x900`, `1080x1350` |
## Task flow
Send the multipart form request and store the returned `id`.
Call [Retrieve a HappyHorse video](./retrieve) until `status` is `completed`, `failed`, or `error`.
When the task is `completed`, call [Retrieve HappyHorse video content](./retrieve-content) to download the MP4 file.
## OpenAPI
````yaml api/openapi/video/happyhorse/post-create.openapi.json POST /v1/videos
openapi: 3.1.0
info:
title: HappyHorse Video Create API
version: 1.0.0
description: >-
Create an asynchronous HappyHorse video task through CometAPI. Send
text-to-video and reference-image video requests through the same POST
/v1/videos multipart endpoint. Save the returned id, poll GET
/v1/videos/{task_id}, and download the completed MP4 file.
servers:
- url: https://api.cometapi.com
security:
- bearerAuth: []
paths:
/v1/videos:
post:
summary: Create a HappyHorse video task
description: >-
Create a HappyHorse text-to-video or reference-image video task. Send
fields as multipart/form-data. Add one or more input_reference image
files for reference-to-video; repeat input_reference to upload multiple
images.
operationId: happyhorse_create_video
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/HappyHorseCreateRequest'
encoding:
input_reference:
contentType: image/jpeg, image/png, image/webp
examples:
happyhorse_1_1_text_to_video:
summary: HappyHorse 1.1 text-to-video
value:
model: happyhorse-1.1
prompt: >-
A close-up cinematic shot of a ceramic coffee cup on a
wooden table. Steam rises slowly while morning light moves
across the background.
seconds: '3'
size: 1920x1080
happyhorse_1_1_reference_to_video:
summary: HappyHorse 1.1 reference-to-video
value:
model: happyhorse-1.1
prompt: >-
Use the uploaded reference image as the visual guide. Create
a short cinematic shot with gentle natural motion.
seconds: '3'
size: 1280x720
input_reference: '@/path/to/reference.png'
happyhorse_1_0_text_to_video:
summary: HappyHorse 1.0 text-to-video
value:
model: happyhorse-1.0
prompt: >-
A person reads beside a tall window while soft daylight
moves across the room.
seconds: '3'
size: 1280x720
responses:
'200':
description: >-
Task created. Store the returned id and poll GET
/v1/videos/{task_id}.
content:
application/json:
schema:
$ref: '#/components/schemas/HappyHorseVideoTask'
example:
id: task_example
task_id: task_example
object: video
model: happyhorse-1.1
status: queued
progress: 0
created_at: 1779938152
'400':
description: >-
The request is missing a required field or contains a value that the
selected model cannot use.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: The API key is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- bearerAuth: []
x-codeSamples:
- lang: Shell
label: HappyHorse 1.1 text-to-video
source: |-
curl https://api.cometapi.com/v1/videos \
-H "Authorization: Bearer $COMETAPI_KEY" \
-F model=happyhorse-1.1 \
-F 'prompt=A close-up cinematic shot of a ceramic coffee cup on a wooden table. Steam rises slowly while morning light moves across the background.' \
-F seconds=3 \
-F size=1920x1080
- lang: Python
label: HappyHorse 1.1 text-to-video
source: |
import os
import requests
fields = [
("model", (None, "happyhorse-1.1")),
("prompt", (None, "A close-up cinematic shot of a ceramic coffee cup on a wooden table. Steam rises slowly while morning light moves across the background.")),
("seconds", (None, "3")),
("size", (None, "1920x1080")),
]
response = requests.post(
"https://api.cometapi.com/v1/videos",
headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
files=fields,
timeout=120,
)
response.raise_for_status()
print(response.json())
- lang: JavaScript
label: HappyHorse 1.1 text-to-video
source: >
const form = new FormData();
form.append("model", "happyhorse-1.1");
form.append("prompt", "A close-up cinematic shot of a ceramic coffee
cup on a wooden table. Steam rises slowly while morning light moves
across the background.");
form.append("seconds", "3");
form.append("size", "1920x1080");
const response = await fetch("https://api.cometapi.com/v1/videos", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },
body: form,
});
const result = await response.json();
console.log(result);
- lang: Shell
label: HappyHorse 1.1 reference-to-video
source: |-
curl https://api.cometapi.com/v1/videos \
-H "Authorization: Bearer $COMETAPI_KEY" \
-F model=happyhorse-1.1 \
-F 'prompt=Use the uploaded reference image as the visual guide. Create a short cinematic shot with gentle natural motion.' \
-F seconds=3 \
-F size=1280x720 \
-F 'input_reference=@/path/to/reference.png'
- lang: Python
label: HappyHorse 1.1 reference-to-video
source: >
import os
import requests
prompt = "Use the uploaded reference image as the visual guide.
Create a short cinematic shot with gentle natural motion."
with open("/path/to/reference.png", "rb") as reference:
response = requests.post(
"https://api.cometapi.com/v1/videos",
headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
data={
"model": "happyhorse-1.1",
"prompt": prompt,
"seconds": "3",
"size": "1280x720",
},
files={"input_reference": ("reference.png", reference, "image/png")},
timeout=120,
)
response.raise_for_status()
print(response.json())
- lang: JavaScript
label: HappyHorse 1.1 reference-to-video
source: >
import { readFile } from "node:fs/promises";
const reference = await readFile("/path/to/reference.png");
const form = new FormData();
form.append("model", "happyhorse-1.1");
form.append("prompt", "Use the uploaded reference image as the
visual guide. Create a short cinematic shot with gentle natural
motion.");
form.append("seconds", "3");
form.append("size", "1280x720");
form.append("input_reference", new Blob([reference], { type:
"image/png" }), "reference.png");
const response = await fetch("https://api.cometapi.com/v1/videos", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },
body: form,
});
const result = await response.json();
console.log(result);
- lang: Shell
label: HappyHorse 1.0 text-to-video
source: |-
curl https://api.cometapi.com/v1/videos \
-H "Authorization: Bearer $COMETAPI_KEY" \
-F model=happyhorse-1.0 \
-F 'prompt=A person reads beside a tall window while soft daylight moves across the room.' \
-F seconds=3 \
-F size=1280x720
- lang: Python
label: HappyHorse 1.0 text-to-video
source: |
import os
import requests
fields = [
("model", (None, "happyhorse-1.0")),
("prompt", (None, "A person reads beside a tall window while soft daylight moves across the room.")),
("seconds", (None, "3")),
("size", (None, "1280x720")),
]
response = requests.post(
"https://api.cometapi.com/v1/videos",
headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
files=fields,
timeout=120,
)
response.raise_for_status()
print(response.json())
- lang: JavaScript
label: HappyHorse 1.0 text-to-video
source: >
const form = new FormData();
form.append("model", "happyhorse-1.0");
form.append("prompt", "A person reads beside a tall window while
soft daylight moves across the room.");
form.append("seconds", "3");
form.append("size", "1280x720");
const response = await fetch("https://api.cometapi.com/v1/videos", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },
body: form,
});
const result = await response.json();
console.log(result);
components:
schemas:
HappyHorseCreateRequest:
type: object
required:
- model
- prompt
properties:
model:
type: string
description: HappyHorse model ID for this endpoint.
enum:
- happyhorse-1.0
- happyhorse-1.1
example: happyhorse-1.1
prompt:
type: string
description: >-
Text prompt that describes the video to generate. For
reference-image requests, combine the prompt with the uploaded
reference image.
example: >-
Use the uploaded reference image as the visual guide. Create a short
cinematic shot with gentle natural motion.
seconds:
type: string
description: >-
Requested clip duration in seconds. Use an integer from 3 through
15. Default is 5.
example: '3'
size:
type: string
description: >-
Output size as an exact WxH value. Use one of the documented size
values for the selected HappyHorse model.
example: 1920x1080
input_reference:
type: string
format: binary
description: >-
Reference image file for reference-to-video. Required when using
reference-to-video; repeat this multipart field to send additional
reference images. CometAPI preserves upload order. Use JPEG, JPG,
PNG, or WEBP images up to 20 MB each.
additionalProperties: false
HappyHorseVideoTask:
type: object
required:
- id
- object
- model
- status
- progress
- created_at
properties:
id:
type: string
description: Task ID. Use this value with retrieve and content endpoints.
example: task_example
task_id:
type: string
description: Compatibility alias for id when present.
example: task_example
object:
type: string
description: Object type. Video tasks return video.
example: video
model:
type: string
description: Model ID used for the task.
example: happyhorse-1.1
status:
type: string
description: >-
Task lifecycle status. Poll until the value is completed, failed, or
error.
enum:
- queued
- in_progress
- completed
- failed
- error
example: queued
progress:
type: integer
minimum: 0
maximum: 100
description: Task progress as a coarse percentage.
example: 0
created_at:
type: integer
description: Task creation time as a Unix timestamp in seconds.
example: 1779938152
completed_at:
type: integer
description: >-
Task completion time as a Unix timestamp in seconds. This field
appears on completed tasks.
example: 1779938219
video_url:
type: string
description: Temporary video delivery URL. This field appears on completed tasks.
example:
error:
type: object
description: Failure details. This field appears when the task fails.
additionalProperties: true
additionalProperties: true
ErrorResponse:
description: Error body returned when a request cannot be created or the task fails.
type: object
additionalProperties: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer authentication. Use your CometAPI API key.
````