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

# 创建一个 Sora 2 视频

> 使用 POST /v1/videos 从文本 Prompt 或参考图片创建 Sora 2 视频生成任务，然后通过任务 ID 轮询状态以获取结果。

使用此端点可以从文本，或从文本加一张参考图片，启动一个 Sora 渲染任务。API 会立即返回一个 video id，而不会等待渲染完成。

## 从最小可用任务开始

* 使用 `sora-2` 以更快地迭代，或者在输出质量比速度更重要时使用 `sora-2-pro`
* 首次请求时将 `seconds` 保持为 `4`
* 除非你明确需要竖屏输出，否则从 `size: 1280x720` 开始
* 最多上传一张参考图片

## 时长和尺寸

| 设置                      | 支持的值                                   | 默认起始点                   | 边界行为                    |
| ----------------------- | -------------------------------------- | ----------------------- | ----------------------- |
| `seconds`               | `4`, `8`, `12`, `16`, `20`             | `4`                     | 其他值不属于 Sora 视频请求的参数结构。  |
| `size` for `sora-2`     | `1280x720`, `720x1280`                 | `1280x720`              | 使用横屏或竖屏方向。              |
| `size` for `sora-2-pro` | `1792x1024`, `1024x1792`, 以及标准 Sora 尺寸 | 横屏 Pro 输出使用 `1792x1024` | 仅在 Pro 模型中使用更大的 Pro 尺寸。 |

Sora 要求 `size` 字段必须采用精确的 `WxH` 形式。像 `720p` 这样的分辨率标记以及像 `16:9` 这样的比例标签，在此端点上都不是有效的 Sora `size` 值。

## 端到端流程

<Steps>
  <Step title="创建渲染任务">
    发送 `model`、`prompt`、`seconds` 和 `size`，然后保存返回的 `id`。
  </Step>

  <Step title="轮询直到任务完成">
    调用 [Retrieve Video](./retrieve)，直到状态变为 `completed` 或 `failed`。
  </Step>

  <Step title="下载结果">
    当渲染完成后，使用 [Retrieve Video Content](./retrieve-content) 获取文件。
  </Step>
</Steps>

## 仍然适用的 Sora 行为

OpenAI 在 Videos API 中记录了相同的 create -> retrieve -> download 流程。在 CometAPI 上，你保留 Sora 的请求结构，但使用 CometAPI 的 base URL 和 key。完成后的下载 URL 是临时的，因此如果你需要长期保留，请将已完成的资源复制到你自己的存储中。


## OpenAPI

````yaml api/openapi/video/sora-2/post-create.openapi.json POST /v1/videos
openapi: 3.1.0
info:
  title: Create Video API
  version: 1.0.0
  description: >-
    Create an asynchronous Sora video job through CometAPI. Poll GET
    /v1/videos/{video_id} for status and GET /v1/videos/{video_id}/content for
    the final file.
servers:
  - url: https://api.cometapi.com
security:
  - bearerAuth: []
