xAI Videos API

openapi: 3.2.0
info:
  title: xAI's REST Videos API
  description: REST API for xAI compatible with other providers.
  license:
    name: ''
  version: 1.0.0
tags:
- name: Videos
paths:
  /v1/videos/edits:
    post:
      tags:
      - Videos
      summary: Edit a video based on a prompt.
      operationId: handle_edit_video_request
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditVideoRequest'
            example:
              prompt: Add snow to the scene
              video:
                url: https://example.com/video.mp4
              model: grok-imagine-video
        required: true
      responses:
        '200':
          description: Video editing started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartDeferredResponse'
              example:
                request_id: a3d1008e-4544-40d4-d075-11527e794e4a
        '400':
          description: Bad request. The request is invalid or an invalid API key is provided.
        '422':
          description: Unprocessable Entity. There are missing fields in the request body.
      security:
      - bearerAuth: []
  /v1/videos/extensions:
    post:
      tags:
      - Videos
      summary: Extend a video by generating continuation content.
      operationId: handle_extend_video_request
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtendVideoRequest'
            example:
              prompt: The camera slowly zooms out to reveal the city skyline
              video:
                url: https://example.com/video.mp4
              model: grok-imagine-video
              duration: 6
        required: true
      responses:
        '200':
          description: Video extension started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartDeferredResponse'
              example:
                request_id: a3d1008e-4544-40d4-d075-11527e794e4a
        '400':
          description: Bad request. The request is invalid or an invalid API key is provided.
        '422':
          description: Unprocessable Entity. There are missing fields in the request body.
      security:
      - bearerAuth: []
  /v1/videos/generations:
    post:
      tags:
      - Videos
      summary: Generate a video from a text prompt and optionally an image.
      operationId: handle_generate_video_request
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateVideoRequest'
            example:
              prompt: A cat playing with a ball
              model: grok-imagine-video
              duration: 6
        required: true
      responses:
        '200':
          description: Video generation started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartDeferredResponse'
              example:
                request_id: a3d1008e-4544-40d4-d075-11527e794e4a
        '400':
          description: Bad request. The request is invalid or an invalid API key is provided.
        '422':
          description: Unprocessable Entity. There are missing fields in the request body.
      security:
      - bearerAuth: []
  /v1/videos/{request_id}:
    get:
      tags:
      - Videos
      summary: Get the result of a deferred video generation request
      description: 'Returns the current status of a video generation job. When the job completes

        successfully the response contains the generated video URL. When the job fails

        the response contains a structured `error` object with a machine-readable

        `code` and a human-readable `message`.


        Both successful and failed completions return HTTP 200 — use the `status`

        field (`"done"` or `"failed"`) to distinguish between the two.'
      operationId: handle_get_deferred_video_request
      parameters:
      - name: request_id
        in: path
        description: The deferred request id returned by a previous video generation request.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Video generation completed or failed. Check the `status` field to determine the outcome.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoResponse'
              example:
                status: done
                video:
                  url: https://vidgen.x.ai/xai-vidgen-bucket/xai-video-{request_id}.mp4
                  duration: 6
                  respect_moderation: true
                model: grok-imagine-video
        '202':
          description: Video generation still in progress
        '400':
          description: Bad request. The request is invalid or an invalid API key is provided.
        '404':
          description: Not found. No deferred video could be found with the given request_id.
      security:
      - bearerAuth: []
