> ## 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.
# 创建 HappyHorse 视频
> 通过 CometAPI 使用 POST /v1/videos 创建 HappyHorse 文本生成视频或参考图生成视频任务，然后轮询任务并下载完成后的 MP4 文件。
使用此端点创建 HappyHorse 视频任务。API 会立即返回任务 ID，因此请保存返回的 `id`，并轮询任务直到其达到终态状态。
`POST /v1/videos` 使用 `multipart/form-data`；将标量控制项作为表单字段传递，将参考图像作为 `input_reference` 文件字段传递。
## 选择输入模式
| 目标 | Model | 必填字段 | 可选字段 |
| ------- | ---------------------------------- | ------------------------------------------ | ------------------------- |
| 文本生成视频 | `happyhorse-1.0`, `happyhorse-1.1` | `model`, `prompt` | `seconds`, `size` |
| 参考图生成视频 | `happyhorse-1.0`, `happyhorse-1.1` | `model`, `prompt`, 一个 `input_reference` 文件 | `seconds`, `size`, 更多参考图像 |
对于参考图生成视频，可通过重复 `input_reference` multipart 字段上传 1-9 张参考图像。CometAPI 会将每个上传的文件作为一张 HappyHorse 参考图像发送。请使用 JPEG、JPG、PNG 或 WEBP 格式的图像，每张最大 20 MB；为获得最佳效果，建议使用最短边至少为 400 px 的图像。
## 设置时长和尺寸
| Model ID | `seconds` | 默认值 |
| ---------------- | ----------- | ----------------- |
| `happyhorse-1.0` | 整数 `3`-`15` | `5` 秒，`1920x1080` |
| `happyhorse-1.1` | 整数 `3`-`15` | `5` 秒，`1920x1080` |
将 `size` 设置为精确的 `WxH` 值。
| Model | 画幅 | `size` 值 |
| ---------------- | ----- | ----------------------- |
| `happyhorse-1.0` | 横向 | `1280x720`, `1920x1080` |
| | 纵向 | `720x1280`, `1080x1920` |
| | 方形 | `1440x1440` |
| `happyhorse-1.1` | 横向 | `1280x720`, `1920x1080` |
| | 纵向 | `720x1280`, `1080x1920` |
| | 方形 | `1440x1440` |
| | 经典横向 | `1440x1080` |
| | 经典纵向 | `720x960`, `1080x1440` |
| | 宽幅横向 | `2520x1080` |
| | 宽幅纵向 | `1080x2520` |
| | 近方形横向 | `900x720`, `1350x1080` |
| | 近方形纵向 | `720x900`, `1080x1350` |
## 任务流程
发送 multipart 表单请求，并保存返回的 `id`。
调用 [获取 HappyHorse 视频](./retrieve)，直到 `status` 为 `completed`、`failed` 或 `error`。
当任务为 `completed` 时，调用 [获取 HappyHorse 视频内容](./retrieve-content) 下载 MP4 文件。
## 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.
````