---
title: Chat Completions
description: POST /v1/chat/completions — OpenAI-совместимый чат Clipia AI Gateway. Обычный и потоковый ответ, параметры, роли, вызов инструментов и ошибки.
icon: MessageSquare
---

`POST /v1/chat/completions` — основной эндпоинт Clipia AI Gateway, совместимый с OpenAI Chat Completions. Ключу нужно право `generate` — оно есть у каждого ключа, отдельный ключ для чата не нужен. Принимает массив `messages`, возвращает ответ ассистента в обычном или потоковом режиме, поддерживает вызов инструментов и структурированный вывод по JSON-схеме.

<Method name="POST" path="/v1/chat/completions" />

## Обычный ответ

<Tabs items={['Python', 'Node.js', 'cURL']}>
<Tab value="Python">

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CLIPIA_KEY"],
    base_url="https://api.clipia.ai/v1",
)

resp = client.chat.completions.create(
    model="claude-opus-5-5",
    messages=[
        {"role": "system", "content": "Ты лаконичный ассистент."},
        {"role": "user", "content": "Назови три факта о Марсе."},
    ],
    max_tokens=512,
)

print(resp.choices[0].message.content)
print(resp.usage)
```

</Tab>
<Tab value="Node.js">

```ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CLIPIA_KEY,
  baseURL: "https://api.clipia.ai/v1",
});

const resp = await client.chat.completions.create({
  model: "claude-opus-5-5",
  messages: [
    { role: "system", content: "Ты лаконичный ассистент." },
    { role: "user", content: "Назови три факта о Марсе." },
  ],
  max_tokens: 512,
});

console.log(resp.choices[0].message.content);
```

</Tab>
<Tab value="cURL">

```bash
curl https://api.clipia.ai/v1/chat/completions \
  -H "Authorization: Bearer $CLIPIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "messages": [
      { "role": "system", "content": "Ты лаконичный ассистент." },
      { "role": "user", "content": "Назови три факта о Марсе." }
    ],
    "max_tokens": 512
  }'
