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

# 创建 Omni 视频

> 通过 POST /v1/videos 使用 CometAPI 创建 Beta 版 Omni 文本转视频或参考视频编辑任务，然后轮询任务并下载完成的 MP4 文件。

使用此 Beta 端点创建文本转视频或视频转视频任务。API 会立即返回任务 ID，因此请存储返回的 `id`，并轮询任务，直到其达到终止状态。

选择与输入模式匹配的请求内容类型。将文本转视频控件作为 `multipart/form-data` 字段发送。将参考视频编辑作为 `application/json` 请求体发送。

## 选择输入模式

| 目标    | 内容类型                  | 必填字段                       | 可选字段                                    |
| ----- | --------------------- | -------------------------- | --------------------------------------- |
| 文本转视频 | `multipart/form-data` | `model`, `prompt`          | `seconds`, `aspect_ratio`, `resolution` |
| 视频转视频 | `application/json`    | `model`, `prompt`, `video` | `seconds`, `aspect_ratio`, `resolution` |

文本转视频示例使用 `model=omni-fast`。视频转视频示例使用 `model=omni-fast-v2v`。使用 [列出可用模型](/zh-Hans/guides/how-to-list-available-models) 以确认模型 ID 对您的 API 密钥可见。

## 编辑参考视频

对于视频转视频，请将本地 MP4 文件编码为 base64，并在编码后的字节前添加 `data:video/mp4;base64,` 前缀。在 `video` 字段中发送完整的数据 URL。

在 `prompt` 中描述请求的更改。还请说明结果应保留的主体、对象、构图或运动。代码示例选择器包含 Shell、Python 和 JavaScript 示例，这些示例从工作目录读取 `reference.mp4`。

此请求结构涵盖内联 MP4 数据 URL。它不定义 URL 输入、其他视频容器格式或文件大小限制。

## 设置时长、比例和分辨率

Omni 被标记为 Beta 版，因为生成稳定性可能因输入和所选路由而异。请保持首次请求较小，然后检查完成的视频，再依赖特定的渲染时长或帧尺寸。

| 设置             | 支持的值                     | 默认值    | 边界行为                                   |
| -------------- | ------------------------ | ------ | -------------------------------------- |
| `seconds`      | 从 `4`                    | 取决于路由  | 将其视为请求的时长，并验证完成的 MP4，因为输出时长可能不同。       |
| `aspect_ratio` | `16:9`, `9:16`, `1:1`    | `16:9` | `9:16` 可以渲染为纵向输出。`1:1` 可以在渲染为横向输出时被接受。 |
| `resolution`   | 从 `720p` 开始；可以接受 `1080p` | `720p` | 即使请求了 `720p`，当前生产输出也可能标准化为 `1080p`。    |

| 请求                                      | 观察到的完成帧    |
| --------------------------------------- | ---------- |
| `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` |

由于此端点处于 Beta 阶段，请将 `aspect_ratio` 和 `resolution` 视为生成偏好，并在依赖最终像素前验证下载的 MP4。

## 任务流程

<Steps>
  <Step title="创建任务">
    使用所选输入模式对应的内容类型发送请求，并存储返回的 `id`。
  </Step>

  <Step title="轮询任务">
    调用 [检索 Omni 视频](./retrieve) 直到 `status` 为 `completed` 或 `failed`。
  </Step>

  <Step title="下载结果">
    当任务为 `completed` 时，调用 [检索 Omni 视频内容](./retrieve-content) 以下载 MP4 文件。
  </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 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,<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: 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 @- <<JSON
            {
              "model": "omni-fast-v2v",
              "prompt": "$EDIT_PROMPT",
              "video": "data:video/mp4;base64,$VIDEO_B64",
              "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.
          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,<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.

````