openapi: 3.2.0
info:
  title: xAI's REST Embeddings API
  description: REST API for xAI compatible with other providers.
  license:
    name: ''
  version: 1.0.0
tags:
- name: Embeddings
paths:
  /v1/embeddings:
    post:
      tags:
      - Embeddings
      summary: Create an embedding vector representation corresponding to the input text.
      operationId: handle_embedding_request
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingRequest'
            example: "{\n            \"input\": [\"This is an example content to embed...\"],\n            \"model\": \"v1\",\n            \"encoding_format\": \"float\"\n        }"
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingResponse'
              example:
                object: list
                model: v1
                data:
                - index: 0
                  embedding:
                  - 0.01567895
                  - 0.063257694
                  - 0.045925662
                  object: embedding
                usage:
                  prompt_tokens: 1
                  total_tokens: 1
        '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:
    EmbeddingResponse:
      type: object
      required:
      - object
      - model
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Embedding'
          description: A list of embedding objects.
        model:
          type: string
          description: Model ID used to create embedding.
        object:
          type: string
          description: The object type of `data` field, which is always `"list"`.
        usage:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/EmbeddingUsage'
            description: Token usage information.
    EmbeddingInput:
      oneOf:
      - type: object
        description: 'A strings to be embedded. For best performance, prepend "query: " in front of query content and prepend "passage: " in front of passage/text'
        required:
        - String
        properties:
          String:
            type: string
            description: 'A strings to be embedded. For best performance, prepend "query: " in front of query content and prepend "passage: " in front of passage/text'
      - type: object
        description: An array of strings to be embedded
        required:
        - StringArray
        properties:
          StringArray:
            type: array
            items:
              type: string
            description: An array of strings to be embedded
      - type: object
        description: A token in integer to be embedded
        required:
        - Ints
        properties:
          Ints:
            type: array
            items:
              type: integer
              format: int32
            description: A token in integer to be embedded
      - type: object
        description: An array of tokens in integers to be embedded
        required:
        - IntsArray
        properties:
          IntsArray:
            type: array
            items:
              type: array
              items:
                type: integer
                format: int32
            description: An array of tokens in integers to be embedded
    Embedding:
      type: object
      required:
      - index
      - embedding
      - object
      properties:
        embedding:
          $ref: '#/components/schemas/EmbeddingContent'
          description: Embedding content.
        index:
          type: integer
          format: int32
          description: Index of the embedding object in the data list.
        object:
          type: string
          description: The object type, which is always `"embedding"`.
    EmbeddingContent:
      oneOf:
      - type: string
        description: Embedding in base64 string.
      - type: array
        items:
          type: number
          format: float
        description: Embedding as an array of floats.
    EmbeddingRequest:
      type: object
      properties:
        dimensions:
          type:
          - integer
          - 'null'
          format: int32
          description: The number of dimensions the resulting output embeddings should have.
        encoding_format:
          type:
          - string
          - 'null'
          description: The format to return the embeddings in. Can be either `float` or `base64`.
        input:
          $ref: '#/components/schemas/EmbeddingInput'
          description: Input text to embed, encoded as a string or list of tokens. To embed multiple inputs in a single request, pass a list of strings or list of token lists. The total tokens in the input must not exceed the context window for the model and cannot be an empty string. If the input is a list, the maximum length of the list is 128.
        model:
          type: string
          description: ID of the model to use.
          example: v1
        preview:
          type:
          - boolean
          - 'null'
          description: Flag to use the new format of the API.
        user:
          type:
          - string
          - 'null'
          description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse.
    EmbeddingUsage:
      type: object
      required:
      - prompt_tokens
      - total_tokens
      properties:
        prompt_tokens:
          type: integer
          format: int32
          description: Prompt token used.
        total_tokens:
          type: integer
          format: int32
          description: Total token used.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer