> ## 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` ファイルを 1 つ | `seconds`, `size`, 追加の参照画像 |
参照画像から動画の場合は、`input_reference` の multipart フィールドを繰り返して、1～9 枚の参照画像をアップロードします。CometAPI はアップロードされた各ファイルを HappyHorse の参照画像として送信します。各画像は 20 MB までの JPEG、JPG、PNG、または WEBP を使用できます。より良い結果を得るには、短辺が少なくとも 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` を保存します。
`status` が `completed`、`failed`、または `error` になるまで [HappyHorse 動画を取得する](./retrieve) を呼び出します。
タスクが `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.
````