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

# Create Video

> Use POST /v1/videos to create Sora 2 video generation tasks from text prompts or reference images, then poll status by task ID for results.

Use this endpoint to start a new Sora render job from text, or from text plus one reference image. The API returns a video id immediately and does not wait for the render to finish.

## Start with the smallest useful job

* Use `sora-2` for faster iteration or `sora-2-pro` when output quality matters more than speed
* Keep `seconds` at `4` for your first request
* Start with `size: 1280x720` unless you specifically need portrait output
* Upload at most one reference image

## End-to-end flow

<Steps>
  <Step title="Create the render job">
    Send `model`, `prompt`, `seconds`, and `size`, then save the returned `id`.
  </Step>

  <Step title="Poll until the job finishes">
    Call [Retrieve Video](./retrieve-video) until the status becomes `completed` or `failed`.
  </Step>

  <Step title="Download or remix the result">
    When the render is done, fetch the file with [Retrieve Video Content](./retrieve-video-content). If you want a targeted variation, use [Remix Video](./remix-video) on the completed result.
  </Step>
</Steps>

## Sora behavior that still applies

OpenAI documents the same create -> retrieve -> download flow in the Videos API. On CometAPI you keep the Sora request shape, but use the CometAPI base URL and key. Finished download URLs are temporary, so copy completed assets into your own storage if you need long retention.


## OpenAPI

````yaml /api/openapi/video/sora-2/official/post-create-video.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 new 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 a current model from the [Models
                    page](/overview/models).
                  default: sora-2
                  example: sora-2
                seconds:
                  type: string
                  enum:
                    - '4'
                    - '8'
                    - '12'
                  description: Clip duration in seconds.
                  default: '4'
                  example: '4'
                size:
                  type: string
                  enum:
                    - 720x1280
                    - 1280x720
                    - 1024x1792
                    - 1792x1024
                  description: Output resolution formatted as width x height.
                  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
      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
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication. Use your CometAPI key.

````