AI Gateway
Chat Completions
POST /v1/chat/completions — OpenAI-совместимый чат Clipia AI Gateway. Обычный и потоковый ответ, параметры, роли, вызов инструментов и ошибки.
POST /v1/chat/completions — основной эндпоинт Clipia AI Gateway, совместимый с OpenAI Chat Completions. Ключу нужно право generate — оно есть у каждого ключа, отдельный ключ для чата не нужен. Принимает массив messages, возвращает ответ ассистента в обычном или потоковом режиме, поддерживает вызов инструментов и структурированный вывод по JSON-схеме.
/v1/chat/completionsОбычный ответ
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)Ответ 200
{
"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 ответа — см. «Ключ и лимиты». id ответа имеет вид chatcmpl-…, provider всегда равен "Clipia". finish_reason приводится к перечислению OpenAI: stop, length, tool_calls, content_filter.
Потоковый ответ
Передайте stream: true — ответ придёт по мере генерации в виде Server-Sent Events. Каждое событие — это chat.completion.chunk с дельтой; поток завершается строкой data: [DONE].
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)Поток событий
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]Итоговый usage в стриме
Чтобы получить usage в потоковом режиме, передайте stream_options: { "include_usage": true }. Тогда перед data: [DONE] придёт дополнительный чанк с заполненным usage и пустым choices: [].
Таймауты и повторы
Длинные ответы — только в потоке
Долгий запрос без стриминга может получить 504 на границе шлюза, даже если модель ещё работает. Для моделей с рассуждениями, длинных ответов и больших max_tokens включайте stream: true (при необходимости со stream_options.include_usage): поток живёт, пока приходят данные, а общий потолок одного ответа — 4 минуты. Долгая пауза без единого токена тоже обрывает соединение.
Для обычного (не потокового) ответа передайте заголовок 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, но id приходит только в полученном ответе; журнал запросов — на вкладке «Логи» в консоли разработчика. У MCP-инструмента chat свой безопасный повтор по idempotency_key. На чат действуют общие лимиты запросов и параллельности.
Параметры запроса
Свойство
Тип
Совместимость параметров
Всегда возвращается один вариант: 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 формирует структурированный ответ по инструкции без гарантии строгого соответствия схеме.
Роли сообщений
| Роль | Как обрабатывается |
|---|---|
system | системная инструкция |
developer | обрабатывается как system |
user | сообщение пользователя |
assistant | предыдущий ответ модели, в том числе с tool_calls |
tool | результат вызова инструмента, нужен tool_call_id |
| любая другая | обрабатывается как user |
Пустой messages, сообщение без строки role или запрос без model вернут 400 invalid_request_error.
Вызов инструментов
Полный цикл: вы описываете инструменты в tools, модель возвращает tool_calls, вы выполняете функцию на своей стороне и отправляете результат сообщением с role: "tool", после чего модель формирует финальный ответ.
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.
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}json_object против json_schema
response_format: { "type": "json_object" } гарантирует валидный JSON, но без конкретной схемы — и требует, чтобы слово «json» встречалось в messages. Для жёсткого соответствия структуре используйте json_schema со strict: true. В потоке схема проверяется после полного ответа: при несовпадении последний чанк придёт с ошибкой invalid_structured_output, кредиты не спишутся, но уже полученный текст отозвать нельзя.
Старый формат: POST /v1/completions
Для клиентов старого формата text-completion (например, класса OpenAI в LangChain вместо ChatOpenAI) есть POST /v1/completions: строка prompt становится единственным сообщением пользователя, ответ приходит в форме text_completion с текстом в choices[].text, идентификатор — cmpl-…. Модели, цены, стриминг, лимиты и ошибки те же, что у /v1/chat/completions.
Ошибки
Ошибки приходят в конверте 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 | исчерпан бюджет кредитов ключа на период — см. «Лимиты» |
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 | временный сбой модели, повторите запрос позже |
{
"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, — см. «Таймауты и повторы».
Ошибка внутри потока
Если сбой случился после начала потока, HTTP-статус уже 200. Тогда последний чанк перед data: [DONE] содержит finish_reason: "error" и объект error:
{
"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-статусом.
Clipia AI Gateway
Единый OpenAI-совместимый API к Claude, GPT, Gemini, DeepSeek и Grok с оплатой кредитами Clipia. Получите ключ и сделайте первый запрос за пару минут.
Модели и цены
Каталог LLM-моделей Clipia AI Gateway в GET /v1/models и цены в рублях за 1M токенов ввода и вывода — Claude, GPT, Gemini, DeepSeek и Grok.