```

</Tab>
</Tabs>

**Ответ `200`**

```json
{
  "id": "chatcmpl-3f9a1c7e2b41",
  "object": "chat.completion",
  "created": 1782300000,
  "model": "claude-opus-5-5",
  "provider": "Clipia",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "1. ...\n2. ...\n3. ..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 64,
    "total_tokens": 92,
    "prompt_tokens_details": { "cached_tokens": 0 }
  }
}
```

`usage` — расход токенов: `prompt_tokens`, `completion_tokens`, `total_tokens` и `prompt_tokens_details.cached_tokens`; при кешировании промпта добавляются `cache_read_input_tokens` и `cache_creation_input_tokens`. Стоимости в **кредитах** в `usage` нет: её возвращает `GET /v1/generation?id=` по `id` ответа — см. [«Ключ и лимиты»](/ru/docs/llm-gateway/account#cost). `id` ответа имеет вид `chatcmpl-…`, `provider` всегда равен `"Clipia"`. `finish_reason` приводится к перечислению OpenAI: `stop`, `length`, `tool_calls`, `content_filter`.

## Потоковый ответ

Передайте `stream: true` — ответ придёт по мере генерации в виде Server-Sent Events. Каждое событие — это `chat.completion.chunk` с дельтой; поток завершается строкой `data: [DONE]`.

<Tabs items={['Python', 'Node.js', 'cURL']}>
<Tab value="Python">

```python
stream = client.chat.completions.create(
    model="claude-opus-5-5",
    messages=[{"role": "user", "content": "Напиши хокку про море."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)
```

</Tab>
<Tab value="Node.js">

```ts
const stream = await client.chat.completions.create({
  model: "claude-opus-5-5",
  messages: [{ role: "user", content: "Напиши хокку про море." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```

</Tab>
<Tab value="cURL">

```bash
curl -N https://api.clipia.ai/v1/chat/completions \
  -H "Authorization: Bearer $CLIPIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "messages": [{ "role": "user", "content": "Напиши хокку про море." }],
    "stream": true
  }'
```

</Tab>
</Tabs>

**Поток событий**

```text
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1782300000,"model":"claude-opus-5-5","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"claude-opus-5-5","choices":[{"index":0,"delta":{"content":"Волны "},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"claude-opus-5-5","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```

<Callout type="info" title="Итоговый usage в стриме">
Чтобы получить `usage` в потоковом режиме, передайте `stream_options: { "include_usage": true }`. Тогда перед `data: [DONE]` придёт дополнительный чанк с заполненным `usage` и пустым `choices: []`.
</Callout>

## Таймауты и повторы [#timeouts]

<Callout type="warn" title="Длинные ответы — только в потоке">
Долгий запрос без стриминга может получить `504` на границе шлюза, даже если модель ещё работает. Для моделей с рассуждениями, длинных ответов и больших `max_tokens` включайте `stream: true` (при необходимости со `stream_options.include_usage`): поток живёт, пока приходят данные, а общий потолок одного ответа — 4 минуты. Долгая пауза без единого токена тоже обрывает соединение.
</Callout>

Для обычного (не потокового) ответа передайте заголовок `Idempotency-Key` — до 255 символов, например UUID v4. Повтор с тем же ключом и тем же телом в течение 24 часов вернёт сохранённый ответ с заголовком `Idempotent-Replayed: true` без нового списания; тот же ключ с другим телом — `409 idempotency_key_reuse`, повтор, пока первый запрос ещё выполняется, — `409 request_in_progress`. Если первый запрос завершился ошибкой, ключ освобождается. В потоковом режиме заголовок игнорируется: поток выполняется заново. Без ключа повтор после обрыва или сетевого сбоя — это новый запрос и новое списание, а официальный `openai` SDK по умолчанию сам повторяет запрос дважды: передавайте ключ в заголовках запроса или отключите автоматические повторы (`max_retries=0` в Python, `maxRetries: 0` в Node.js).

Если соединение оборвалось до конца ответа, генерация останавливается: в потоке после первого фрагмента списываются кредиты за уже отданное, а до первого фрагмента и в обычном ответе резерв возвращается. Стоимость выполненного запроса можно проверить по его `id` через [`GET /v1/generation`](/ru/docs/llm-gateway/account#cost), но `id` приходит только в полученном ответе; журнал запросов — на вкладке «Логи» в консоли разработчика. У MCP-инструмента [`chat`](/ru/docs/mcp/tools#conditional) свой безопасный повтор по `idempotency_key`. На чат действуют общие [лимиты запросов и параллельности](/ru/docs/api-reference/rate-limits).

## Параметры запроса

<TypeTable
  type={{
    model: { type: 'string', description: 'Идентификатор модели, например claude-opus-5-5 (см. каталог GET /v1/models). Обязателен.' },
    messages: { type: 'object[]', description: 'Непустая история диалога. content — строка или массив частей. Роли — в разделе ниже.' },
    temperature: { type: 'number', description: 'Степень случайности, 0–2; вне диапазона — 400. По умолчанию — значение модели.' },
    top_p: { type: 'number', description: 'Nucleus sampling, 0–1; вне диапазона — 400. Альтернатива temperature.' },
    max_completion_tokens: { type: 'integer', description: 'Максимум токенов в ответе. Без него действует потолок модели, top_provider.max_completion_tokens из GET /v1/models. Значение выше потолка допускается, резерв считается по запрошенному; выше 200 000 — 400 max_tokens_too_large. Если переданы оба лимита, побеждает этот.' },
    max_tokens: { type: 'integer', description: 'Старое имя того же лимита.' },
    stream: { type: 'boolean', description: 'true — потоковый ответ (SSE). По умолчанию false.' },
    stream_options: { type: 'object', description: '{ include_usage: true } — добавить в поток финальный чанк с usage.' },
    stop: { type: 'string | string[]', description: 'Стоп-последовательности.' },
    seed: { type: 'integer', description: 'Запрос на детерминизм, если модель его поддерживает.' },
    presence_penalty: { type: 'number', description: 'Штраф за повторение тем, −2…2.' },
    frequency_penalty: { type: 'number', description: 'Штраф за повторение токенов, −2…2.' },
    reasoning_effort: { type: 'string', description: 'Глубина рассуждений: minimal, none и low — быстрый режим; medium — сбалансированный; high и xhigh — глубокий. Можно передать и как reasoning: { effort }.' },
    response_format: { type: 'object', description: '{ type: "json_object" } или { type: "json_schema", json_schema: {...} } — структурированный вывод.' },
    tools: { type: 'object[]', description: 'Описания функций, которые модель может вызвать. Суммарный размер — не больше 256 КБ.' },
    tool_choice: { type: 'string | object', description: 'auto | none | required | { type: "function", function: { name } }.' },
    user: { type: 'string', description: 'Стабильный идентификатор конечного пользователя.' },
  }}
/>

<Callout type="info" title="Совместимость параметров">
Всегда возвращается один вариант: `n` допустим только равным 1, иначе `400`. Поля `parallel_tool_calls`, `logprobs`, `top_logprobs`, `logit_bias`, `service_tier` и `metadata` принимаются, но не влияют на ответ. Неизвестные поля верхнего уровня тоже не приводят к ошибке `400`, поэтому код, написанный под OpenAI, переносится без правок.

Поддержка параметров зависит от модели: сверяйте `supported_parameters` в `GET /v1/models`. Современные модели могут игнорировать `temperature`, `top_p` и штрафы за повторения. DeepSeek V4.1 Flash работает без вызова инструментов. Для строгого JSON по схеме выбирайте модель с `response_format`, например GPT-6.1 Sol. Claude 5.5 формирует структурированный ответ по инструкции без гарантии строгого соответствия схеме.
</Callout>

## Роли сообщений [#roles]

| Роль | Как обрабатывается |
| --- | --- |
| `system` | системная инструкция |
| `developer` | обрабатывается как `system` |
| `user` | сообщение пользователя |
| `assistant` | предыдущий ответ модели, в том числе с `tool_calls` |
| `tool` | результат вызова инструмента, нужен `tool_call_id` |
| любая другая | обрабатывается как `user` |

Пустой `messages`, сообщение без строки `role` или запрос без `model` вернут `400 invalid_request_error`.

## Вызов инструментов

Полный цикл: вы описываете инструменты в `tools`, модель возвращает `tool_calls`, вы выполняете функцию на своей стороне и отправляете результат сообщением с `role: "tool"`, после чего модель формирует финальный ответ.

```python
import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Текущая погода в городе",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "Название города"},
                },
                "required": ["city"],
            },
        },
    }
]

messages = [{"role": "user", "content": "Какая сейчас погода в Москве?"}]

# 1) Модель решает вызвать инструмент
resp = client.chat.completions.create(
    model="claude-opus-5-5", messages=messages, tools=tools,
)
msg = resp.choices[0].message
# resp.choices[0].finish_reason == "tool_calls"

# 2) Выполняем функцию на своей стороне
call = msg.tool_calls[0]
args = json.loads(call.function.arguments)   # {"city": "Москва"}
result = {"temp_c": 14, "condition": "облачно"}

# 3) Возвращаем результат модели и получаем финальный ответ
messages.append(msg)  # эхо ассистента с tool_calls
messages.append({
    "role": "tool",
    "tool_call_id": call.id,
    "content": json.dumps(result, ensure_ascii=False),
})

final = client.chat.completions.create(
    model="claude-opus-5-5", messages=messages, tools=tools,
)
print(final.choices[0].message.content)
```

В потоковом режиме фрагменты `tool_calls` приходят по полю `index`: имя функции и `id` — в первой дельте этого индекса, далее — фрагменты `function.arguments`, которые нужно склеить в валидный JSON. Завершение вызова инструмента помечается `finish_reason: "tool_calls"`.

## Структурированный вывод

Чтобы получить ответ строго по JSON-схеме, передайте `response_format` с `type: "json_schema"` и `strict: true`.

```python
resp = client.chat.completions.create(
    model="gpt-6.1-sol",
    messages=[{"role": "user", "content": "Извлеки имя и возраст: Анне 30 лет."}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                },
                "required": ["name", "age"],
                "additionalProperties": False,
            },
        },
    },
)

print(resp.choices[0].message.content)  # {"name": "Анна", "age": 30}
```

<Callout type="info" title="json_object против json_schema">
`response_format: { "type": "json_object" }` гарантирует валидный JSON, но без конкретной схемы — и требует, чтобы слово «json» встречалось в `messages`. Для жёсткого соответствия структуре используйте `json_schema` со `strict: true`. В потоке схема проверяется после полного ответа: при несовпадении последний чанк придёт с ошибкой `invalid_structured_output`, кредиты не спишутся, но уже полученный текст отозвать нельзя.
</Callout>

## Старый формат: `POST /v1/completions` [#legacy-completions]

Для клиентов старого формата text-completion (например, класса `OpenAI` в LangChain вместо `ChatOpenAI`) есть `POST /v1/completions`: строка `prompt` становится единственным сообщением пользователя, ответ приходит в форме `text_completion` с текстом в `choices[].text`, идентификатор — `cmpl-…`. Модели, цены, стриминг, лимиты и ошибки те же, что у `/v1/chat/completions`.

## Ошибки [#errors]

Ошибки приходят в конверте OpenAI: `{ "error": { "message", "type", "param", "code" } }`, всегда с `Content-Type: application/json` и соответствующим HTTP-статусом.

| Статус | `code` | `type` | Когда |
|--------|--------|--------|-------|
| `400` | `invalid_request_error` | `invalid_request_error` | некорректное тело: нет `model`, пустой `messages`, неверная JSON-схема в `response_format` |
| `400` | `context_length_exceeded` | `invalid_request_error` | ввод больше контекста модели; проверяется до списания |
| `400` | `max_tokens_too_large` | `invalid_request_error` | `max_tokens` больше 200 000; `param` указывает поле |
| `400` | `invalid_request_error` | `invalid_request_error` | `temperature`/`top_p` вне диапазона, `n` ≠ 1, `tools` больше 256 КБ или модель отклонила параметры запроса; проверяется до списания |
| `401` | `invalid_api_key` | `invalid_request_error` | ключа нет, он неверный или отозван |
| `402` | `insufficient_quota` | `insufficient_quota` | не хватает кредитов на балансе |
| `402` | `subscription_required` | `insufficient_quota` | для модели нужна активная подписка |
| `402` | `insufficient_quota` | `insufficient_quota` | исчерпан бюджет кредитов ключа на период — см. [«Лимиты»](/ru/docs/api-reference/rate-limits) |
| `403` | `insufficient_scope` или `permission_error` | `invalid_request_error` | у ключа нет права или запрос не разрешён |
| `404` | `model_not_found` | `invalid_request_error` | неизвестный или недоступный `model` |
| `409` | `idempotency_key_reuse` или `request_in_progress` | `invalid_request_error` | тот же `Idempotency-Key` с другим телом или повтор, пока первый запрос ещё выполняется |
| `422` | `model_input_invalid` | `invalid_request_error` | модель отклонила запрос по содержанию; переформулируйте ввод |
| `429` | `rate_limit_exceeded` или `concurrency_limit_exceeded` | `rate_limit_error` | превышен лимит запросов, токенов или параллельности |
| `500`, `502`, `503`, `504` | `null` | `api_error` | временный сбой модели, повторите запрос позже |

```json
{
  "error": {
    "message": "Insufficient credits. Please top up your balance.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_quota"
  }
}
```

На ошибки `5xx` сообщение всегда общее: «The upstream model is temporarily unavailable. Please retry.» для `502`, `503` и `504`, «An internal error occurred. Please retry or contact support.» для `500`. Отдельно стоит `504` с границы шлюза: он приходит, когда долгий ответ без стриминга не успел прийти, а его тело формирует прокси, поэтому оно может быть не в формате OpenAI, — см. [«Таймауты и повторы»](#timeouts).

### Ошибка внутри потока [#stream-errors]

Если сбой случился после начала потока, HTTP-статус уже `200`. Тогда последний чанк перед `data: [DONE]` содержит `finish_reason: "error"` и объект `error`:

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion.chunk",
  "choices": [{ "index": 0, "delta": {}, "finish_reason": "error" }],
  "error": { "message": "The model timed out. Please retry.", "code": "upstream_timeout", "type": "api_error" }
}
```

| `code` | Что случилось |
| --- | --- |
| `upstream_error` | модель не ответила |
| `upstream_timeout` | модель не уложилась во время |
| `service_unavailable` | модель временно недоступна |
| `empty_response` | модель не вернула пригодного ответа |
| `incomplete_stream` | поток модели оборвался до конца |
| `invalid_structured_output` | ответ не соответствует запрошенному `response_format` |
| `model_input_invalid` | модель отклонила запрос по содержанию |
| `invalid_request_error` | модель отклонила параметры запроса; `type` такого чанка — `invalid_request_error` |

Проверяйте `finish_reason` последнего чанка: клиенты OpenAI SDK не всегда превращают такой чанк в исключение. За текст, отданный до сбоя, кредиты списываются; если отдать ничего не успели, резерв возвращается. Ошибки до начала потока, например `402` или `404`, приходят обычным JSON с HTTP-статусом.
