> ## 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 會立即回傳影片 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 model 時使用較大的 Pro 尺寸。 |

Sora 要求 `size` 欄位必須採用精確的 `WxH` 格式。像 `720p` 這類解析度標記，以及像 `16:9` 這類比例標籤，都不是此端點上有效的 Sora `size` 值。

## 端到端流程

<Steps>
  <Step title="建立渲染工作">
    傳送 `model`、`prompt`、`seconds` 和 `size`，然後儲存回傳的 `id`。
  </Step>

  <Step title="輪詢直到工作完成">
    呼叫 [擷取影片](./retrieve)，直到狀態變為 `completed` 或 `failed`。
  </Step>

  <Step title="下載結果">
    當渲染完成後，使用 [擷取影片內容](./retrieve-content) 取得檔案。
  </Step>
</Steps>

## 仍然適用的 Sora 行為

OpenAI 在 Videos API 中記錄了相同的 create -> retrieve -> download 流程。在 CometAPI 上，你可以保留 Sora 的請求結構，但要使用 CometAPI 的基底 URL 和金鑰。完成後的下載 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.

````