> ## 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.

# Tạo video HappyHorse

> Tạo tác vụ video HappyHorse từ văn bản sang video hoặc từ ảnh tham chiếu thông qua CometAPI với POST /v1/videos, sau đó thăm dò tác vụ và tải xuống tệp MP4 đã hoàn tất.

Sử dụng endpoint này để tạo một tác vụ video HappyHorse. API trả về task ID ngay lập tức, vì vậy hãy lưu `id` được trả về và thăm dò tác vụ cho đến khi nó đạt trạng thái kết thúc.

`POST /v1/videos` sử dụng `multipart/form-data`; truyền các tham số điều khiển dạng vô hướng dưới dạng form field và các ảnh tham chiếu dưới dạng file field `input_reference`.

## Chọn một chế độ đầu vào

| Mục tiêu                     | Model                              | Trường bắt buộc                              | Trường tùy chọn                        |
| ---------------------------- | ---------------------------------- | -------------------------------------------- | -------------------------------------- |
| Từ văn bản sang video        | `happyhorse-1.0`, `happyhorse-1.1` | `model`, `prompt`                            | `seconds`, `size`                      |
| Từ ảnh tham chiếu sang video | `happyhorse-1.0`, `happyhorse-1.1` | `model`, `prompt`, một tệp `input_reference` | `seconds`, `size`, thêm ảnh tham chiếu |

Đối với chế độ từ ảnh tham chiếu sang video, hãy tải lên 1-9 ảnh tham chiếu bằng cách lặp lại trường multipart `input_reference`. CometAPI gửi từng tệp được tải lên dưới dạng ảnh tham chiếu HappyHorse. Sử dụng ảnh JPEG, JPG, PNG hoặc WEBP có dung lượng tối đa 20 MB mỗi ảnh; để có kết quả tốt hơn, hãy dùng ảnh có cạnh ngắn nhất ít nhất 400 px.

## Đặt thời lượng và kích thước

| Model ID         | `seconds`          | Mặc định              |
| ---------------- | ------------------ | --------------------- |
| `happyhorse-1.0` | số nguyên `3`-`15` | `5` giây, `1920x1080` |
| `happyhorse-1.1` | số nguyên `3`-`15` | `5` giây, `1920x1080` |

Đặt `size` thành giá trị `WxH` chính xác.

| Model            | Hình dạng khung hình | Giá trị `size`          |
| ---------------- | -------------------- | ----------------------- |
| `happyhorse-1.0` | Ngang                | `1280x720`, `1920x1080` |
|                  | Dọc                  | `720x1280`, `1080x1920` |
|                  | Vuông                | `1440x1440`             |
| `happyhorse-1.1` | Ngang                | `1280x720`, `1920x1080` |
|                  | Dọc                  | `720x1280`, `1080x1920` |
|                  | Vuông                | `1440x1440`             |
|                  | Ngang cổ điển        | `1440x1080`             |
|                  | Dọc cổ điển          | `720x960`, `1080x1440`  |
|                  | Ngang rộng           | `2520x1080`             |
|                  | Dọc rộng             | `1080x2520`             |
|                  | Ngang gần vuông      | `900x720`, `1350x1080`  |
|                  | Dọc gần vuông        | `720x900`, `1080x1350`  |

## Quy trình tác vụ

<Steps>
  <Step title="Tạo tác vụ">
    Gửi yêu cầu form multipart và lưu `id` được trả về.
  </Step>

  <Step title="Thăm dò tác vụ">
    Gọi [Truy xuất video HappyHorse](./retrieve) cho đến khi `status` là `completed`, `failed`, hoặc `error`.
  </Step>

  <Step title="Tải xuống kết quả">
    Khi tác vụ là `completed`, hãy gọi [Truy xuất nội dung video HappyHorse](./retrieve-content) để tải xuống tệp MP4.
  </Step>
</Steps>


## 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: <temporary-video-url>
        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.

````