> ## 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 MiniMax H3 video

> Create a MiniMax H3 text-to-video or reference-image video task through CometAPI with an exact WxH size.

Use this endpoint to create a MiniMax H3 video task. The API returns a task ID, so store the returned `id` for status and content requests.

`POST /v1/videos` uses `multipart/form-data`. Send scalar controls as form fields. Repeat the relevant image field when you use multiple reference images.

## Choose an input mode

| Goal                      | Required fields                                                   | Optional fields   |
| ------------------------- | ----------------------------------------------------------------- | ----------------- |
| Text-to-video             | `model=minimax-h3`, `prompt`                                      | `seconds`, `size` |
| URL reference images      | `model=minimax-h3`, `prompt`, one or more `images` fields         | `seconds`, `size` |
| Uploaded reference images | `model=minimax-h3`, `prompt`, one or more `input_reference` files | `seconds`, `size` |

## Use reference images

For HTTPS reference images, repeat the `images` multipart field. Each value must be a publicly accessible HTTPS image URL.

For uploaded reference images, repeat the `input_reference` multipart field. Upload PNG or JPEG files up to 20 MB each.

A request can contain up to nine reference images across the URL and file fields. Describe the visual details that the generated video should preserve.

## Set duration and size

Set `seconds` to an integer from `5` through `15`. The default is `5` seconds.

Set `size` to an exact `WxH` value. For predictable output dimensions, choose a canonical size from the table below. Other `WxH` values can be normalized to the nearest supported aspect ratio and size.

| Resolution | Aspect Ratio | Size        |
| ---------- | ------------ | ----------- |
| `768P`     | `21:9`       | `1536x672`  |
| `768P`     | `16:9`       | `1344x768`  |
| `768P`     | `4:3`        | `1024x768`  |
| `768P`     | `1:1`        | `768x768`   |
| `768P`     | `3:4`        | `768x1024`  |
| `768P`     | `9:16`       | `768x1344`  |
| `2K`       | `21:9`       | `2912x1280` |
| `2K`       | `16:9`       | `2560x1440` |
| `2K`       | `4:3`        | `1920x1440` |
| `2K`       | `1:1`        | `1440x1440` |
| `2K`       | `3:4`        | `1440x1920` |
| `2K`       | `9:16`       | `1440x2560` |

## Task flow

<Steps>
  <Step title="Create the task">
    Send the multipart form request and store the returned `id`.
  </Step>

  <Step title="Poll the task">
    Call [Retrieve a MiniMax H3 video](./retrieve) until `status` is `completed` or `failed`.
  </Step>

  <Step title="Download the result">
    When the task is `completed`, call [Download MiniMax H3 video content](./retrieve-content) to save the MP4 file.
  </Step>
</Steps>


## OpenAPI

````yaml api/openapi/video/minimax-h3/post-create.openapi.json POST /v1/videos
openapi: 3.1.0
info:
  title: MiniMax H3 Video Create API
  version: 1.0.0
  description: >-
    Create an asynchronous MiniMax H3 text-to-video or reference-image video
    task through CometAPI. Send the request as multipart/form-data, then use the
    returned id to retrieve the task and download its completed MP4 file.
servers:
  - url: https://api.cometapi.com
security:
  - bearerAuth: []