paths:
  /v1/videos:
    post:
      summary: Create a Sora video job
      description: >-
        Start a Sora render job from a prompt and, optionally, one reference
        image. Save the returned video id and poll the retrieve endpoint until
        the job completes.
      operationId: create_video
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - prompt
              properties:
                prompt:
                  type: string
                  description: Text prompt that describes the video you want to create.
                  example: A paper airplane glides across a desk.
                model:
                  type: string
                  description: >-
                    Sora model ID. Choose an available model from the [Models
                    page](/overview/models).
                  default: sora-2
                  example: sora-2
                seconds:
                  type: string
                  enum:
                    - '4'
                    - '8'
                    - '12'
                    - '16'
                    - '20'
                  description: Clip duration in seconds. Use 4, 8, 12, 16, or 20.
                  default: '4'
                  example: '4'
                size:
                  type: string
                  enum:
                    - 720x1280
                    - 1280x720
                    - 1024x1792
                    - 1792x1024
                  description: >-
                    Output resolution formatted as width x height. Use 1280x720
                    or 720x1280 for standard Sora output. Use 1792x1024 or
                    1024x1792 with a Pro model when you need larger Pro output.
                  default: 1280x720
                  example: 1280x720
                input_reference:
                  type: string
                  format: binary
                  description: >-
                    Optional reference image uploaded as a file. The image
                    should match the target size you request.
              default:
                prompt: A paper airplane glides across a desk.
                model: sora-2
                seconds: '4'
                size: 1280x720
            examples:
              Text to video:
                summary: Text to video
                value:
                  model: sora-2
                  prompt: A paper boat drifts across a calm pond at sunrise
                  seconds: '4'
                  size: 1280x720
              With reference image:
                summary: >-
                  First-frame reference image. Replace input_reference with your
                  image file.
                value:
                  model: sora-2
                  prompt: Animate gentle ripples across the water
                  seconds: '4'
                  size: 1280x720
                  input_reference: '@reference.png'
      responses:
        '200':
          description: Video job accepted.
          content:
            application/json:
              schema:
                type: object
                required:
                  - created_at
                  - id
                  - model
                  - object
                  - progress
                  - seconds
                  - size
                  - status
                properties:
                  created_at:
                    type: integer
                  id:
                    type: string
                  model:
                    type: string
                  object:
                    type: string
                  progress:
                    type: integer
                  seconds:
                    type: string
                  size:
                    type: string
                  status:
                    type: string
                example:
                  created_at: 1773296991
                  id: video_69b25d5f467c81908733a56bc236b4df
                  model: sora-2
                  object: video
                  progress: 0
                  seconds: '4'
                  size: 1280x720
                  status: queued
              example:
                id: <video_id>
                task_id: <video_id>
                object: video
                model: sora-2
                status: queued
                progress: 0
                created_at: 1781079478
                seconds: '4'
                size: 1280x720
      x-codeSamples:
        - lang: Shell
          label: Text to video
          source: |
            curl https://api.cometapi.com/v1/videos \
              -H "Authorization: Bearer $COMETAPI_KEY" \
              -F model=sora-2 \
              -F prompt="A paper boat drifts across a calm pond at sunrise" \
              -F seconds=4 \
              -F size=1280x720
        - lang: Shell
          label: With reference image
          source: |
            curl https://api.cometapi.com/v1/videos \
              -H "Authorization: Bearer $COMETAPI_KEY" \
              -F model=sora-2 \
              -F prompt="Animate gentle ripples across the water" \
              -F seconds=4 \
              -F size=1280x720 \
              -F input_reference=@reference.png
        - lang: Python
          label: Text to video
          source: >
            import os

            import requests


            response = requests.post(
                "https://api.cometapi.com/v1/videos",
                headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
                data={
                    "model": "sora-2",
                    "prompt": "A paper boat drifts across a calm pond at sunrise",
                    "seconds": "4",
                    "size": "1280x720",
                },
            )


            video = response.json()

            print(video["id"], video["status"])  # poll GET /v1/videos/{id}
            until completed
        - lang: Python
          label: With reference image
          source: |
            import os
            import requests

            with open("reference.png", "rb") as image:
                response = requests.post(
                    "https://api.cometapi.com/v1/videos",
                    headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
                    data={
                        "model": "sora-2",
                        "prompt": "Animate gentle ripples across the water",
                        "seconds": "4",
                        "size": "1280x720",
                    },
                    files={"input_reference": image},
                )

            video = response.json()
            print(video["id"], video["status"])
        - lang: JavaScript
          label: Text to video
          source: >
            const form = new FormData();

            form.append("model", "sora-2");

            form.append("prompt", "A paper boat drifts across a calm pond at
            sunrise");

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

            form.append("size", "1280x720");


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


            const video = await response.json();

            console.log(video.id, video.status); // poll GET /v1/videos/{id}
            until completed
        - lang: JavaScript
          label: With reference image
          source: >
            import { readFile } from "node:fs/promises";


            const form = new FormData();

            form.append("model", "sora-2");

            form.append("prompt", "Animate gentle ripples across the water");

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

            form.append("size", "1280x720");

            form.append("input_reference", new Blob([await
            readFile("reference.png")], { 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 video = await response.json();

            console.log(video.id, video.status);
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication. Use your CometAPI key.

````