> ## 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 an Omni video from text, image, or video

> Create a beta Omni text-to-video, image-to-video, or reference-video editing task through CometAPI with POST /v1/videos, then poll the task and download the completed MP4 file.

Use this beta endpoint to create a text-to-video, image-to-video, or video-to-video task. The API returns a task ID immediately, so store the returned `id` and poll the task until it reaches a terminal status.

Choose the request content type that matches the input mode. Send text-to-video and image-to-video controls as `multipart/form-data` fields. Send a reference-video edit as an `application/json` body.

## Choose an input mode

| Goal           | Content type          | Required fields                      | Optional fields                         |
| -------------- | --------------------- | ------------------------------------ | --------------------------------------- |
| Text-to-video  | `multipart/form-data` | `model`, `prompt`                    | `seconds`, `aspect_ratio`, `resolution` |
| Image-to-video | `multipart/form-data` | `model`, `prompt`, `input_reference` | `seconds`, `aspect_ratio`, `resolution` |
| Video-to-video | `application/json`    | `model`, `prompt`, `video`           | `seconds`, `aspect_ratio`, `resolution` |

The text-to-video and image-to-video examples use `model=omni-fast`. The video-to-video examples use `model=omni-fast-v2v`. Use [List available models](/guides/how-to-list-available-models) to confirm that a model ID is visible to your API key.

## Animate a reference image

For image-to-video, use `model=omni-fast` and upload one PNG file in the multipart `input_reference` field. The field remains optional for text-to-video, but it is required when a reference image should drive the generated video.

Focus the `prompt` on the motion to add and explicitly name the colors, shapes, subjects, or composition that the result should preserve. The code sample selector includes Shell, Python, and JavaScript examples that upload `reference.png` from the working directory and create the task.

This request shape covers one uploaded PNG. It does not define URL input, other image formats, multiple reference images, or file-size limits.

## Edit a reference video

For video-to-video, encode a local MP4 file as base64 and prefix the encoded bytes with `data:video/mp4;base64,`. Send the complete data URL in the `video` field.

Describe the requested changes in `prompt`. Also name the subjects, objects, composition, or motion that the result should preserve. The code sample selector includes Shell, Python, and JavaScript examples that read `reference.mp4` from the working directory.

This request shape covers an inline MP4 data URL. It does not define URL input, other video container formats, or file-size limits.

## Set duration, ratio, and resolution

Omni is marked beta because generation stability can vary by input and selected route. Keep the first request small, then inspect the completed video before relying on a specific rendered duration or frame size.

| Setting        | Supported values                           | Default         | Boundary behavior                                                                                       |
| -------------- | ------------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------- |
| `seconds`      | Start with `4`                             | Route-dependent | Treat this as a requested duration and verify the completed MP4 because the output duration can differ. |
| `aspect_ratio` | `16:9`, `9:16`, `1:1`                      | `16:9`          | `9:16` can render portrait output. `1:1` can be accepted while rendering as landscape.                  |
| `resolution`   | Start with `720p`; `1080p` can be accepted | `720p`          | Current production output can normalize to `720p` even when `1080p` is requested.                       |

| Request                                 | Observed completed frame |
| --------------------------------------- | ------------------------ |
| `resolution=720p`, `aspect_ratio=16:9`  | `1280x720`               |
| `resolution=720p`, `aspect_ratio=9:16`  | `720x1280`               |
| `resolution=720p`, `aspect_ratio=1:1`   | `1280x720`               |
| `resolution=1080p`, `aspect_ratio=16:9` | `1280x720`               |

Because this endpoint is beta, treat `aspect_ratio` and `resolution` as generation preferences and verify the downloaded MP4 before depending on final pixels.

## Task flow

<Steps>
  <Step title="Create the task">
    Send the request with the content type for the selected input mode and store the returned `id`.
  </Step>

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

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


## OpenAPI