paths:
  /v1/videos:
    post:
      summary: Create a MiniMax H3 video task
      description: >-
        Create a MiniMax H3 video task from a text prompt, repeated HTTPS image
        URLs, or repeated uploaded image files. Use exact WxH values for size.
      operationId: minimax_h3_create_video
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/MiniMaxH3CreateRequest'
            encoding:
              images:
                style: form
                explode: true
              input_reference:
                contentType: image/png, image/jpeg
                style: form
                explode: true
            examples:
              text_2560x1440:
                summary: Text-to-video at 2560x1440
                value:
                  model: minimax-h3
                  prompt: >-
                    A paper boat glides across a still pond, daylight, locked
                    camera, no text.
                  seconds: 5
                  size: 2560x1440
              text_1344x768:
                summary: Text-to-video at 1344x768
                value:
                  model: minimax-h3
                  prompt: >-
                    A cinematic view of clouds moving over green mountains,
                    locked camera, no text.
                  seconds: 5
                  size: 1344x768
              url_reference_images:
                summary: HTTPS reference images at 1344x768
                value:
                  model: minimax-h3
                  prompt: >-
                    The referenced characters walk together through a city
                    street. Preserve their appearance and use natural motion. No
                    text.
                  seconds: 5
                  size: 1344x768
                  images:
                    - https://your-image-host/reference-1.png
                    - https://your-image-host/reference-2.png
              uploaded_reference_images:
                summary: Uploaded reference images
                value:
                  model: minimax-h3
                  prompt: >-
                    The uploaded reference characters walk together through a
                    city street. Preserve their appearance and use natural
                    motion. No text.
                  seconds: 5
                  size: 2560x1440
                  input_reference:
                    - '@/path/to/reference-1.png'
                    - '@/path/to/reference-2.jpg'
      responses:
        '200':
          description: >-
            Task created. Store the returned id and use it in retrieve and
            content requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiniMaxH3VideoTask'
              example:
                id: <task_id>
                task_id: <task_id>
                object: video
                model: minimax-h3
                status: queued
                progress: 0
                created_at: 1779938152
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: Shell
          label: Text-to-video at 2560x1440
          source: |-
            curl https://api.cometapi.com/v1/videos \
              -H "Authorization: Bearer $COMETAPI_KEY" \
              --form-string 'model=minimax-h3' \
              --form-string 'prompt=A paper boat glides across a still pond, daylight, locked camera, no text.' \
              --form-string 'seconds=5' \
              --form-string 'size=2560x1440'
        - lang: Python
          label: Text-to-video at 2560x1440
          source: |
            import os

            import requests

            fields = [
                ("model", (None, "minimax-h3")),
                (
                    "prompt",
                    (
                        None,
                        "A paper boat glides across a still pond, daylight, "
                        "locked camera, no text.",
                    ),
                ),
                ("seconds", (None, "5")),
                ("size", (None, "2560x1440")),
            ]

            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: Text-to-video at 2560x1440
          source: |
            const form = new FormData();
            form.append("model", "minimax-h3");
            form.append(
              "prompt",
              "A paper boat glides across a still pond, daylight, " +
                "locked camera, no text.",
            );
            form.append("seconds", "5");
            form.append("size", "2560x1440");

            const response = await fetch("https://api.cometapi.com/v1/videos", {
              method: "POST",
              headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },
              body: form,
            });

            if (!response.ok) {
              throw new Error(await response.text());
            }

            console.log(await response.json());
        - lang: Shell
          label: Text-to-video at 1344x768
          source: |-
            curl https://api.cometapi.com/v1/videos \
              -H "Authorization: Bearer $COMETAPI_KEY" \
              --form-string 'model=minimax-h3' \
              --form-string 'prompt=A cinematic view of clouds moving over green mountains, locked camera, no text.' \
              --form-string 'seconds=5' \
              --form-string 'size=1344x768'
        - lang: Python
          label: Text-to-video at 1344x768
          source: |
            import os

            import requests

            fields = [
                ("model", (None, "minimax-h3")),
                (
                    "prompt",
                    (
                        None,
                        "A cinematic view of clouds moving over green mountains, "
                        "locked camera, no text.",
                    ),
                ),
                ("seconds", (None, "5")),
                ("size", (None, "1344x768")),
            ]

            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: Text-to-video at 1344x768
          source: |
            const form = new FormData();
            form.append("model", "minimax-h3");
            form.append(
              "prompt",
              "A cinematic view of clouds moving over green mountains, " +
                "locked camera, no text.",
            );
            form.append("seconds", "5");
            form.append("size", "1344x768");

            const response = await fetch("https://api.cometapi.com/v1/videos", {
              method: "POST",
              headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },
              body: form,
            });

            if (!response.ok) {
              throw new Error(await response.text());
            }

            console.log(await response.json());
        - lang: Shell
          label: HTTPS reference images
          source: |-
            curl https://api.cometapi.com/v1/videos \
              -H "Authorization: Bearer $COMETAPI_KEY" \
              --form-string 'model=minimax-h3' \
              --form-string 'prompt=The referenced characters walk together through a city street. Preserve their appearance and use natural motion. No text.' \
              --form-string 'seconds=5' \
              --form-string 'size=1344x768' \
              --form-string 'images=https://your-image-host/reference-1.png' \
              --form-string 'images=https://your-image-host/reference-2.png'
        - lang: Python
          label: HTTPS reference images
          source: |
            import os

            import requests

            prompt = (
                "The referenced characters walk together through a city street. "
                "Preserve their appearance and use natural motion. No text."
            )
            fields = [
                ("model", (None, "minimax-h3")),
                ("prompt", (None, prompt)),
                ("seconds", (None, "5")),
                ("size", (None, "1344x768")),
                (
                    "images",
                    (None, "https://your-image-host/reference-1.png"),
                ),
                (
                    "images",
                    (None, "https://your-image-host/reference-2.png"),
                ),
            ]

            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: HTTPS reference images
          source: |
            const form = new FormData();
            form.append("model", "minimax-h3");
            form.append(
              "prompt",
              "The referenced characters walk together through a city street. " +
                "Preserve their appearance and use natural motion. No text.",
            );
            form.append("seconds", "5");
            form.append("size", "1344x768");
            form.append("images", "https://your-image-host/reference-1.png");
            form.append("images", "https://your-image-host/reference-2.png");

            const response = await fetch("https://api.cometapi.com/v1/videos", {
              method: "POST",
              headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },
              body: form,
            });

            if (!response.ok) {
              throw new Error(await response.text());
            }

            console.log(await response.json());
        - lang: Shell
          label: Uploaded reference images
          source: |-
            curl https://api.cometapi.com/v1/videos \
              -H "Authorization: Bearer $COMETAPI_KEY" \
              --form-string 'model=minimax-h3' \
              --form-string 'prompt=The uploaded reference characters walk together through a city street. Preserve their appearance and use natural motion. No text.' \
              --form-string 'seconds=5' \
              --form-string 'size=2560x1440' \
              --form 'input_reference=@/path/to/reference-1.png;type=image/png' \
              --form 'input_reference=@/path/to/reference-2.jpg;type=image/jpeg'
        - lang: Python
          label: Uploaded reference images
          source: |
            import os
            from contextlib import ExitStack

            import requests

            prompt = (
                "The uploaded reference characters walk together through a city street. "
                "Preserve their appearance and use natural motion. No text."
            )

            with ExitStack() as stack:
                files = [
                    (
                        "input_reference",
                        (
                            "reference-1.png",
                            stack.enter_context(
                                open("/path/to/reference-1.png", "rb")
                            ),
                            "image/png",
                        ),
                    ),
                    (
                        "input_reference",
                        (
                            "reference-2.jpg",
                            stack.enter_context(
                                open("/path/to/reference-2.jpg", "rb")
                            ),
                            "image/jpeg",
                        ),
                    ),
                ]
                response = requests.post(
                    "https://api.cometapi.com/v1/videos",
                    headers={
                        "Authorization": "Bearer "
                        + os.environ["COMETAPI_KEY"]
                    },
                    data={
                        "model": "minimax-h3",
                        "prompt": prompt,
                        "seconds": "5",
                        "size": "2560x1440",
                    },
                    files=files,
                    timeout=120,
                )

            response.raise_for_status()
            print(response.json())
        - lang: JavaScript
          label: Uploaded reference images
          source: |
            import { readFile } from "node:fs/promises";

            const firstReference = await readFile("/path/to/reference-1.png");
            const secondReference = await readFile("/path/to/reference-2.jpg");

            const form = new FormData();
            form.append("model", "minimax-h3");
            form.append(
              "prompt",
              "The uploaded reference characters walk together through a city street. " +
                "Preserve their appearance and use natural motion. No text.",
            );
            form.append("seconds", "5");
            form.append("size", "2560x1440");
            form.append(
              "input_reference",
              new Blob([firstReference], { type: "image/png" }),
              "reference-1.png",
            );
            form.append(
              "input_reference",
              new Blob([secondReference], { type: "image/jpeg" }),
              "reference-2.jpg",
            );

            const response = await fetch("https://api.cometapi.com/v1/videos", {
              method: "POST",
              headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },
              body: form,
            });

            if (!response.ok) {
              throw new Error(await response.text());
            }

            console.log(await response.json());
components:
  schemas:
    MiniMaxH3CreateRequest:
      type: object
      required:
        - model
        - prompt
      properties:
        model:
          type: string
          const: minimax-h3
          default: minimax-h3
          description: Model ID for this route. Use minimax-h3.
        prompt:
          type: string
          minLength: 1
          description: >-
            Text that describes the scene, motion, camera behavior, and visual
            details that the video should preserve.
          default: >-
            A paper boat glides across a still pond, daylight, locked camera, no
            text.
        seconds:
          type: integer
          minimum: 5
          maximum: 15
          default: 5
          description: >-
            Requested clip duration in whole seconds. Use an integer from 5
            through 15. The default is 5.
        size:
          type: string
          pattern: ^[1-9][0-9]*x[1-9][0-9]*$
          default: 2560x1440
          examples:
            - 1536x672
            - 1344x768
            - 1024x768
            - 768x768
            - 768x1024
            - 768x1344
            - 2912x1280
            - 2560x1440
            - 1920x1440
            - 1440x1440
            - 1440x1920
            - 1440x2560
          description: >-
            Requested frame size in exact WxH form. For predictable output
            dimensions, use one of the documented canonical sizes. Other WxH
            inputs can be normalized to the nearest supported aspect ratio and
            size.
        images:
          type: array
          minItems: 1
          maxItems: 9
          items:
            type: string
            format: uri
            pattern: ^https://
            example: https://your-image-host/reference-1.png
          description: >-
            Publicly accessible HTTPS reference image URLs. Repeat the images
            multipart field for each URL. A request can contain up to nine
            reference images across images and input_reference.
        input_reference:
          type: array
          minItems: 1
          maxItems: 9
          items:
            type: string
            format: binary
          description: >-
            PNG or JPEG reference image files. Repeat the input_reference
            multipart field for each file. Each file can be up to 20 MB. A
            request can contain up to nine reference images across
            input_reference and images.
      additionalProperties: false
    MiniMaxH3VideoTask:
      type: object
      required:
        - id
        - object
        - model
        - status
        - progress
        - created_at
      properties:
        id:
          type: string
          description: Task ID. Use this value as task_id in retrieve and content requests.
          example: <task_id>
        task_id:
          type: string
          description: >-
            Compatibility alias for id. This field can be omitted from retrieve
            responses.
          example: <task_id>
        object:
          type: string
          const: video
          description: Object type for the asynchronous video task.
        model:
          type: string
          const: minimax-h3
          description: Model ID that the task uses.
        status:
          type: string
          enum:
            - queued
            - in_progress
            - completed
            - failed
          description: Task lifecycle status. Poll until the value is completed or failed.
        progress:
          type: integer
          minimum: 0
          maximum: 100
          description: Task progress as a coarse percentage.
        created_at:
          type: integer
          format: int64
          description: Task creation time as a Unix timestamp in seconds.
        completed_at:
          type: integer
          format: int64
          description: >-
            Unix timestamp returned by the platform. Use status, not this field,
            to decide when polling can stop.
        expires_at:
          type: integer
          format: int64
          description: >-
            Result expiration time as a Unix timestamp in seconds when the task
            provides one.
        video_url:
          type: string
          format: uri
          description: Video delivery URL. This field appears on completed tasks.
          example: https://<provider-cdn>/<video_id>.mp4
        error:
          type: object
          description: Failure details. This field appears when the task fails.
          properties:
            message:
              type: string
              description: Human-readable failure description.
            code:
              type: string
              description: Failure code when the task provides one.
          additionalProperties: true
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication. Use your CometAPI API key.

````