Документация OpenAI API на русском: Chat Completions по параметрам

Если вы ищете документацию OpenAI API на русском, чаще всего нужен один эндпоинт: POST /v1/chat/completions. Через него работают чат-боты, агенты и большинство интеграций, а формат давно стал общим для других поставщиков. Ниже разберём его по параметрам: что отправлять, что приходит в ответ, как читать usage и какие нюансы появляются при работе через шлюз. Полное описание всегда смотрите в официальной справке OpenAI API reference: она обновляется, а этот текст сделан как краткая шпаргалка.

Примеры идут через OpenAI SDK с адресом шлюза https://api.zukko.pro/v1. С самим OpenAI отличается только адрес и ключ, форма запроса та же. Цены ниже указаны на 18 октября 2026.

Минимальный запрос

Обязательны два параметра: model и messages.

from openai import OpenAI

client = OpenAI(base_url="https://api.zukko.pro/v1", api_key="fetch_ваш_ключ")

resp = client.chat.completions.create(
    model="gpt-6.1-sol",
    messages=[
        {"role": "system", "content": "Отвечай кратко."},
        {"role": "user", "content": "Что такое токен?"},
    ],
    max_tokens=300,
)
print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

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

messages

Каждое сообщение — объект с полями role и content. Роль system задаёт правила, user — запрос, assistant — предыдущие ответы модели, tool — результат вызова функции. Модель не помнит прошлые запросы: вся история диалога отправляется заново в каждом запросе, и именно поэтому длинные диалоги дорожают.

temperature и top_p

Документация OpenAI рекомендует менять что-то одно: либо temperature, либо top_p. Нестандартные значения принимают не все модели. В справке Zukko отдельно сказано, что новые модели Claude могут отклонять нестандартную temperature, и для них параметр лучше не передавать.

max_tokens

Ограничивает длину ответа и помогает не платить за лишнее. В справке OpenAI max_tokens помечен как устаревший в пользу max_completion_tokens, который включает и токены рассуждений. В справке Zukko описан max_tokens, поэтому используйте его, а работу max_completion_tokens на нужной модели проверьте отдельным запросом. Если ответ обрывается, смотрите finish_reason: значение length означает, что упёрлись в лимит.

stream

При stream=True ответ приходит кусками. Последний кусок перед [DONE] несёт usage и пустой массив choices, поэтому перед чтением choices[0] проверяйте, что список не пуст:

stream = client.chat.completions.create(
    model="gpt-6.1-sol",
    messages=[{"role": "user", "content": "Назови три цвета"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)
    if chunk.usage:
        print("\n", chunk.usage)

Подробнее о потоковой отдаче — в статье когда нужен stream: true↗.

tools и tool_choice

Через tools вы описываете функции JSON-схемой. Модель не выполняет их сама: она возвращает имя функции и аргументы, а выполнить вызов должен ваш код.

tools = [{
    "type": "function",
    "function": {
        "name": "get_rate",
        "description": "Курс валюты к рублю",
        "parameters": {
            "type": "object",
            "properties": {"code": {"type": "string", "description": "Код валюты, например USD"}},
            "required": ["code"],
        },
    },
}]

messages = [{"role": "user", "content": "Сколько стоит доллар?"}]

tool_choice управляет выбором: none запрещает вызовы, auto оставляет решение модели, required требует хотя бы один вызов, а объект с именем функции форсирует конкретную. Не все модели и шлюзы одинаково поддерживают форсирование, это стоит проверить на вашей модели. Различия между семействами разобраны в статье function calling у Claude, GPT и Qwen↗.

response_format

{"type": "json_object"} включает режим JSON: ответ будет валидным JSON, при этом в промпте должно быть слово JSON. {"type": "json_schema", ...} даёт структурированный вывод по схеме и в справке OpenAI называется предпочтительным там, где модель его поддерживает. Какой вариант принимает конкретная модель на шлюзе, проверяйте тестовым запросом, а результат всё равно разбирайте с обработкой ошибок.

Формат ответа

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "gpt-6.1-sol",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Токен — это ..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 30, "completion_tokens": 150, "total_tokens": 180}
}

Значения finish_reason: stop — естественное завершение, length — упёрлись в лимит, tool_calls — модель просит вызвать функцию, content_filter — сработал фильтр. Для GPT-моделей в usage может быть prompt_tokens_details.cached_tokens — сколько токенов входа прочитано из кэша.

Сколько стоит один ответ

Возьмём ответ из примера: 30 токенов входа и 150 токенов выхода на gpt-6.1-sol (вход 0,27, выход 1,32 доллара за миллион). Формула: вход × цена входа + выход × цена выхода.

30 × 0,27 / 1 000 000 + 150 × 1,32 / 1 000 000 = 0,0000081 + 0,000198 ≈ $0,000206.

Один такой ответ стоит около двух сотых цента, а затраты складываются от длины истории и ответа. Актуальный список моделей и цен: GET https://api.zukko.pro/v1/models или страница «Модели» в кабинете.

Ошибки

• 401 — неверный ключ.
• 402 — не хватает баланса.
• 403 model_not_allowed_for_key — модель не разрешена для ключа.
• 404 model_not_found — неизвестное имя модели.
• 413 — слишком большой запрос.
• 429 — исчерпан дневной или месячный лимит ключа либо ограничение у провайдера модели.
• 503 — провайдер недоступен или модель выключена (model_disabled).

Подробности — в справочнике chat completions↗. Если вы выбираете между этим эндпоинтом и /v1/responses, прочитайте сравнение двух API↗.

Частые вопросы

Чем отличается документация OpenAI от документации шлюза?

OpenAI описывает все возможности платформы, включая те, что есть только у неё: файлы, пакетную обработку, эмбеддинги. Документация шлюза описывает то, что доступно именно в нём: чат-запросы, список моделей, формат ответов и ошибки. Сверяйте параметры с ней.

Где взять ключ и адрес?

Ключ создаётся в кабинете↗, адрес для OpenAI-формата — https://api.zukko.pro/v1. Примеры из этой статьи работают из России без изменений, баланс пополняется через СБП, картой MasterCard или криптой.

Почему параметр, который работает у OpenAI, не работает у другой модели?

Параметры одинаковы по форме, но поддержка зависит от модели. Если запрос отклонён, уберите параметр и проверьте ответ, затем добавляйте по одному.

Нужно ли передавать историю диалога?

Да. Модель не хранит состояние между запросами: клиент отправляет всю историю заново.