> ## 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 を使用して、テキストプロンプトまたは参照画像から Sora 2 の動画生成タスクを作成し、その後 task ID でステータスをポーリングして結果を取得します。

このエンドポイントを使用すると、テキストから、またはテキストと 1 枚の参照画像から Sora のレンダージョブを開始できます。API はすぐに video id を返し、レンダリングの完了は待ちません。

## 最小限で有用なジョブから始める

* より素早く反復したい場合は `sora-2` を、速度よりも出力品質を重視する場合は `sora-2-pro` を使用します
* 最初のリクエストでは `seconds` を `4` にします
* 縦長出力が明確に必要でない限り、`size: 1280x720` から始めます
* 参照画像は最大 1 枚までアップロードします

## Duration and size

| Setting                 | Supported values                                       | Default starting point               | Boundary behavior                  |
| ----------------------- | ------------------------------------------------------ | ------------------------------------ | ---------------------------------- |
| `seconds`               | `4`, `8`, `12`, `16`, `20`                             | `4`                                  | その他の値は Sora の動画リクエスト形状には含まれません。    |
| `size` for `sora-2`     | `1280x720`, `720x1280`                                 | `1280x720`                           | 横向きまたは縦向きの向きを使用します。                |
| `size` for `sora-2-pro` | `1792x1024`, `1024x1792`, plus the standard Sora sizes | `1792x1024` for landscape Pro output | より大きい Pro サイズは Pro モデルでのみ使用してください。 |

Sora では、`size` フィールドに正確な `WxH` 形式が必要です。`720p` のような解像度トークンや `16:9` のような比率ラベルは、このエンドポイントでは有効な Sora `size` 値ではありません。

## エンドツーエンドのフロー

<Steps>
  <Step title="レンダージョブを作成する">
    `model`、`prompt`、`seconds`、`size` を送信し、返された `id` を保存します。
  </Step>

  <Step title="ジョブが完了するまでポーリングする">
    ステータスが `completed` または `failed` になるまで [Retrieve Video](./retrieve) を呼び出します。
  </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.

````