> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.qubrid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Completions

> Generate text responses using large language models.



## OpenAPI

````yaml POST /chat/completions
openapi: 3.0.3
info:
  title: Qubrid Chat API
  version: 1.0.0
  description: >-
    Generate text responses using large language models via the
    OpenAI-compatible chat completions API.
servers:
  - url: https://platform.qubrid.com/v1
security:
  - BearerAuth: []
paths:
  /chat/completions:
    post:
      tags:
        - Chat
      summary: Create Chat Completion
      description: Generate text responses using a large language model.
      operationId: createChatCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
            examples:
              Basic Chat:
                summary: Generate a response from a prompt
                value:
                  model: openai/gpt-oss-120b
                  messages:
                    - role: user
                      content: >-
                        Summarize this support ticket into bullet-point next
                        steps for the agent.
                  max_tokens: 4096
                  temperature: 0.7
                  top_p: 1
                  stream: true
      responses:
        '200':
          description: Chat completion generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResponse'
              example:
                id: chatcmpl-abc123
                object: chat.completion
                created: 1710000000
                model: openai/gpt-oss-120b
                choices:
                  - index: 0
                    message:
                      role: assistant
                      content: |-
                        - Identify issue
                        - Provide solution
                        - Confirm resolution with user
                    finish_reason: stop
                usage:
                  prompt_tokens: 20
                  completion_tokens: 10
                  total_tokens: 30
                x_metrics:
                  ttft_seconds: 0.38
                  tps: 42.1
                  total_time_seconds: 1.24
        '400':
          description: >-
            Bad request - missing required fields, invalid values, or malformed
            JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationErrorResponse'
        '402':
          description: Insufficient credits to process the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientQuotaErrorResponse'
        '403':
          description: >-
            Forbidden - authenticated but not allowed to access this model or
            resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionErrorResponse'
        '404':
          description: >-
            Model not found - the specified model does not exist or is not
            available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelNotFoundErrorResponse'
        '413':
          description: Payload too large - input exceeds the model context window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextLengthExceededErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
        '502':
          description: >-
            Bad gateway - upstream AI provider is unavailable or returned an
            error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackendUnavailableErrorResponse'
        '504':
          description: Gateway timeout - upstream AI provider took too long to respond
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayTimeoutErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    ChatRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
          example: openai/gpt-oss-120b
          description: The language model to use.
        messages:
          type: array
          description: Conversation messages in chat format.
          items:
            type: object
            required:
              - role
              - content
            properties:
              role:
                type: string
                example: user
                description: Role of the message sender (system, user, assistant).
              content:
                type: string
                example: >-
                  Summarize this support ticket into bullet-point next steps for
                  the agent.
        max_tokens:
          type: integer
          default: 4096
          description: Maximum number of tokens to generate.
        temperature:
          type: number
          default: 0.7
          description: Controls randomness in output.
        top_p:
          type: number
          default: 1
          description: Nucleus sampling parameter.
        stream:
          type: boolean
          default: true
          description: Whether to stream responses incrementally.
    ChatResponse:
      type: object
      description: Standard OpenAI-compatible chat completion response or streamed chunks.
      properties:
        id:
          type: string
          example: chatcmpl-abc123
        object:
          type: string
          example: chat.completion
        created:
          type: integer
          example: 1710000000
        model:
          type: string
          example: openai/gpt-oss-120b
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
                example: 0
              message:
                type: object
                properties:
                  role:
                    type: string
                    example: assistant
                  content:
                    type: string
                    example: |-
                      - Identify customer issue
                      - Provide resolution steps
                      - Follow up with confirmation
              finish_reason:
                type: string
                example: stop
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
              example: 20
            completion_tokens:
              type: integer
              example: 10
            total_tokens:
              type: integer
              example: 30
        x_metrics:
          type: object
          description: Performance metrics for the request.
          properties:
            ttft_seconds:
              type: number
              example: 0.38
            tps:
              type: number
              example: 42.1
            total_time_seconds:
              type: number
              example: 1.24
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
            - code
            - request_id
          properties:
            message:
              type: string
              example: 'Missing required parameter: ''model''.'
            type:
              type: string
              example: invalid_request_error
              description: Machine-readable error category.
            code:
              type: string
              example: invalid_request
              description: Specific machine-readable error code.
            param:
              type: string
              nullable: true
              example: model
              description: The request field that caused the error, or null.
            request_id:
              type: string
              example: req-qubrid-abc123
              description: Unique request identifier for debugging and support.
    AuthenticationErrorResponse:
      type: object
      description: Returned when authentication fails.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
            - code
            - request_id
          properties:
            message:
              type: string
              example: Missing authentication credentials.
            type:
              type: string
              example: authentication_error
            code:
              type: string
              example: missing_api_key
            param:
              type: string
              nullable: true
              example: null
            request_id:
              type: string
              example: req-qubrid-abc123
    InsufficientQuotaErrorResponse:
      type: object
      description: >-
        Returned when the account does not have enough credits to complete the
        request.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
            - code
            - request_id
          properties:
            message:
              type: string
              example: >-
                Insufficient credits to process this request. Please recharge
                your account.
            type:
              type: string
              example: insufficient_quota
            code:
              type: string
              example: insufficient_quota
            param:
              type: string
              nullable: true
              example: null
            request_id:
              type: string
              example: req-qubrid-abc123
    PermissionErrorResponse:
      type: object
      description: >-
        Returned when the authenticated account does not have permission to
        access the resource.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
            - code
            - request_id
          properties:
            message:
              type: string
              example: >-
                Permission denied: You do not have permission to access this
                model.
            type:
              type: string
              example: permission_error
            code:
              type: string
              example: insufficient_quota
            param:
              type: string
              nullable: true
              example: null
            request_id:
              type: string
              example: req-qubrid-abc123
    ModelNotFoundErrorResponse:
      type: object
      description: Returned when the specified model does not exist or is not available.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
            - code
            - request_id
          properties:
            message:
              type: string
              example: The model 'gpt-99' does not exist or is not available.
            type:
              type: string
              example: invalid_request_error
            code:
              type: string
              example: model_not_found
            param:
              type: string
              nullable: true
              example: model
            request_id:
              type: string
              example: req-qubrid-abc123
    ContextLengthExceededErrorResponse:
      type: object
      description: Returned when the input exceeds the model's maximum context window.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
            - code
            - request_id
          properties:
            message:
              type: string
              example: >-
                Context length exceeded: The input exceeds the model's maximum
                context length.
            type:
              type: string
              example: invalid_request_error
            code:
              type: string
              example: context_length_exceeded
            param:
              type: string
              nullable: true
              example: messages
            request_id:
              type: string
              example: req-qubrid-abc123
    RateLimitErrorResponse:
      type: object
      description: Returned when request rate limits are exceeded.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
            - code
            - request_id
          properties:
            message:
              type: string
              example: Rate limit exceeded. Please try again later.
            type:
              type: string
              example: rate_limit_error
            code:
              type: string
              example: rate_limit_exceeded
            param:
              type: string
              nullable: true
              example: null
            request_id:
              type: string
              example: req-qubrid-abc123
    ServerErrorResponse:
      type: object
      description: Returned when an internal or upstream server error occurs.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
            - code
            - request_id
          properties:
            message:
              type: string
              example: An unexpected error occurred while processing the request.
            type:
              type: string
              example: server_error
            code:
              type: string
              example: internal_error
            param:
              type: string
              nullable: true
              example: null
            request_id:
              type: string
              example: req-qubrid-abc123
    BackendUnavailableErrorResponse:
      type: object
      description: >-
        Returned when the upstream AI provider is temporarily unavailable or
        could not be reached.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
            - code
            - request_id
          properties:
            message:
              type: string
              example: The backend service is temporarily unavailable.
            type:
              type: string
              example: server_error
            code:
              type: string
              example: backend_unavailable
            param:
              type: string
              nullable: true
              example: null
            request_id:
              type: string
              example: req-qubrid-abc123
    GatewayTimeoutErrorResponse:
      type: object
      description: Returned when the upstream AI provider took too long to respond.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
            - code
            - request_id
          properties:
            message:
              type: string
              example: The request timed out while waiting for the backend service.
            type:
              type: string
              example: server_error
            code:
              type: string
              example: backend_error
            param:
              type: string
              nullable: true
              example: null
            request_id:
              type: string
              example: req-qubrid-abc123
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````