> ## 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는 즉시 비디오 id를 반환하며 렌더링이 끝날 때까지 기다리지 않습니다.

## 가장 작은 유용한 작업으로 시작하기

* 더 빠르게 반복 작업하려면 `sora-2`를 사용하고, 속도보다 출력 품질이 더 중요하면 `sora-2-pro`를 사용하세요
* 첫 요청에서는 `seconds`를 `4`로 유지하세요
* 세로형 출력이 꼭 필요한 경우가 아니라면 `size: 1280x720`으로 시작하세요
* 참조 이미지는 최대 1장만 업로드하세요

## 길이와 크기

| 설정                   | 지원 값                                     | 기본 시작점                     | 경계 동작                            |
| -------------------- | ---------------------------------------- | -------------------------- | -------------------------------- |
| `seconds`            | `4`, `8`, `12`, `16`, `20`               | `4`                        | 다른 값은 Sora 비디오 요청 형식에 포함되지 않습니다. |
| `sora-2`의 `size`     | `1280x720`, `720x1280`                   | `1280x720`                 | 가로 또는 세로 방향을 사용하세요.              |
| `sora-2-pro`의 `size` | `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="작업이 끝날 때까지 조회">
    상태가 `completed` 또는 `failed`가 될 때까지 [비디오 조회](./retrieve)를 호출하세요.
  </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.

````