> ## 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 alias 解析为所选提供商的模型 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。使用 latest alias 可以让 Capriole AI 为对应提供商选择当前推荐的旗舰模型。

Latest alias 只是请求输入的快捷方式。用量按解析后的具体模型记录，响应体则保留所选兼容端点原有的模型命名方式。

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

````