> ## 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
> Create a beta Omni video task through CometAPI with POST /v1/videos, then poll the task and download the completed MP4 file.
Use this beta endpoint to create an Omni video task. The API returns a task ID immediately, so store the returned `id` and poll the task until it reaches a terminal status.
Beta
`POST /v1/videos` uses `multipart/form-data`; pass scalar controls as form fields.
## Choose an input mode
| Goal | Required fields | Optional fields |
| ------------- | ----------------- | --------------------------------------- |
| Text-to-video | `model`, `prompt` | `seconds`, `aspect_ratio`, `resolution` |
Use `model=omni-fast` for this page.
## 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` | `4` | Use short clips first while this endpoint is beta. |
| `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
Send the multipart form request and store the returned `id`.
Call [Retrieve an Omni video](./retrieve) until `status` is `completed` or `failed`.
When the task is `completed`, call [Retrieve Omni video content](./retrieve-content) to download the MP4 file.
## 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 video 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 task. Send request controls as
multipart/form-data fields.
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
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
'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: 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);
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.
enum:
- omni-fast
example: omni-fast
prompt:
type: string
description: Text prompt that describes the video to generate.
example: Ocean waves rolling onto a sandy beach at golden hour
seconds:
type: string
description: >-
Requested clip duration in seconds. Start with 4 while this endpoint
is beta.
default: '4'
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:
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 accepted or the task fails.
type: object
additionalProperties: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer authentication. Use your CometAPI API key.
````