xAI Messages API

openapi: 3.2.0
info:
  title: xAI's REST Messages API
  description: REST API for xAI compatible with other providers.
  license:
    name: ''
  version: 1.0.0
tags:
- name: Messages
paths:
  /v1/messages:
    post:
      tags:
      - Messages
      summary: Create a messages response. This endpoint is compatible with the Anthropic API
      operationId: handle_generic_messages_request
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageRequest'
            example:
              model: latest
              max_tokens: 32
              messages:
              - role: user
                content: Hello, world
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                id: 4f224bfb-9d53-4c82-b40a-b7cd80831ec2
                type: message
                role: assistant
                content:
                - type: text
                  text: Hello there! "Hello, world" is a classic, isn't it? Whether you're just saying hi or channeling your inner coder, I'm happy to greet you back
                model: latest
                stop_reason: max_tokens
                stop_sequence: null
                usage:
                  input_tokens: 9
                  cache_creation_input_tokens: 0
                  cache_read_input_tokens: 0
                  output_tokens: 32
        '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:
    MessageToolInputSchema:
      type: object
      required:
      - type
      - properties
      properties:
        properties:
          description: JSON-object of the tool input schema.
        required:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Required properties of the tool input schema, if any.
        type:
          type: string
          description: Type of the schema. This is always `"object"`.
    SystemMessagePart:
      type: object
      required:
      - type
      - text
      properties:
        cache_control:
          description: (Unsupported) Cache control.
        text:
          type: string
          description: System prompt text.
        type:
          type: string
          description: Type of the object. This is always `"text"`.
    MessageToolChoice:
      oneOf:
      - type: object
        description: Allows the model to automatically decide whether to call the tool
        required:
        - type
        properties:
          type:
            type: string
            enum:
            - auto
      - type: object
        description: Forces the model to use at least one tool, without specifying the tool.
        required:
        - type
        properties:
          type:
            type: string
            enum:
            - any
      - type: object
        description: Forces the model to use the named tool
        required:
        - name
        - type
        properties:
          name:
            type: string
            description: Name of the tool to use.
          type:
            type: string
            enum:
            - tool
      description: Tool choice option.
    MessageContent:
      oneOf:
      - type: string
        description: Text prompt.
      - type: array
        items:
          $ref: '#/components/schemas/MessageContentPart'
        description: An array of message content parts.
    MessageImageContent:
      oneOf:
      - type: object
        required:
        - media_type
        - data
        - type
        properties:
          data:
            type: string
            description: Base64 encoded image string.
          media_type:
            type: string
            description: 'Media type of the image source. Available options: `image/jpeg`, `image/png`, `image/webp`.'
          type:
            type: string
            enum:
            - base64
      - type: object
        required:
        - url
        - type
        properties:
          type:
            type: string
            enum:
            - url
          url:
            type: string
            description: URL of the image.
    ToolResultContentBlock:
      oneOf:
      - type: object
        description: Text content block.
        required:
        - text
        - type
        properties:
          text:
            type: string
            description: The text content.
          type:
            type: string
            enum:
            - text
      - type: object
        description: Image content block.
        required:
        - source
        - type
        properties:
          source:
            $ref: '#/components/schemas/MessageImageContent'
            description: Image source.
          type:
            type: string
            enum:
            - image
      description: A single content block within a tool_result's array content.
    MessageRequest:
      type: object
      description: Request message for `/v1/messages`
      properties:
        max_tokens:
          type: integer
          format: int32
          description: The maximum number of tokens to generate before stopping. The model may stop before the max_tokens when it reaches the stop sequence.
        messages:
          type: array
          items:
            $ref: '#/components/schemas/MessageBody'
          description: Input messages.
        metadata:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/MessageMetadata'
            description: An object describing metadata about the request.
        model:
          type: string
          description: Model name for the model to use.
          example: latest
        stop_sequences:
          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: 'If set, partial message deltas will be sent. Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a `data: [DONE]` message.'
        system:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/SystemMessageContent'
            description: System prompt message for the model, defining how the model should behave to user messages.
        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. It may not work well with reasoning models.
          default: 1
          maximum: 2
          minimum: 0
        tool_choice:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/MessageToolChoice'
            description: 'Controls which (if any) tool is called by the model. `"none"` means the model will not call any tool and instead generates a message. `"auto"` means the model can pick between generating a message or calling one or more tools. `"any"` means the model must call one or more tools. Specifying a particular tool via `{"type": "tool", "function": {"name": "get_weather"}}` forces the model to call that tool. `"none"` is the default when no tools are provided. `"auto"` is the default if tools are provided.'
        tools:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/MessageTools'
          description: A list of tools the model may call in JSON-schema. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.
        top_k:
          type:
          - integer
          - 'null'
          format: int32
          description: (Unsupported) When generating next tokens, randomly selecting the next token from the k most likely options.
        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. It is generally recommended to alter this or `temperature` but not both.
          default: 1
          maximum: 1
          exclusiveMinimum: 0
    MessageTools:
      type: object
      required:
      - name
      - description
      - input_schema
      properties:
        cache_control:
          description: (Unsupported) Cache control.
        description:
          type: string
          description: Description of the tool.
        input_schema:
          $ref: '#/components/schemas/MessageToolInputSchema'
          description: Input schema allowed by the tool.
        name:
          type: string
          description: Name of the tool.
    SystemMessageContent:
      oneOf:
      - type: string
        description: Text content of system prompt.
      - type: array
        items:
          $ref: '#/components/schemas/SystemMessagePart'
        description: An array of system prompt parts.
    MessageResponseContent:
      oneOf:
      - type: object
        description: Text response from the model.
        required:
        - text
        - type
        properties:
          text:
            type: string
          type:
            type: string
            enum:
            - text
      - type: object
        description: Thinking response for the model
        required:
        - signature
        - thinking
        - type
        properties:
          signature:
            type: string
            description: Signature of the content
          thinking:
            type: string
            description: Thinking content
          type:
            type: string
            enum:
            - thinking
      - type: object
        description: Redacted thinking response for the model
        required:
        - data
        - type
        properties:
          data:
            type: string
            description: Signature of the content
          type:
            type: string
            enum:
            - redacted_thinking
      - type: object
        description: Request by the model to invoke a tool call.
        required:
        - id
        - name
        - input
        - type
        properties:
          id:
            type: string
            description: Tool call ID.
          input:
            description: Input to the tool call follwing the `input_schema`.
          name:
            type: string
            description: Name of the tool call to be used.
          type:
            type: string
            enum:
            - tool_use
    MessageResponse:
      type: object
      description: Response message for `/v1/messages`
      required:
      - id
      - type
      - role
      - content
      - model
      - usage
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/MessageResponseContent'
          description: Response message content.
        id:
          type: string
          description: Unique object identifier.
        model:
          type: string
          description: Model name that handled the request.
          example: latest
        role:
          type: string
          description: Role of the generated message. Always `"assistant"`
        stop_reason:
          type:
          - string
          - 'null'
          description: Reason to stop. `"stop_sequence"` means the inference has reached a model-defined or user-supplied stop sequence in `stop`. `"max_tokens"` 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. `"tool_use"` means the model has called a tool and is waiting for the tool response.
        stop_sequence:
          type:
          - string
          - 'null'
          description: Custom stop sequence used to stop the generation.
        type:
          type: string
          description: Object type. This is always `"message"` for message types.
          example: message
        usage:
          $ref: '#/components/schemas/MessageUsage'
          description: Token usage information.
    MessageBody:
      type: object
      description: Anthropic compatible message body
      required:
      - role
      - content
      properties:
        content:
          $ref: '#/components/schemas/MessageContent'
          description: The content message.
        role:
          type: string
          description: The role that the message belongs to, `"system"` for system prompt, `"user"` for user prompt, and `"assistant"` for response from the model.
    MessageMetadata:
      type: object
      properties:
        user_id:
          type:
          - string
          - 'null'
          description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse.
    MessageContentPart:
      oneOf:
      - type: object
        description: Text prompt message content part.
        required:
        - text
        - type
        properties:
          cache_control:
            description: (Unsupported) Cache control.
          text:
            type: string
            description: Text prompt.
          type:
            type: string
            enum:
            - text
      - type: object
        description: Image prompt message content part.
        required:
        - source
        - type
        properties:
          cache_control:
            description: (Unsupported) Cache control.
          source:
            $ref: '#/components/schemas/MessageImageContent'
            description: Image source.
          type:
            type: string
            enum:
            - image
      - type: object
        description: Tool call message content part. Received from model.
        required:
        - id
        - name
        - input
        - type
        properties:
          cache_control:
            description: (Unsupported) Cache control.
          id:
            type: string
            description: ID of the tool call.
          input:
            description: Input for tool call.
          name:
            type: string
            description: Name of the tool call.
          type:
            type: string
            enum:
            - tool_use
      - type: object
        description: Tool call result.
        required:
        - tool_use_id
        - content
        - type
        properties:
          cache_control:
            description: (Unsupported) Cache control.
          content:
            $ref: '#/components/schemas/ToolResultContent'
            description: Result content of the tool call. Can be a string or an array of content blocks.
          is_error:
            type:
            - boolean
            - 'null'
            description: Whether the tool call returns an error.
          tool_use_id:
            type: string
            description: ID of the tool call given by the model.
          type:
            type: string
            enum:
            - tool_result
      - type: object
        description: (Redacted) Thinking of the model.
        required:
        - data
        - type
        properties:
          data:
            type: string
            description: Encrypted data of the redacted thinking.
          type:
            type: string
            enum:
            - redacted_thinking
      - type: object
        description: Thinking of the model.
        required:
        - thinking
        - type
        properties:
          signature:
            type:
            - string
            - 'null'
            description: Signature of the thinking block (required by Anthropic SDK for round-tripping).
          thinking:
            type: string
            description: Thinking.
          type:
            type: string
            enum:
            - thinking
    ToolResultContent:
      oneOf:
      - type: string
        description: Plain text content.
      - type: array
        items:
          $ref: '#/components/schemas/ToolResultContentBlock'
        description: An array of content blocks (text, image, etc.).
      description: 'Content of a tool_result block. The Anthropic SDK may send this as either a plain

        string or an array of typed content blocks (e.g. `[{"type": "text", "text": "..."}]`).'
    MessageUsage:
      type: object
      required:
      - input_tokens
      - cache_creation_input_tokens
      - cache_read_input_tokens
      - output_tokens
      properties:
        cache_creation_input_tokens:
          type: integer
          format: int32
          description: (Unsupported) Number of tokens written to the cache when creating a new entry.
        cache_read_input_tokens:
          type: integer
          format: int32
          description: Number of tokens retrieved from the cache for this request.
        input_tokens:
          type: integer
          format: int32
          description: Number of input tokens used
        output_tokens:
          type: integer
          format: int32
          description: Number of output tokens used
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer