> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Chat Completions API: запросы и потоковая передача

> Как вызывать текстовые модели LaoZhang API в формате OpenAI Chat Completions: примеры cURL и Python, потоковый ответ, поля результата и обработка ошибок.

Chat Completions от OpenAI даёт единый интерфейс к текстовым моделям OpenAI, Google Gemini, DeepSeek, Qwen и других вендоров. Отправьте `messages` и прочитайте ответ в `choices[0].message.content`.

| Параметр | Значение |
| - | - |
| Эндпоинт | `POST https://api.laozhang.ai/v1/chat/completions` |
| Модели | Те, что в [каталоге моделей](https://docs.laozhang.ai/ru/models.md) помечены в столбце **Endpoints** как OpenAI-compatible; нужную выбирайте в поле `model` |
| Потоковая передача | Укажите `"stream": true`, чтобы получать ответ по мере генерации |
| Модель в примерах | `gpt-5.4-mini` |

Необязательные параметры и поддержка инструментов зависят от модели. Если ваше приложение построено на структурах запросов Anthropic Messages или Gemini `generateContent`, используйте страницы [Протокол Claude](https://docs.laozhang.ai/ru/api-reference/claude.md) и [Протокол Gemini](https://docs.laozhang.ai/ru/api-reference/gemini.md). Три формата сравнивает руководство [API генерации текста](https://docs.laozhang.ai/ru/api-capabilities/text-generation.md).

```text theme={null}
POST https://api.laozhang.ai/v1/chat/completions
```

## Отправка запроса

Создайте API-ключ в разделе [Управление токенами](https://api.laozhang.ai/token), выбрав режим оплаты «сначала по использованию» (в консоли — 按量优先, рекомендуется) или «оплата по использованию» (按量计费), и сохраните его в переменной окружения:

```bash theme={null}
export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"
```

Запросы используют аутентификацию `Authorization: Bearer` и JSON-тело с `model` и `messages`. В примерах взята модель `gpt-5.4-mini`.

> [tab] cURL
>
> ```bash theme={null}
> curl --fail-with-body --max-time 120 \
>   "https://api.laozhang.ai/v1/chat/completions" \
>   -H "Authorization: Bearer $LAOZHANG_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "gpt-5.4-mini",
>     "messages": [
>       {"role": "user", "content": "Ответь только одним словом: connected"}
>     ]
>   }'
> ```

> [tab] Python
>
> Установите SDK командой `python -m pip install openai`.
>
> ```python theme={null}
> import os
> from openai import OpenAI
>
> client = OpenAI(
>     api_key=os.environ["LAOZHANG_API_KEY"],
>     base_url="https://api.laozhang.ai/v1",
>     timeout=120.0,
>     max_retries=0,
> )
> response = client.chat.completions.create(
>     model="gpt-5.4-mini",
>     messages=[{"role": "user", "content": "Ответь только одним словом: connected"}],
> )
> print(response.choices[0].message.content)
> ```

На этот промпт ожидается ответ `connected`. Когда клиент заработает, подставьте вместо промпта сообщение своего приложения.

## Выбор модели

Модель выбирайте в [каталоге моделей](https://docs.laozhang.ai/ru/models.md). Прежде чем менять значение `model`, проверьте в строке модели три вещи:

* В **Endpoints** есть OpenAI-compatible. Модели, у которых указан только Responses, например серия `o3-pro`, вызываются через `/v1/responses`; примеры есть в разделе про Responses API в [руководстве по подключению](https://docs.laozhang.ai/ru/api-manual.md).
* В **Token groups** есть группа вашего API-ключа.
* Цены **Input**, **Output** и **Cache read** за 1M токенов подходят вашей нагрузке.

Среди распространённых текстовых моделей каталога:

* `gpt-5.4-mini` и `gpt-5.4`
* `gemini-3.8-flash`, `gemini-3.6-flash` и `gemini-3.5-flash-lite`

Копируйте точный ID из каталога или консоли, а не собирайте его из названия продукта. Форматы и цены этих моделей перечислены в руководстве [API генерации текста](https://docs.laozhang.ai/ru/api-capabilities/text-generation.md), а то, как вызвать `o3-pro` (только Responses), показано на странице [Модели OpenAI](https://docs.laozhang.ai/ru/api-reference/openai.md).

Общий рейтинг не подскажет, какая модель подходит вашему приложению. Прогоните выборку собственных промптов через две-три модели и сравните качество ответов, следование инструкциям, структурированный вывод, долю успешных вызовов инструментов (если вы их используете), задержку и расход токенов, записанный по каждому запросу.

Зафиксируйте выбранный ID модели в конфигурации, чтобы смена модели была осознанным обновлением.

## Поля запроса

| Поле | Описание |
| - | - |
| `model` | Обязательно. Точный ID модели, доступной группе вашего токена. |
| `messages` | Обязательно. Сообщения в порядке диалога. |
| `stream` | Необязательно. `true` возвращает ответ в виде server-sent events; см. раздел о потоковом ответе ниже. |
| `temperature`, `top_p` | Необязательные параметры сэмплирования, если их поддерживает модель. |
| `max_completion_tokens` | Лимит вывода для моделей, принимающих это поле. |
| `max_tokens` | Лимит вывода, который используют некоторые модели; не передавайте оба поля лимита сразу. |
| `response_format` | Настройки формата вывода для моделей с поддержкой JSON или структурированного вывода. |
| `tools`, `tool_choice` | Описания инструментов и настройки их выбора для моделей, поддерживающих вызов инструментов. |

Начните с `model` и `messages`. Необязательные поля и допустимые значения зависят от модели; если запрос отклонён из-за неподдерживаемого параметра, перед повтором нужно изменить поле. Определения полей на стороне вендора — в [официальном справочнике Chat Completions](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create).

### Сообщения и история диалога

У каждого сообщения есть `role` и `content`. Роль `user` — ввод пользователя, `assistant` — прежние ответы модели. С каждым запросом отправляйте ту историю, которая нужна вашему приложению:

```json theme={null}
[
  {"role": "user", "content": "Мой проект называется Cedar."},
  {"role": "assistant", "content": "Чем помочь с Cedar?"},
  {"role": "user", "content": "Предложи для него короткий слоган."}
]
```

Роли инструкций вроде `system` или `developer`, сообщения инструментов и мультимодальное содержимое зависят от выбранной модели. Как передавать изображения модели с поддержкой зрения, описано в разделе [API понимания изображений](https://docs.laozhang.ai/en/api-capabilities/vision-understanding.md).

## Чтение ответа

Текстовый ответ содержит массив `choices`. В сокращённом примере показаны поля, которые нужно читать:

```json theme={null}
{
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "connected"},
      "finish_reason": "stop"
    }
  ]
}
```

Ответ находится в `message.content`, а причина завершения генерации — в `finish_reason`. Значение `length` означает, что ответ упёрся в лимит вывода или контекста; если нужен полный ответ, сократите вход или измените поддерживаемый моделью лимит вывода.

Если модель поддерживает вызов инструментов, вместо обычного текста ответ может содержать `message.tool_calls`. При продолжении диалога сохраняйте эти вызовы вместе с соответствующими результатами. Число токенов может быть в `usage`; списания по аккаунту смотрите в [журнале вызовов](https://docs.laozhang.ai/en/faq/call-logs.md).

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

Добавьте `"stream": true`, чтобы получать ответ частями по мере того, как его пишет модель. Ответ приходит как поток server-sent events:

* В каждой строке `data:` лежит объект `chat.completion.chunk`.
* Новый текст находится в `choices[0].delta.content`.
* Поток заканчивается строкой `data: [DONE]`.

> [tab] cURL
>
> Флаг `-N` отключает буферизацию вывода cURL, так что каждый фрагмент печатается сразу после получения.
>
> ```bash theme={null}
> curl --fail-with-body -N --max-time 300 \
>   "https://api.laozhang.ai/v1/chat/completions" \
>   -H "Authorization: Bearer $LAOZHANG_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "gpt-5.4-mini",
>     "stream": true,
>     "messages": [
>       {"role": "user", "content": "Дай три коротких совета по именованию переменных."}
>     ]
>   }'
> ```

> [tab] Python
>
> ```python theme={null}
> import os
> from openai import OpenAI
>
> client = OpenAI(
>     api_key=os.environ["LAOZHANG_API_KEY"],
>     base_url="https://api.laozhang.ai/v1",
>     timeout=300.0,
>     max_retries=0,
> )
> stream = client.chat.completions.create(
>     model="gpt-5.4-mini",
>     messages=[{"role": "user", "content": "Дай три коротких совета по именованию переменных."}],
>     stream=True,
> )
> for chunk in stream:
>     if not chunk.choices:
>         continue
>     text = chunk.choices[0].delta.content
>     if text:
>         print(text, end="", flush=True)
> print()
> ```

Необработанный поток выглядит так (сокращён до нужных полей; в реальных фрагментах есть и другие поля, например `id` и `model`):

```text theme={null}
data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"1. Name variables"},"finish_reason":null}]}

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```

Как читать поток:

* Добавляйте каждый `delta.content` по порядку, чтобы собрать ответ целиком.
* Первый фрагмент может содержать только роль, а в некоторых фрагментах, например в последнем фрагменте с `usage`, массив `choices` бывает пустым, поэтому проверяйте его перед чтением.
* Последний фрагмент с содержимым задаёт `finish_reason`; затем `data: [DONE]` закрывает поток, и цикл в Python SDK на этом завершается.
* Если соединение оборвалось до `[DONE]`, считайте ответ неполным.

## Обработка ошибок

| Статус | Что делать |
| - | - |
| 400 | Исправьте недопустимые поля, их типы или вход, превышающий лимит модели. |
| 401 | Проверьте заголовок Bearer и API-ключ. |
| 403 | Проверьте права группы токена и ограничения аккаунта. |
| 404 | Проверьте эндпоинт и точный ID модели. |
| 429 | Прочитайте тело ошибки: лимит запросов, параллельности, ёмкости или недостаток баланса. |
| 5xx | Посмотрите журнал вызовов и повторяйте при временных сбоях с ограниченной задержкой. |

После таймаута на стороне клиента проверьте в [журнале вызовов](https://api.laozhang.ai/log), есть ли там этот запрос, прежде чем отправлять его снова. В примерах на Python автоматические повторы отключены; добавляйте обработку повторов в приложении осознанно.

Обращаясь в поддержку, укажите время запроса, эндпоинт, модель, группу токена и текст ошибки без учётных данных. Никогда не отправляйте свой API-ключ.

## Связанные материалы

* [API генерации текста: протоколы и модели](https://docs.laozhang.ai/ru/api-capabilities/text-generation.md)
* [Использование моделей OpenAI в LaoZhang API](https://docs.laozhang.ai/ru/api-reference/openai.md)
* [Руководство по подключению](https://docs.laozhang.ai/ru/api-manual.md)
* [Модели и цены](https://docs.laozhang.ai/ru/models.md)
* [API понимания изображений](https://docs.laozhang.ai/en/api-capabilities/vision-understanding.md)
* [Models API](https://docs.laozhang.ai/en/api-reference/models.md)
* [Доступность моделей и права доступа](https://docs.laozhang.ai/en/faq/model-availability.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.