Перейти к содержимому

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-схеме.

POST/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-статусом.

СтатусcodetypeКогда
400invalid_request_errorinvalid_request_errorнекорректное тело: нет model, пустой messages, неверная JSON-схема в response_format
400context_length_exceededinvalid_request_errorввод больше контекста модели; проверяется до списания
400max_tokens_too_largeinvalid_request_errormax_tokens больше 200 000; param указывает поле
400invalid_request_errorinvalid_request_errortemperature/top_p вне диапазона, n ≠ 1, tools больше 256 КБ или модель отклонила параметры запроса; проверяется до списания
401invalid_api_keyinvalid_request_errorключа нет, он неверный или отозван
402insufficient_quotainsufficient_quotaне хватает кредитов на балансе
402subscription_requiredinsufficient_quotaдля модели нужна активная подписка
402insufficient_quotainsufficient_quotaисчерпан бюджет кредитов ключа на период — см. «Лимиты»
403insufficient_scope или permission_errorinvalid_request_errorу ключа нет права или запрос не разрешён
404model_not_foundinvalid_request_errorнеизвестный или недоступный model
409idempotency_key_reuse или request_in_progressinvalid_request_errorтот же Idempotency-Key с другим телом или повтор, пока первый запрос ещё выполняется
422model_input_invalidinvalid_request_errorмодель отклонила запрос по содержанию; переформулируйте ввод
429rate_limit_exceeded или concurrency_limit_exceededrate_limit_errorпревышен лимит запросов, токенов или параллельности
500, 502, 503, 504nullapi_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-статусом.