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

# Chat completions

> Create OpenAI-compatible chat completions with Capriole AI models.

Use this endpoint when your application, SDK, or gateway expects the OpenAI Chat Completions request and response format.

Send a standard Chat Completions payload with `model` and `messages`. Capriole AI resolves latest aliases to the selected provider model ID before upstream dispatch, forwards compatible fields such as `messages`, `tools`, `tool_choice`, `response_format`, and `stream`, and returns the upstream JSON or SSE stream unchanged. For streaming requests, Capriole AI sets `stream_options.include_usage=true` before forwarding so usage can be recorded.

`POST /v1/chat/completions` accepts `openai-latest`, `claude-latest`, `google-latest`, and public concrete model IDs returned by `GET /v1/models`. Use a latest alias to let Capriole AI choose our recommended flagship model for that provider.

Latest aliases are input shortcuts. Usage is recorded against the resolved model, while the response body keeps the model naming behavior of the selected compatible endpoint.

For Capriole-native text generation, use `POST /v1/chat`. Use `POST /v1/chat/completions` when OpenAI-compatible wire behavior is required.


## OpenAPI

````yaml api-reference/openapi.json POST /v1/chat/completions
openapi: 3.1.0
info:
  title: Capriole AI API
  description: >-
    Public API for model discovery, text chat, and protocol-compatible model
    endpoints.
  version: 1.0.0
servers:
  - url: https://api.caprioletech.com
security: []
paths:
  /v1/chat/completions:
    post:
      summary: Create chat completion
      description: >-
        Creates an OpenAI-compatible chat completion for clients that use the
        Chat Completions request and response format.
      operationId: createChatCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionsRequest'
            examples:
              text:
                value:
                  model: openai-latest
                  messages:
                    - role: user
                      content: Hello World!
              streaming:
                value:
                  model: openai-latest
                  messages:
                    - role: user
                      content: Write a short Python function.
                  stream: true
      responses:
        '200':
          description: >-
            OpenAI-compatible Chat Completions response or SSE stream. Response
            model fields follow the selected compatible endpoint and may differ
            from the input alias.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionsResponse'
              examples:
                default:
                  value:
                    id: chatcmpl_123
                    object: chat.completion
                    created: 1764547200
                    model: gpt-5.5
                    choices:
                      - index: 0
                        message:
                          role: assistant
                          content: Hello! How can I help?
                        finish_reason: stop
                    usage:
                      prompt_tokens: 12
                      completion_tokens: 8
                      total_tokens: 20
            text/event-stream:
              schema:
                type: string
                description: OpenAI-compatible Chat Completions SSE chunks.
        '400':
          $ref: '#/components/responses/ValidationOrDetailErrorResponse'
        '401':
          $ref: '#/components/responses/DetailErrorResponse'
        '403':
          $ref: '#/components/responses/DetailErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimitErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '502':
          $ref: '#/components/responses/DetailErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    ChatCompletionsRequest:
      type: object
      additionalProperties: true
      required:
        - model
        - messages
      properties:
        model:
          type: string
          description: Public model identifier or latest alias returned by GET /v1/models
          enum:
            - openai-latest
            - openai/gpt-5.6-terra
            - openai/gpt-5.6-luna
            - openai/gpt-5.5
            - openai/gpt-5.4-mini
            - claude-latest
            - anthropic/claude-fable-5
            - anthropic/claude-opus-4-8
            - anthropic/claude-opus-4-7
            - anthropic/claude-opus-4-6
            - anthropic/claude-sonnet-4-6
            - google-latest
            - google/gemini-3.1-pro-preview
            - google/gemini-3.5-flash
            - xai/grok-4.5
            - zai/glm-5.2
        messages:
          type: array
          description: OpenAI-compatible conversation messages.
          items:
            $ref: '#/components/schemas/ChatCompletionsMessage'
        tools:
          type: array
          description: OpenAI-compatible tool definitions.
          items:
            type: object
            additionalProperties: true
        tool_choice:
          description: OpenAI-compatible tool choice.
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
        response_format:
          type: object
          description: OpenAI-compatible response format.
          additionalProperties: true
        stream:
          type: boolean
          default: false
          description: Stream the response as OpenAI-compatible server-sent events.
        stream_options:
          type: object
          description: >-
            OpenAI-compatible stream options. For streaming requests, Capriole
            AI sets include_usage=true before upstream dispatch for usage
            accounting.
          additionalProperties: true
    ChatCompletionsResponse:
      type: object
      additionalProperties: true
      required:
        - id
        - object
        - created
        - model
        - choices
      properties:
        id:
          type: string
        object:
          type: string
          example: chat.completion
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            additionalProperties: true
        usage:
          type: object
          additionalProperties: true
    ChatCompletionsMessage:
      type: object
      additionalProperties: true
      required:
        - role
      properties:
        role:
          type: string
          description: Message role such as system, user, assistant, or tool.
        content:
          description: OpenAI-compatible message content.
          oneOf:
            - type: string
            - type: array
              items:
                type: object
                additionalProperties: true
            - type: 'null'
    ValidationError:
      type: object
      required:
        - detail
        - errors
      properties:
        detail:
          type: string
          description: Validation summary
        errors:
          type: array
          items:
            type: string
          description: Per-field validation errors
    DetailError:
      type: object
      required:
        - detail
      properties:
        detail:
          type: string
          description: Error detail from the API
  responses:
    ValidationOrDetailErrorResponse:
      description: Validation error or request-level error response
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ValidationError'
              - $ref: '#/components/schemas/DetailError'
          examples:
            invalidPayload:
              value:
                detail: Invalid input parameters received.
                errors:
                  - >-
                    Field 'body -> input': String should have at least 1
                    character
    DetailErrorResponse:
      description: Error response with a detail message
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DetailError'
          examples:
            missingBearerToken:
              value:
                detail: Missing Bearer token
            invalidApiKey:
              value:
                detail: Invalid API key
            usageMetadataUnavailable:
              value:
                detail: Missing usage metadata
    RateLimitErrorResponse:
      description: Rate limit error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DetailError'
          examples:
            rateLimitExceeded:
              value:
                detail: 'Rate limit exceeded: 100 per 1 minute'
    InternalServerErrorResponse:
      description: Internal server error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DetailError'
          examples:
            internalServerError:
              value:
                detail: An internal server error occurred. Please try again later.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Use an API key created in the Capriole AI page. Send it as
        `Authorization: Bearer sk-...`.

````