components:
  schemas:
    VideoOutput:
      type: object
      description: Output destination for generated video.
      required:
      - upload_url
      properties:
        upload_url:
          type: string
          description: Signed URL to upload the generated video via HTTP PUT.
    VideoResolution:
      type: string
      description: Resolution for video generation.
      enum:
      - 480p
      - 720p
      - 1080p
    GenerateVideoRequest:
      type: object
      description: Request to generate video for `/v1/videos/generations` endpoint
      properties:
        aspect_ratio:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/VideoAspectRatio'
            description: Aspect ratio of the generated video.
        duration:
          type:
          - integer
          - 'null'
          format: int32
          description: 'Video duration in seconds. Range: [1, 15]. Default: 8.

            Also accepts `seconds` for OpenAI API compatibility.

            Accepts both number (8) and string ("8") values.'
          default: 8
          maximum: 15
          minimum: 1
        image:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/ImageUrl'
            description: 'Optional input image for image-to-video generation.

              If provided, generates video with this image as the first frame.

              Also accepts `input_reference` for compatibility (same semantics — first frame).'
        model:
          type:
          - string
          - 'null'
          description: Model to be used.
          example: grok-imagine-video
        output:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/VideoOutput'
            description: Optional output destination for generated video.
        prompt:
          type: string
          description: 'Prompt for video generation. Required for text-to-video (T2V) and

            reference-to-video (R2V). Optional for image-to-video (I2V) — when

            omitted, the model generates a video from the image alone.'
        reference_images:
          type: array
          items:
            $ref: '#/components/schemas/ImageUrl'
          description: 'Optional reference images for reference-to-video (R2V) generation.

            When provided generates video using these images

            as style/content references.'
        resolution:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/VideoResolution'
            description: Resolution of the generated video.
        user:
          type:
          - string
          - 'null'
          description: A unique identifier representing your end-user.
    VideoResponse:
      type: object
      description: Video generation response.
      required:
      - status
      - progress
      properties:
        error:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/VideoError'
            description: 'Structured error describing why video generation failed.

              Only present when the generation encountered a failure (4xx or 5xx).'
        model:
          type:
          - string
          - 'null'
          description: The model used to generate the video. Omitted when status is "failed".
        progress:
          type: integer
          format: int32
          description: 'Approximate completion percentage for the video generation task (0-100).

            - When status is "pending": progress is between 0-99, indicating current completion.

            - When status is "done": progress is 100.

            - When status is "failed": progress is 0.'
          maximum: 100
          minimum: 0
        status:
          type: string
          description: 'Status of the video generation: "done" when the video is ready.'
        usage:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/MediaUsage'
            description: Billing and cost information for this request.
        video:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/GeneratedVideo'
            description: The generated video data. Omitted when status is "failed".
    MediaUsage:
      type: object
      description: Billing and cost information for media generation requests (image and video).
      required:
      - cost_in_usd_ticks
      properties:
        cost_in_usd_ticks:
          type: integer
          format: int64
          description: 'The cost of this request expressed in USD ticks.

            One USD cent equals 100,000,000 ticks, so one US dollar equals

            10,000,000,000 ticks.'
    StartDeferredResponse:
      type: object
      description: Response for starting a deferred operation.
      required:
      - request_id
      properties:
        request_id:
          type: string
          description: A unique request ID to poll for the result.
    VideoAspectRatio:
      type: string
      description: Aspect ratio for video generation.
      enum:
      - '1:1'
      - '16:9'
      - '9:16'
      - '4:3'
      - '3:4'
      - '3:2'
      - '2:3'
    VideoError:
      type: object
      description: Structured error returned when video generation fails.
      required:
      - code
      - message
      properties:
        code:
          $ref: '#/components/schemas/VideoErrorCode'
          description: 'Machine-readable error code indicating the type of failure.

            See `VideoErrorCode` for all possible values.'
        message:
          type: string
          description: Human-readable error message describing the failure.
    EditVideoRequest:
      type: object
      description: Request for editing video for `/v1/videos/edits` endpoint
      required:
      - prompt
      - video
      properties:
        model:
          type:
          - string
          - 'null'
          description: Model to be used.
          example: grok-imagine-video
        output:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/VideoOutput'
            description: Optional output destination for generated video.
        prompt:
          type: string
          description: Prompt for video editing.
        user:
          type:
          - string
          - 'null'
          description: A unique identifier representing your end-user.
        video:
          $ref: '#/components/schemas/VideoUrl'
          description: Input video to perform edit on.
    ExtendVideoRequest:
      type: object
      description: Request for extending a video for `/v1/videos/extensions` endpoint
      required:
      - prompt
      - video
      properties:
        duration:
          type:
          - integer
          - 'null'
          format: int32
          description: 'Duration of the extension segment to generate in seconds (1-10).

            Defaults to 6 seconds if not specified.'
        model:
          type:
          - string
          - 'null'
          description: Model to be used.
          example: grok-imagine-video
        output:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/VideoOutput'
            description: Optional output destination for generated video.
        prompt:
          type: string
          description: Prompt describing what should happen next in the video.
        video:
          $ref: '#/components/schemas/VideoUrl'
          description: 'Input video to extend. The extension continues from the end of this video.

            Input video must be between 2 and 30 seconds long.'
    VideoErrorCode:
      type: string
      description: 'Machine-readable error codes for video generation failures.


        These are the codes that can appear in `VideoError.code` when polling a

        deferred video generation result. Authentication errors, model-not-found

        errors, and rate-limit errors are returned synchronously as HTTP errors

        and never appear in `VideoError`.


        Serializes to/from snake_case strings (e.g. `"invalid_argument"`,

        `"internal_error"`) for JSON compatibility.'
      enum:
      - invalid_argument
      - permission_denied
      - failed_precondition
      - internal_error
    ImageUrl:
      type: object
      description: 'Image input for generation and editing requests.

        Accepts a public URL, a base64-encoded data URL, or a file_id from the xAI Files API.'
      properties:
        file_id:
          type:
          - string
          - 'null'
          description: 'File ID from the xAI Files API. Mutually exclusive with `url`.

            The file must be an image (JPEG, PNG, or WebP) and fully uploaded.'
        url:
          type: string
          description: 'Public URL or base64-encoded data URL of the image (JPEG, PNG, or WebP).

            Also accepts `image_url` for compatibility.

            Required when `file_id` is not set.'
    VideoUrl:
      type: object
      description: 'Video input for editing and extension requests.

        Accepts a public URL, a base64-encoded data URL, or a file_id from the xAI Files API.'
      properties:
        file_id:
          type:
          - string
          - 'null'
          description: 'File ID from the xAI Files API. Mutually exclusive with `url`.

            The file must be a video (e.g., MP4) and fully uploaded.'
        url:
          type: string
          description: 'URL of the video (public URL or base64-encoded data URL).

            The video must have the `.mp4` file extension and be encoded with `.mp4` supported codecs such as H.265, H.264, AV1, etc.

            Required when `file_id` is not set.'
    GeneratedVideo:
      type: object
      description: Generated video.
      required:
      - duration
      - respect_moderation
      properties:
        duration:
          type: integer
          format: int32
          description: Duration of the generated video in seconds.
        respect_moderation:
          type: boolean
          description: 'Whether the video generated by the model respects moderation rules.

            The field will be true if the video respects moderation rules. Otherwise

            the field will be false and the video url field will be empty.'
        url:
          type:
          - string
          - 'null'
          description: A url to the generated video.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer