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

# Совместимость с OpenAI

> Текстовые диалоги через официальный OpenAI SDK

Elumenta поддерживает OpenAI-совместимые эндпоинты для текстовых диалогов:

* `POST /v1/chat/completions` — создание ответа, в том числе в потоковом режиме;
* `GET /v1/models` — список доступных текстовых моделей в формате OpenAI.

<Warning>
  Точный базовый URL — `https://elumenta.ru/v1`. Не добавляйте `/api` или `/chat/completions`: OpenAI SDK сам добавит путь эндпоинта.
</Warning>

## Доступ

Используйте тот же API-ключ `nb_...`, что и для `/api/v2`: отдельный ключ не нужен. Доступ к API открыт на тарифе **«Продвинутый» и выше** (`t2_advanced` или `vip`, уровень 3). На более низком тарифе сервер вернёт `403` с описанием необходимого тарифа.

## Полный пример на Python

Установите официальный SDK:

```bash theme={null}
pip install openai
```

Скопируйте пример целиком и замените только API-ключ:

```python theme={null}
from openai import OpenAI

client = OpenAI(api_key="nb_...", base_url="https://elumenta.ru/v1")

response = client.chat.completions.create(
    model="gpt-5-nano",
    messages=[
        {"role": "system", "content": "Ты полезный ассистент."},
        {"role": "user", "content": "Объясни рекурсию одним предложением."},
    ],
)

print(response.choices[0].message.content)
billing = getattr(response, "elumenta", {}) or {}
print(f"Списано: {billing.get('tokens_spent', 'неизвестно')} ткн")
print(f"Баланс: {billing.get('balance', 'неизвестно')} ткн")
```

Поддерживаются роли `system`, `user` и `assistant`, а также параметры `temperature` и `max_tokens`. Последнее сообщение должно иметь роль `user`.

## Потоковый режим

Передайте `stream=True` и читайте фрагменты ответа по мере готовности:

```python theme={null}
stream = client.chat.completions.create(
    model="gpt-5-nano",
    messages=[{"role": "user", "content": "Назови три планеты."}],
    stream=True,
)

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

    billing = getattr(chunk, "elumenta", {}) or {}
    if billing:
        print(f"\nСписано: {billing.get('tokens_spent', 'неизвестно')} ткн")
        print(f"Баланс: {billing.get('balance', 'неизвестно')} ткн")
```

Объект `elumenta` приходит в финальном чанке потока. Поля `tokens_spent` и `balance` включаются только тогда, когда их значения известны, поэтому читайте их через `.get()`, как в примере выше. Объект может быть пустым — например, если для веб-сессии не запускается потоковая сверка.

## Стоимость вызова

Каждый синхронный ответ содержит два соседних объекта:

* `usage` — ровно три стандартных поля OpenAI: `prompt_tokens`, `completion_tokens` и `total_tokens`;
* `elumenta.tokens_spent` — сколько ткн фактически списано за этот вызов после сверки с реальным расходом провайдера, если значение известно;
* `elumenta.balance` — остаток на балансе после списания, если значение известно.

Любое из полей стоимости может отсутствовать, а если неизвестны оба значения, `elumenta` будет пустым объектом. В потоковом режиме полностью заполнить `usage` нельзя: событие завершения не содержит числа входных и выходных токенов. Поэтому для одинаковой формы ответа в обоих режимах поля стоимости находятся рядом с `usage` — в объекте `elumenta`, а не внутри `usage`.

В синхронном HTTP-ответе заголовок `X-RateLimit-Limit` содержит лимит запросов, а `X-Token-Balance` — остаток токенов. У потокового ответа `X-Token-Balance` нет: заголовки отправляются до завершения потока, когда окончательное списание ещё неизвестно. Актуальный остаток доступен как `elumenta.balance` в финальном чанке.

## Список моделей

```python theme={null}
models = client.models.list()
for model in models.data:
    print(model.id)
```

`GET /v1/models` следует формату OpenAI и поэтому не содержит цен: так устроена спецификация OpenAI. Цены Elumenta доступны в [`GET /api/v2/models`](/ru/api-reference/models/list).

Для изображений, видео, аудио и других возможностей используйте [универсальный Elumenta API](/ru/api-reference/generate/create).