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

> أنشئ مهمة فيديو HappyHorse من النص إلى الفيديو أو باستخدام صورة مرجعية عبر CometAPI باستخدام POST /v1/videos، ثم استعلم عن المهمة بشكل متكرر ونزّل ملف MP4 المكتمل.

استخدم نقطة النهاية هذه لإنشاء مهمة فيديو HappyHorse. تعيد واجهة API معرّف المهمة فورًا، لذا خزّن قيمة `id` المُعادة واستعلم عن المهمة بشكل متكرر حتى تصل إلى حالة نهائية.

يستخدم `POST /v1/videos` النوع `multipart/form-data`؛ مرّر عناصر التحكم القيمية كحقول form والصور المرجعية كحقول ملفات `input_reference`.

## اختر وضع الإدخال

| الهدف                 | الموديل                            | الحقول المطلوبة                               | الحقول الاختيارية                           |
| --------------------- | ---------------------------------- | --------------------------------------------- | ------------------------------------------- |
| من النص إلى الفيديو   | `happyhorse-1.0`, `happyhorse-1.1` | `model`, `prompt`                             | `seconds`, `size`                           |
| من المرجع إلى الفيديو | `happyhorse-1.0`, `happyhorse-1.1` | `model`, `prompt`, ملف `input_reference` واحد | `seconds`, `size`, المزيد من الصور المرجعية |

في وضع من المرجع إلى الفيديو، ارفع من 1 إلى 9 صور مرجعية عبر تكرار حقل multipart `input_reference`. ترسل CometAPI كل ملف مرفوع كصورة مرجعية لـ HappyHorse. استخدم صور JPEG أو JPG أو PNG أو WEBP بحجم يصل إلى 20 ميجابايت لكل صورة؛ ولأفضل النتائج، استخدم صورًا يكون أقصر ضلع فيها 400 px على الأقل.

## اضبط المدة والحجم

| Model ID         | `seconds`                | الافتراضي              |
| ---------------- | ------------------------ | ---------------------- |
| `happyhorse-1.0` | عدد صحيح من `3` إلى `15` | `5` ثوانٍ، `1920x1080` |
| `happyhorse-1.1` | عدد صحيح من `3` إلى `15` | `5` ثوانٍ، `1920x1080` |

اضبط `size` على قيمة `WxH` دقيقة.

| الموديل          | شكل الإطار     | قيم `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`  |

## سير المهمة

<Steps>
  <Step title="إنشاء المهمة">
    أرسل طلب multipart form وخزّن قيمة `id` المُعادة.
  </Step>

  <Step title="الاستعلام عن المهمة">
    استدعِ [استرجاع فيديو HappyHorse](./retrieve) حتى تصبح قيمة `status` هي `completed` أو `failed` أو `error`.
  </Step>

  <Step title="تنزيل النتيجة">
    عندما تكون المهمة في حالة `completed`، استدعِ [استرجاع محتوى فيديو HappyHorse](./retrieve-content) لتنزيل ملف 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.

````