openapi: 3.2.0
info:
  title: xAI's REST Completions API
  description: REST API for xAI compatible with other providers.
  license:
    name: ''
  version: 1.0.0
tags:
- name: Completions
paths:
  /v1/completions:
    post:
      tags:
      - Completions
      summary: (Legacy - Not supported by reasoning models) Create a text completion response…
      operationId: handle_sample_request
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SampleRequest'
            example:
              prompt: '1, 2, 3, 4, '
              model: grok-3
              max_tokens: 3
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SampleResponse'
              example:
                id: 873492b3-6144-4279-ac2e-2c45242c5ce6
                object: text_completion
                created: 1743771779
                model: grok-3
                choices:
                - index: 0
                  text: '5, '
                  finish_reason: length
                usage:
                  prompt_tokens: 12
                  completion_tokens: 3
                  total_tokens: 15
                  prompt_tokens_details:
                    text_tokens: 12
                    audio_tokens: 0
                    image_tokens: 0
                    cached_tokens: 0
                  completion_tokens_details:
                    reasoning_tokens: 0
                    audio_tokens: 0
                    accepted_prediction_tokens: 0
                    rejected_prediction_tokens: 0
                system_fingerprint: fp_156d35dcaa
        '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:
    CompletionUsageDetail:
      type: object
      description: Details of completion usage.
      required:
      - reasoning_tokens
      - audio_tokens
      - accepted_prediction_tokens
      - rejected_prediction_tokens
      properties:
        accepted_prediction_tokens:
          type: integer
          format: int32
          description: The number of tokens in the prediction that appeared in the completion.
        audio_tokens:
          type: integer
          format: int32
          description: Audio input tokens generated by the model.
        reasoning_tokens:
          type: integer
          format: int32
          description: Tokens generated by the model for reasoning.
        rejected_prediction_tokens:
          type: integer
          format: int32
          description: The number of tokens in the prediction that did not appear in the completion.
    SampleContent:
      oneOf:
      - type: string
        description: Text prompt.
      - type: array
        items:
          type: string
        description: An array of strings, a token list, or an array of token lists.
    SampleResponse:
      type: object
      description: (Legacy) Response for `/v1/completions` endpoint
      required:
      - id
      - object
      - created
      - model
      - choices
      properties:
        choices:
          type: array
          items:
            $ref: '#/components/schemas/SampleChoice'
          description: A list of response choices from the model. The length corresponds to the `n` in request body (default to 1).
        created:
          type: integer
          format: int64
          description: The chat completion creation time in Unix timestamp.
        id:
          type: string
          description: ID of the request.
        model:
          type: string
          description: Model to be used.
          example: latest
        object:
          type: string
          description: Object type of the response. This is always `"text_completion"`.
        system_fingerprint:
          type:
          - string
          - 'null'
          description: System fingerprint, used to indicate xAI system configuration changes.
        usage:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/Usage'
            description: Token usage information.
    SampleRequest:
      type: object
      description: (Legacy) Request for `/v1/completions` endpoint
      properties:
        best_of:
          type:
          - integer
          - 'null'
          format: int32
          description: (Unsupported) Generates multiple completions internally and returns the top-scoring one. Not functional yet.
        echo:
          type:
          - boolean
          - 'null'
          description: Option to include the original prompt in the response along with the generated completion.
        frequency_penalty:
          type:
          - number
          - 'null'
          format: float
          description: (Unsupported) Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
        logit_bias:
          type:
          - object
          - 'null'
          description: (Unsupported) Accepts a JSON object that maps tokens to an associated bias value from -100 to 100. You can use this tokenizer tool to convert text to token IDs. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.
          additionalProperties:
            type: number
            format: float
          propertyNames:
            type: integer
            format: int32
        logprobs:
          type:
          - boolean
          - 'null'
          description: Include the log probabilities on the `logprobs` most likely output tokens, as well the chosen tokens. For example, if `logprobs` is 5, the API will return a list of the 5 most likely tokens. The API will always return the logprob of the sampled token, so there may be up to `logprobs+1` elements in the response.
        max_tokens:
          type:
          - integer
          - 'null'
          format: int32
          description: Limits the number of tokens that can be produced in the output. Ensure the sum of prompt tokens and `max_tokens` does not exceed the model's context limit.
        model:
          type: string
          description: Specifies the model to be used for the request.
        n:
          type:
          - integer
          - 'null'
          format: int32
          description: Determines how many completion sequences to produce for each prompt. Be cautious with its use due to high token consumption; adjust `max_tokens` and stop sequences accordingly.
        presence_penalty:
          type:
          - number
          - 'null'
          format: float
          description: (Not supported by `grok-3` and reasoning models) Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.
        prompt:
          $ref: '#/components/schemas/SampleContent'
          description: Input for generating completions, which can be a string, list of strings, token list, or list of token lists. `<|endoftext|>` is used as a document separator, implying a new context start if omitted.
        seed:
          type:
          - integer
          - 'null'
          format: int32
          description: If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result. Determinism is not guaranteed, and you should refer to the system_fingerprint response parameter to monitor changes in the backend.
        stop:
          type:
          - array
          - 'null'
          items:
            type: string
          description: (Not supported by reasoning models) Up to 4 sequences where the API will stop generating further tokens.
        stream:
          type:
          - boolean
          - 'null'
          description: 'Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a `data: [DONE]` message.'
        stream_options:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/StreamOptions'
            description: 'Options for streaming response. Only set this when you set `stream: true`.'
        suffix:
          type:
          - string
          - 'null'
          description: (Unsupported) Optional string to append after the generated text.
        temperature:
          type:
          - number
          - 'null'
          format: float
          description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both.
          default: 1
          example: 0.2
          maximum: 2
          minimum: 0
        top_p:
          type:
          - number
          - 'null'
          format: float
          description: An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.
        user:
          type:
          - string
          - 'null'
          description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse.
    StreamOptions:
      type: object
      description: Options available when using streaming response.
      required:
      - include_usage
      properties:
        include_usage:
          type: boolean
          description: 'Set an additional chunk to be streamed before the `data: [DONE]` message. The other chunks will return `null` in `usage` field.'
    Usage:
      type: object
      required:
      - prompt_tokens
      - completion_tokens
      - total_tokens
      - prompt_tokens_details
      - completion_tokens_details
      - num_sources_used
      - cost_in_usd_ticks
      properties:
        completion_tokens:
          type: integer
          format: int32
          description: Total completion token used.
        completion_tokens_details:
          $ref: '#/components/schemas/CompletionUsageDetail'
          description: Breakdown of completion token usage of different types.
        cost_in_usd_ticks:
          type: integer
          format: int64
          description: 'Accurate cost of this request in USD ticks, where "tick" is defined as follows:

            TICKS_IN_USD_CENT: i64 = 100_000_000

            which means there is 10''000''000''000 ticks in one *dollar*.'
        num_sources_used:
          type: integer
          format: int32
          description: Number of individual live search source used.
        prompt_tokens:
          type: integer
          format: int32
          description: Total prompt token used.
        prompt_tokens_details:
          $ref: '#/components/schemas/PromptUsageDetail'
          description: Breakdown of prompt token usage of different types.
        total_tokens:
          type: integer
          format: int32
          description: Total token used, the sum of prompt token and completion token amount.
    PromptUsageDetail:
      type: object
      description: Details of prompt usage.
      required:
      - text_tokens
      - audio_tokens
      - image_tokens
      - cached_tokens
      properties:
        audio_tokens:
          type: integer
          format: int32
          description: Audio prompt token used.
        cached_tokens:
          type: integer
          format: int32
          description: Token cached by xAI from previous requests and reused for this request.
        image_tokens:
          type: integer
          format: int32
          description: Image prompt token used.
        text_tokens:
          type: integer
          format: int32
          description: Total text prompt token used (cached + non-cached text tokens).
    SampleChoice:
      type: object
      required:
      - index
      - text
      - finish_reason
      properties:
        finish_reason:
          type: string
          description: Finish reason. `"stop"` means the inference has reached a model-defined or user-supplied stop sequence in `stop`. `"length"` means the inference result has reached models' maximum allowed token length or user defined value in `max_tokens`. `"end_turn"` or `null` in streaming mode when the chunk is not the last.
        index:
          type: integer
          format: int32
          description: Index of the choice.
        text:
          type: string
          description: Text response.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer