# Create video

## OpenAPI Specification

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /v1/videos:
    post:
      summary: Create video
      deprecated: false
      description: >
        ## Overview


        `videos` is OpenAI Sora's video generation interface that creates video
        generation tasks through text prompts or optional reference image
        inputs. After creation, you need to use the [query
        interface](https://apidoc.cometapi.com/video/sora2/retrive-video) to get
        the generation status.Once the video has been created, you need to call
        /v1/videos/{video_id}/content again to retrieve the video content.


        Once the task is completed, you can proceed with subsequent operations
        such as
        [remixing](https://apidoc.cometapi.com/video/sora/official/remix) and
        [downloading](https://apidoc.cometapi.com/video/sora2/retrive-video-content).


        For more information about the Sora generation interface, please refer
        to [OpenAI Official
        Documentation](https://platform.openai.com/docs/api-reference/videos/create)


        ### Supported Models


        Currently supported model IDs: `sora-2` `sora-2-pro`


        ### Important Notes


        ⚠️ **Asynchronous Processing**

        Video generation requires considerable time and uses asynchronous mode.
        After creating a task, a task ID is returned immediately. You need to
        use the query interface to get generation progress and results.


        ⚠️ **Content Policy**

        Generated video content must comply with OpenAI's usage policies.
        Content that is illegal, violent, pornographic, or infringes on
        copyrights is prohibited.


        ⚠️ **Moderation Error**

        If you receive `Your request was blocked by our moderation system.`,
        this error is returned by OpenAI's official moderation system due to
        non-compliant input parameters. Please adjust your request parameters
        (e.g., modify the prompt content, change reference images) and try
        again.


        ### Best Practices


        1. **Prompt Optimization**: Use specific, detailed descriptions
        including scene, action, lighting and other details

        2. **Duration Control**: Choose appropriate duration based on content
        complexity; shorter durations typically yield better quality

        3. **Resolution Selection**: Choose appropriate resolution based on use
        case, balancing quality and generation time

        4. **Image Preprocessing**: When using image guidance, ensure input
        images are clear with reasonable composition

        5. **Error Handling**: Implement comprehensive retry and error handling
        mechanisms

        6. **Resource Management**: Download generated videos promptly to avoid
        resource expiration


        ### FAQ


        **Q: How long does video generation take?**

        A: Typically takes several minutes to over ten minutes, depending on
        video duration, resolution, and server load. If there's no response for
        a long time or failure occurs, please contact customer service.


        **Q: What resolutions are supported?**

        A: Default support for `720x1280`. For specific supported resolutions,
        please refer to the model documentation.


        **Q: How long can generated videos be?**

        A: Default is 4 seconds. Maximum duration depends on model limitations,
        please refer to official documentation.


        **Q: How to improve generation quality?**

        A: Use detailed prompts, choose appropriate duration, and provide
        high-quality reference images.


        ### 📋 Storyboard Mode


        The API supports Storyboard functionality for creating sequential
        multi-shot videos. When using storyboard mode, the prompt must strictly
        follow this format:


        ```

        Shot 1:

        duration: 7.5sec

        Scene: The plane takes off.


        Shot 2:

        duration: 7.5sec

        Scene: The plane lands.

        ```


        **Format Requirements:**

        - Each shot starts with `Shot N:` (N is the shot number)

        - Use `duration: Xsec` to specify shot duration

        - Use `Scene:` to describe the shot content

        - Separate shots with blank lines
      tags:
        - 📺 Video Models/sora-2/official
      parameters:
        - name: Authorization
          in: header
          description: ''
          required: true
          example: '{{api-key}}'
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                prompt:
                  description: Text prompt that describes the video to generate.
                  example: cat
                  type: string
                model:
                  type: string
                  enum:
                    - sora-2-pro
                    - sora-2
                  x-apidog-enum:
                    - value: sora-2-pro
                      name: sora-2-pro
                      description: ''
                    - value: sora-2
                      name: sora-2
                      description: ''
                  description: The video generation model to use. Defaults to sora-2.
                  example: sora-2
                seconds:
                  type: string
                  enum:
                    - '4'
                    - '8'
                    - '12'
                  x-apidog-enum:
                    - value: '4'
                      name: ''
                      description: ''
                    - value: '8'
                      name: ''
                      description: ''
                    - value: '12'
                      name: ''
                      description: ''
                  description: 'Clip duration in seconds. Defaults to 4 seconds. '
                  example: '4'
                size:
                  type: string
                  enum:
                    - 720x1280
                    - 1280x720
                    - 1024x1792
                    - 1792x1024
                  x-apidog-enum:
                    - value: 720x1280
                      name: ''
                      description: ''
                    - value: 1280x720
                      name: ''
                      description: ''
                    - value: 1024x1792
                      name: ''
                      description: ''
                    - value: 1792x1024
                      name: ''
                      description: ''
                  description: >-
                    Output resolution formatted as width x height. Defaults to
                    720x1280.
                  example: 720x1280
                input_reference:
                  format: binary
                  type: string
                  description: >-
                    Image reference, used to guide generation.  

                    **Only local path uploads are supported; URLs are not
                    accepted, and only one image can be uploaded at most.**  

                    For curl request parameters, please add `--form
                    'input_reference=@"/path/to/your/image"'`  

                    **The uploaded image size must match the value of `size`.**
                  example: ''
              required:
                - prompt
            examples: {}
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  object:
                    type: string
                  created_at:
                    type: integer
                  status:
                    type: string
                  completed_at:
                    type: 'null'
                  error:
                    type: 'null'
                  expires_at:
                    type: 'null'
                  model:
                    type: string
                  progress:
                    type: integer
                  remixed_from_video_id:
                    type: 'null'
                  seconds:
                    type: string
                  size:
                    type: string
                required:
                  - id
                  - object
                  - created_at
                  - status
                  - completed_at
                  - error
                  - expires_at
                  - model
                  - progress
                  - remixed_from_video_id
                  - seconds
                  - size
                x-apidog-orders:
                  - id
                  - object
                  - created_at
                  - status
                  - completed_at
                  - error
                  - expires_at
                  - model
                  - progress
                  - remixed_from_video_id
                  - seconds
                  - size
                x-apidog-ignore-properties: []
              example:
                id: video_68e688d4950481918ec389280c2f78140fcb904657674466
                object: video
                created_at: 1759938772
                status: queued
                completed_at: null
                error: null
                expires_at: null
                model: sora-2
                progress: 0
                remixed_from_video_id: null
                seconds: '4'
                size: 720x1280
          headers: {}
          x-apidog-name: Successful Response
      security: []
      x-apidog-folder: 📺 Video Models/sora-2/official
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/810968/apis/api-22425640-run
components:
  schemas: {}
  securitySchemes: {}
servers:
  - url: https://api.cometapi.com
    description: Prod Env
security: []

```