openapi: 3.2.0
info:
  title: xAI's REST Images API
  description: REST API for xAI compatible with other providers.
  license:
    name: ''
  version: 1.0.0
tags:
- name: Images
paths:
  /v1/images/edits:
    post:
      tags:
      - Images
      summary: Edit an image based on a prompt.
      operationId: handle_edit_image_request
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditImageRequest'
            example:
              prompt: Add a hat to this cat.
              image:
                url: '...'
              model: grok-imagine-image
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneratedImageResponse'
              example:
                data:
                - url: '...'
        '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/images/generations:
    post:
      tags:
      - Images
      summary: Generate an image based on a prompt.
      operationId: handle_generate_image_request
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateImageRequest'
            example:
              prompt: A cat in a tree
              model: grok-imagine-image
              response_format: url
              n: 2
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneratedImageResponse'
              example:
                data:
                - url: '...'
                - url: '...'
        '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: []
components:
  schemas:
    ImageResolution:
      type: string
      description: 'Resolution for image generation.

        Only supported by grok-imagine models.'
      enum:
      - 1k
      - 2k
    GeneratedImageResponse:
      type: object
      description: Image generation response for `/v1/image/generations` endpoint
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GeneratedImage'
          description: A list of generated image objects.
        usage:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/MediaUsage'
            description: Billing and cost information for this request.
    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.'
    EditImageRequest:
      type: object
      description: Request for editing image
      required:
      - prompt
      properties:
        aspect_ratio:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/ImageAspectRatio'
            description: 'Aspect ratio of the output image for image editing with multiple images.

              For single image editing, do not set this. It will always auto-detect from the input image.'
        image:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/ImageUrl'
            description: Input image to perform edit on. Mutually exclusive with `images`.
        images:
          type: array
          items:
            $ref: '#/components/schemas/ImageUrl'
          description: 'List of input images for multi-reference editing.

            Mutually exclusive with `image`. When multiple images are provided,

            refer to them as \<IMAGE_0\>, \<IMAGE_1\>, etc. in the prompt.'
        model:
          type:
          - string
          - 'null'
          description: Model to be used.
          example: grok-imagine-image
        n:
          type:
          - integer
          - 'null'
          format: int32
          description: Number of image edits to be generated.
        prompt:
          type: string
          description: Prompt for image editing.
        resolution:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/ImageResolution'
            description: 'Resolution of the generated image. Defaults to `1k`.

              Only supported by grok-imagine models.'
        response_format:
          type:
          - string
          - 'null'
          description: Response format to return the image in. Can be `url` or `b64_json`. If `b64_json` is specified, the image will be returned as a base64-encoded string instead of a url to the generated image file.
          default: url
        user:
          type:
          - string
          - 'null'
          description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse.
    GenerateImageRequest:
      type: object
      properties:
        aspect_ratio:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/ImageAspectRatio'
            description: 'Aspect ratio of the generated image. Can be `1:1`, `3:4`, `4:3`, `9:16`, `16:9`, `2:3`, `3:2`, `9:19.5`, `19.5:9`, `9:20`, `20:9`, `1:2`, `2:1`, or `auto`.

              Defaults to `auto` for automatically selecting the best ratio for the prompt.

              Only supported by grok-imagine models.'
        model:
          type:
          - string
          - 'null'
          description: Model to be used.
          example: grok-imagine-image
        n:
          type:
          - integer
          - 'null'
          format: int32
          description: Number of images to be generated
          default: 1
          maximum: 10
          minimum: 1
        prompt:
          type: string
          description: Prompt for image generation.
        resolution:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/ImageResolution'
            description: 'Resolution of the generated image. Defaults to `1k`.

              Only supported by grok-imagine models.'
        response_format:
          type:
          - string
          - 'null'
          description: Response format to return the image in. Can be url or b64_json. If b64_json is specified, the image will be returned as a base64-encoded string instead of a url to the generated image file.
          default: url
        user:
          type:
          - string
          - 'null'
          description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse.
    GeneratedImage:
      type: object
      description: Generated images
      properties:
        b64_json:
          type:
          - string
          - 'null'
          description: A base64-encoded string representation of the generated image (without the data-URI prefix), if `b64_json` is specified as `response_format` in the request.
        mime_type:
          type:
          - string
          - 'null'
          description: The MIME type of the generated image (e.g. `image/png`, `image/jpeg`, `image/webp`).
        url:
          type:
          - string
          - 'null'
          description: A url to the generated image, if `response_format` is not specified or with `url` in the request.
    ImageAspectRatio:
      type: string
      description: 'Aspect ratio for image generation.

        Only supported by grok-imagine models.'
      enum:
      - '1:1'
      - '3:4'
      - '4:3'
      - '9:16'
      - '16:9'
      - '2:3'
      - '3:2'
      - '9:19.5'
      - 19.5:9
      - '9:20'
      - '20:9'
      - '1:2'
      - '2:1'
      - auto
    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.'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer