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

> Capriole AI 모델로 OpenAI 호환 chat completions를 만듭니다.

애플리케이션, SDK 또는 게이트웨이가 OpenAI Chat Completions 요청 및 응답 형식을 기대할 때 이 엔드포인트를 사용하세요.

`model`과 `messages`가 있는 표준 Chat Completions 페이로드를 보내세요. Capriole AI는 업스트림 전달 전에 latest 별칭을 선택한 제공자 모델 ID로 해석하고, `messages`, `tools`, `tool_choice`, `response_format`, `stream` 같은 호환 필드를 전달하며, 업스트림 JSON 또는 SSE 스트림을 그대로 반환합니다. 스트리밍 요청의 경우 Capriole AI는 전달 전에 `stream_options.include_usage=true`를 설정해 사용량을 기록할 수 있게 합니다.

`POST /v1/chat/completions`는 `openai-latest`, `claude-latest`, `google-latest`와 `GET /v1/models`가 반환하는 공개 구체 모델 ID를 받습니다. 해당 제공자의 권장 플래그십 모델을 Capriole AI가 선택하게 하려면 latest 별칭을 사용하세요.

Latest 별칭은 입력 단축키입니다. 사용량은 해석된 모델에 대해 기록되고, 응답 본문은 선택한 호환 엔드포인트의 모델 이름 지정 방식을 유지합니다.

Capriole 네이티브 텍스트 생성에는 `POST /v1/chat`를 사용하세요. OpenAI 호환 전송 동작이 필요하면 `POST /v1/chat/completions`를 사용하세요.


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

````