> ## 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.
# Criar um vídeo Omni
> Crie uma tarefa beta de texto para vídeo ou de edição de vídeo de referência do Omni pelo CometAPI com POST /v1/videos, depois consulte a tarefa e baixe o arquivo MP4 concluído.
Use este endpoint beta para criar uma tarefa de texto para vídeo ou de vídeo para vídeo. A API retorna um ID de tarefa imediatamente, portanto armazene o `id` retornado e consulte a tarefa até que ela alcance um status terminal.
Escolha o tipo de conteúdo da solicitação que corresponde ao modo de entrada. Envie controles de texto para vídeo como campos `multipart/form-data`. Envie uma edição de vídeo de referência como um corpo `application/json`.
## Escolha um modo de entrada
| Objetivo | Tipo de conteúdo | Campos obrigatórios | Campos opcionais |
| ---------------- | --------------------- | -------------------------- | --------------------------------------- |
| Texto para vídeo | `multipart/form-data` | `model`, `prompt` | `seconds`, `aspect_ratio`, `resolution` |
| Vídeo para vídeo | `application/json` | `model`, `prompt`, `video` | `seconds`, `aspect_ratio`, `resolution` |
Os exemplos de texto para vídeo usam `model=omni-fast`. Os exemplos de vídeo para vídeo usam `model=omni-fast-v2v`. Use [Listar modelos disponíveis](/pt/guides/how-to-list-available-models) para confirmar que um ID de modelo está visível para sua chave de API.
## Editar um vídeo de referência
Para vídeo para vídeo, codifique um arquivo MP4 local como base64 e prefixe os bytes codificados com `data:video/mp4;base64,`. Envie o URL de dados completo no campo `video`.
Descreva as alterações solicitadas em `prompt`. Nomeie também os sujeitos, objetos, composição ou movimento que o resultado deve preservar. O seletor de exemplos de código inclui exemplos em Shell, Python e JavaScript que leem `reference.mp4` do diretório de trabalho.
Esse formato de solicitação abrange um URL de dados MP4 embutido. Ele não define entrada por URL, outros formatos de contêiner de vídeo ou limites de tamanho de arquivo.
## Definir duração, proporção e resolução
O Omni é marcado como beta porque a estabilidade da geração pode variar conforme a entrada e a rota selecionada. Mantenha a primeira solicitação pequena e inspecione o vídeo concluído antes de depender de uma duração renderizada ou tamanho de quadro específico.
| Configuração | Valores compatíveis | Padrão | Comportamento nos limites |
| -------------- | ------------------------------------------ | ------------------ | --------------------------------------------------------------------------------------------------------------- |
| `seconds` | Comece com `4` | Dependente da rota | Trate isto como uma duração solicitada e verifique o MP4 concluído, pois a duração de saída pode ser diferente. |
| `aspect_ratio` | `16:9`, `9:16`, `1:1` | `16:9` | `9:16` pode renderizar saída em retrato. `1:1` pode ser aceito durante a renderização em paisagem. |
| `resolution` | Comece com `720p`; `1080p` pode ser aceito | `720p` | A saída de produção atual pode ser normalizada para `720p` mesmo quando `1080p` for solicitado. |
| Solicitação | Quadro concluído observado |
| --------------------------------------- | -------------------------- |
| `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` |
Como este endpoint é beta, trate `aspect_ratio` e `resolution` como preferências de geração e verifique o MP4 baixado antes de depender dos pixels finais.
## Fluxo da tarefa
Envie a solicitação com o tipo de conteúdo correspondente ao modo de entrada selecionado e armazene o `id` retornado.
Chame [Recuperar um vídeo Omni](./retrieve) até que `status` seja `completed` ou `failed`.
Quando a tarefa estiver `completed`, chame [Recuperar conteúdo de vídeo Omni](./retrieve-content) para baixar o arquivo MP4.
## 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 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 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
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,
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: Video-to-video
source: |-
VIDEO_B64=$(openssl base64 -A -in reference.mp4)
EDIT_PROMPT="Change the background to ocean blue."
EDIT_PROMPT="$EDIT_PROMPT Preserve every foreground object"
EDIT_PROMPT="$EDIT_PROMPT and its motion."
curl "https://api.cometapi.com/v1/videos" \
--request POST \
--header "Authorization: Bearer $COMETAPI_KEY" \
--header "Content-Type: application/json" \
--data-binary @- <
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.
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. 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,
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:
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.
````