> ## 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

> Crea Chat Completions compatibles con OpenAI con modelos de Capriole AI.

Usa este endpoint cuando tu aplicación, SDK o gateway espere el formato de solicitud y respuesta de OpenAI Chat Completions.

Envía un payload estándar de Chat Completions con `model` y `messages`. Capriole AI resuelve los alias latest al ID de modelo del proveedor seleccionado antes del envío a upstream, reenvía campos compatibles como `messages`, `tools`, `tool_choice`, `response_format` y `stream`, y devuelve el JSON o el flujo SSE de upstream sin cambios. En solicitudes streaming, Capriole AI establece `stream_options.include_usage=true` antes de reenviar para poder registrar el uso.

`POST /v1/chat/completions` acepta `openai-latest`, `claude-latest`, `google-latest` y los IDs de modelo concretos públicos que devuelve `GET /v1/models`. Usa un alias latest para que Capriole AI elija nuestro modelo insignia recomendado para ese proveedor.

Los alias latest son atajos de entrada. El uso se registra contra el modelo resuelto, mientras que el cuerpo de la respuesta conserva el comportamiento de nombres de modelo del endpoint compatible seleccionado.

Para generación de texto nativa de Capriole, usa `POST /v1/chat`. Usa `POST /v1/chat/completions` cuando se requiera el comportamiento de transmisión compatible con OpenAI.


## 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-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
            - moonshot/kimi-k3
        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-...`.

````