---
title: "Chat completion (OpenAI-совместимый)"
method: POST
path: "/v1/chat/completions"
tags: ["LLM"]
---

# Chat completion (OpenAI-совместимый)

`POST /v1/chat/completions`

## Request

- Base URL: `https://api.clipia.ai`
- URL: `https://api.clipia.ai/v1/chat/completions`
- Auth: API key in header `Authorization`

Drop-in замена `POST https://api.openai.com/v1/chat/completions`:
`model` — slug из `GET /v1/models` (LLM-записи), `messages` — массив
OpenAI-сообщений, `stream: true` — SSE-поток чанков `chat.completion.chunk`.
Неизвестные верхнеуровневые поля (`route`, `transforms`, `usage`,
`include_reasoning`) игнорируются, не отклоняются.

Оплата — кредитами по ставке модели (`pricing` в `LlmModelSummary`);
фактическое списание конкретного ответа — `GET /v1/generation?id=<id ответа>`.
Ответ содержит `id` вида `chatcmpl-…` и `provider: "Clipia"`.

Ошибки — в OpenAI-конверте `{ "error": { "message", "type", "code" } }`:
`402 insufficient_quota`, `429 rate_limit_error` (+ `Retry-After`),
`404 model_not_found`.

**Sandbox.** С тестовым ключом (`clipia_test_…`) возвращается
детерминированный ответ без обращения к модели и без списания.

## Request body

- ChatCompletionRequest: Подмножество OpenAI chat-запроса; остальные поля OpenAI-формата принимаются и игнорируются.
  - `model` string, required: Slug LLM-модели из `GET /v1/models`.
  - `messages` object[], required
    - `role` 'system' | 'user' | 'assistant' | 'tool', required
    - `content` unknown, required
    - `name` string
    - `tool_call_id` string
  - `stream` boolean
  - `temperature` number
  - `top_p` number
  - `max_tokens` integer
  - `max_completion_tokens` integer
  - `n` integer
  - `seed` integer
  - `stop` union
    - string
    - string[]
  - `tools` object[]
  - `tool_choice` unknown
  - `response_format` object
  - `reasoning_effort` string
  - `stream_options` object
    - `include_usage` boolean
  - `user` string

## Response `200`

Ответ `chat.completion` (JSON) либо SSE-поток (`text/event-stream`)
при `stream: true`, завершающийся `data: [DONE]`.

- ChatCompletionResponse
  - `id` string, required: Детерминированный id ответа; принимается `GET /v1/generation?id=`.
  - `object` 'chat.completion', required
  - `created` integer, required
  - `model` string, required
  - `provider` 'Clipia'
  - `choices` object[], required
    - `index` integer
    - `message` object
      - `role` string
      - `content` string, nullable
      - `tool_calls` object[]
    - `finish_reason` 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'error' | 'null', nullable
  - `usage` OpenAIUsage, required
    - `prompt_tokens` integer
    - `completion_tokens` integer
    - `total_tokens` integer
    - `cost` number: Списанные кредиты (дробные).

## Other responses

- `401`: Ключ отсутствует, неверный или отозван.
- `402`: Бюджет/кредиты исчерпаны (`insufficient_quota`).
- `404`: Неизвестный `model`.
- `429`: Лимит RPM/TPM/одновременных запросов; см. `Retry-After`.

---

[API](https://skmtc.dev/clipia/apis/clipia-api.md) · [All operations](https://skmtc.dev/clipia/apis/clipia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/clipia/apis/clipia-api/revisions/cc55924a3381?raw)