````yaml api/openapi/video/omni/post-create.openapi.json POST /v1/videos
openapi: 3.1.0
info:
  title: Omni Video Create API
  version: 1.0.0
  description: >-
    Create an asynchronous beta Omni text-to-video, image-to-video, or
    reference-video editing task through CometAPI. 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 an Omni video task
      description: >-
        Create a beta Omni text-to-video or image-to-video task with
        multipart/form-data, or a reference-video editing task with
        application/json.
      operationId: omni_create_video
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OmniCreateRequest'
            examples:
              text_to_video:
                summary: Text-to-video
                value:
                  model: omni-fast
                  prompt: Ocean waves rolling onto a sandy beach at golden hour
                  seconds: '4'
                  aspect_ratio: '16:9'
                  resolution: 720p
              image_to_video:
                summary: Image-to-video with one PNG reference
                value:
                  model: omni-fast
                  prompt: >-
                    Animate the uploaded reference image with gentle movement
                    while preserving its colors, shapes, and layout.
                  seconds: '4'
                  aspect_ratio: '16:9'
                  resolution: 720p
                  input_reference: <binary PNG file>
          application/json:
            schema:
              $ref: '#/components/schemas/OmniVideoEditRequest'
            examples:
              video_to_video:
                summary: Video-to-video with an inline MP4
                value:
                  model: omni-fast-v2v
                  prompt: >-
                    Change the background to ocean blue. Preserve every
                    foreground object and its motion.
                  video: data:video/mp4;base64,<your-video-base64>
                  seconds: '4'
                  aspect_ratio: '16:9'
                  resolution: 720p
      responses:
        '200':
          description: >-
            Task accepted. Store the returned id and poll GET
            /v1/videos/{task_id}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OmniVideoTask'
              example:
                id: task_example
                task_id: task_example
                object: video
                model: omni-fast
                status: queued
                progress: 0
                created_at: 1779938152
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: Shell
          label: Text-to-video
          source: |-
            curl https://api.cometapi.com/v1/videos \
              -H "Authorization: Bearer $COMETAPI_KEY" \
              -F model=omni-fast \
              -F 'prompt=Ocean waves rolling onto a sandy beach at golden hour' \
              -F seconds=4 \
              -F aspect_ratio=16:9 \
              -F resolution=720p
        - lang: Python
          label: Text-to-video
          source: |
            import os
            import requests

            fields = [
                ("model", (None, "omni-fast")),
                ("prompt", (None, "Ocean waves rolling onto a sandy beach at golden hour")),
                ("seconds", (None, "4")),
                ("aspect_ratio", (None, "16:9")),
                ("resolution", (None, "720p")),
            ]

            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
          source: >
            const form = new FormData();

            form.append("model", "omni-fast");

            form.append("prompt", "Ocean waves rolling onto a sandy beach at
            golden hour");

            form.append("seconds", "4");

            form.append("aspect_ratio", "16:9");

            form.append("resolution", "720p");


            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: Image-to-video
          source: |-
            curl https://api.cometapi.com/v1/videos \
              -H "Authorization: Bearer $COMETAPI_KEY" \
              -F model=omni-fast \
              -F 'prompt=Animate the uploaded reference image with gentle movement while preserving its colors, shapes, and layout.' \
              -F seconds=4 \
              -F aspect_ratio=16:9 \
              -F resolution=720p \
              -F 'input_reference=@reference.png;type=image/png'
        - lang: Python
          label: Image-to-video
          source: |
            import os
            from pathlib import Path

            import requests

            with Path("reference.png").open("rb") as reference:
                fields = [
                    ("model", (None, "omni-fast")),
                    ("prompt", (None, "Animate the uploaded reference image with gentle movement while preserving its colors, shapes, and layout.")),
                    ("seconds", (None, "4")),
                    ("aspect_ratio", (None, "16:9")),
                    ("resolution", (None, "720p")),
                    ("input_reference", ("reference.png", reference, "image/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: Image-to-video
          source: >
            import { readFile } from "node:fs/promises";


            const reference = await readFile("reference.png");

            const form = new FormData();

            form.append("model", "omni-fast");

            form.append("prompt", "Animate the uploaded reference image with
            gentle movement while preserving its colors, shapes, and layout.");

            form.append("seconds", "4");

            form.append("aspect_ratio", "16:9");

            form.append("resolution", "720p");

            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: Video-to-video
          source: |-
            curl "https://api.cometapi.com/v1/videos" \
              --request POST \
              --header "Authorization: Bearer $COMETAPI_KEY" \
              --header "Content-Type: application/json" \
              --data-binary @- <<'JSON'
            {
              "model": "omni-fast-v2v",
              "prompt": "Change the background to ocean blue. Preserve every foreground object and its motion.",
              "video": "data:video/mp4;base64,<base64-encoded-mp4>",
              "seconds": "4",
              "aspect_ratio": "16:9",
              "resolution": "720p"
            }
            JSON
        - lang: Python
          label: Video-to-video
          source: >
            import base64

            import os

            from pathlib import Path


            import requests


            video_data =
            base64.b64encode(Path("reference.mp4").read_bytes()).decode("ascii")


            response = requests.post(
                "https://api.cometapi.com/v1/videos",
                headers={
                    "Authorization": "Bearer " + os.environ["COMETAPI_KEY"],
                    "Content-Type": "application/json",
                },
                json={
                    "model": "omni-fast-v2v",
                    "prompt": "Change the background to ocean blue. Preserve every foreground object and its motion.",
                    "video": "data:video/mp4;base64," + video_data,
                    "seconds": "4",
                    "aspect_ratio": "16:9",
                    "resolution": "720p",
                },
                timeout=120,
            )


            response.raise_for_status()

            print(response.json())
        - lang: JavaScript
          label: Video-to-video
          source: >
            import { readFile } from "node:fs/promises";


            const videoData = (await
            readFile("reference.mp4")).toString("base64");


            const response = await fetch("https://api.cometapi.com/v1/videos", {
              method: "POST",
              headers: {
                Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
                "Content-Type": "application/json",
              },
              body: JSON.stringify({
                model: "omni-fast-v2v",
                prompt: "Change the background to ocean blue. Preserve every foreground object and its motion.",
                video: `data:video/mp4;base64,${videoData}`,
                seconds: "4",
                aspect_ratio: "16:9",
                resolution: "720p",
              }),
            });


            const result = await response.json();

            console.log(result);
components:
  schemas:
    OmniCreateRequest:
      type: object
      required:
        - model
        - prompt
      properties:
        model:
          type: string
          description: >-
            Omni model ID for this endpoint. Use omni-fast for text-to-video and
            image-to-video.
          example: omni-fast
        prompt:
          type: string
          description: >-
            Text prompt that describes the video to generate. For
            image-to-video, focus on motion and name the reference content that
            should be preserved.
          example: Ocean waves rolling onto a sandy beach at golden hour
        input_reference:
          type: string
          format: binary
          description: >-
            One PNG reference image uploaded as a multipart file. Optional for
            text-to-video and required for image-to-video. This contract does
            not define URL input, other image formats, multiple references, or a
            file-size limit.
        seconds:
          type: string
          description: >-
            Requested clip duration in seconds. The completed video can use a
            different duration.
          example: '4'
        aspect_ratio:
          type: string
          description: >-
            Output aspect ratio preference. 16:9 and 9:16 are the most
            predictable; 1:1 can be accepted but may render as landscape.
          enum:
            - '16:9'
            - '9:16'
            - '1:1'
          default: '16:9'
          example: '16:9'
        resolution:
          type: string
          description: >-
            Output resolution preference. Start with 720p. A request for 1080p
            can render at 720p.
          example: 720p
      additionalProperties: false
    OmniVideoEditRequest:
      type: object
      required:
        - model
        - prompt
        - video
      properties:
        model:
          type: string
          description: >-
            Omni model ID for video-to-video. Confirm that the model ID is
            visible to your API key with GET /v1/models.
          example: omni-fast-v2v
        prompt:
          type: string
          description: >-
            Text instructions that describe the requested edit and the source
            content that the result should preserve.
          example: >-
            Change the background to ocean blue. Preserve every foreground
            object and its motion.
        video:
          type: string
          description: >-
            Reference MP4 as a data URL. Prefix the MP4 file bytes encoded as
            base64 with data:video/mp4;base64,. This field determines the source
            video to edit.
          example: data:video/mp4;base64,<your-video-base64>
        seconds:
          type: string
          description: >-
            Requested clip duration in seconds. Start with 4 for an inline MP4
            edit.
          example: '4'
        aspect_ratio:
          type: string
          description: >-
            Output aspect ratio preference. 16:9 and 9:16 are the most
            predictable; 1:1 can be accepted but may render as landscape.
          enum:
            - '16:9'
            - '9:16'
            - '1:1'
          default: '16:9'
          example: '16:9'
        resolution:
          type: string
          description: >-
            Output resolution preference. Start with 720p. 1080p can be accepted
            but current production output may normalize to 720p.
          example: 720p
      additionalProperties: false
    OmniVideoTask:
      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: omni-fast
        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.
          properties:
            code:
              type: string
              description: Provider or CometAPI error code.
            message:
              type: string
              description: Human-readable failure reason.
            type:
              type: string
              description: Error category when returned.
          additionalProperties: true
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication. Use your CometAPI API key.

````