документация

Справочник aiokno API

Всё, что нужно для интеграции: быстрый старт, модель и имена, подписка и лимиты, цены и резерв, уровни размышления, совместимость с OpenAI-контрактом, лимиты и коды ошибок. Формат — OpenAI-совместимый Chat Completions: работает любой SDK, где меняются base_url и ключ.

быстрый старт

Первый запрос — за минуту

Зарегистрируйтесь, создайте ключ в разделе «API и токены» и подставьте его в пример. Ключ показывается один раз — сохраните сразу.

curl https://aiokno.ru/api/v1/chat/completions \
  -H "Authorization: Bearer sk-aiokno-ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "aiokno-standard",
    "messages": [{"role": "user", "content": "Сколько идёт доставка до Казани?"}],
    "max_tokens": 500
  }'

Python — через официальный клиент OpenAI

from openai import OpenAI

client = OpenAI(
    api_key="sk-aiokno-ВАШ_КЛЮЧ",
    base_url="https://aiokno.ru/api/v1",
)

answer = client.chat.completions.create(
    model="aiokno-standard",
    messages=[{"role": "user", "content": "Сколько идёт доставка до Казани?"}],
    max_tokens=500,
)
print(answer.choices[0].message.content)

Библиотека обращается к base_url + /chat/completions, поэтому адрес совпадает с нашим эндпоинтом. Node.js и любой другой OpenAI-совместимый клиент настраиваются так же: меняются только ключ и базовый адрес.

модели

Одна модель, несколько имён

Имя в запросе	Что это
`aiokno-standard`	Рекомендуемое имя. За ним закреплена текущая модель проекта: если мы её обновим, менять код не придётся.
`qwen3.8-27b-fp8`	Техническое имя той же модели на сегодня.
`qwen3.6-27b-fp8`	Прежнее имя модели. Продолжает работать и ведёт на текущую модель — код, написанный до обновления, менять не нужно.

Контекст — 262 144 токена. Любое другое имя вернёт ошибку 400 invalid_model.

Каталог моделей — `GET /api/v1/models`

Эндпоинт живой и требует тот же ключ, что и запросы к модели. Первым элементом data идёт техническое имя текущей модели, за ним — её синонимы из таблицы выше; клиенты, которые берут data[0] как модель по умолчанию, попадут в актуальную. Без ключа или с отозванным ключом придёт 401 invalid_api_key. В коде удобнее оставить постоянное aiokno-standard — оно переживает смену модели.

curl https://aiokno.ru/api/v1/models \
  -H "Authorization: Bearer sk-aiokno-ВАШ_КЛЮЧ"

# Тот же клиент OpenAI, что и в быстром старте
for model in client.models.list().data:
    print(model.id)   # qwen3.8-27b-fp8, aiokno-standard, qwen3.6-27b-fp8

Подписка и лимиты

Подписка продаёт одновременные запросы — потоки, а не токены. Пока она активна, запросы любых ключей аккаунта идут без денежного резерва: баланс не трогается, 402 не приходит. Оформляется в кабинете с единого баланса, условия — на странице условий подписки.

Тариф	Потоков одновременно	Цена	На полной скорости, вычисленных токенов в сутки
1 поток	1	49 ₽ за 1 час	до 2 млн
1 поток	1	190 ₽ за 24 часа	до 2 млн
1 поток	1	940 ₽ за 7 дней	до 2 млн
1 поток	1	2 790 ₽ за 30 дней	до 2 млн
2 потока	2	98 ₽ за 1 час	до 4 млн
2 потока	2	380 ₽ за 24 часа	до 4 млн
2 потока	2	1 880 ₽ за 7 дней	до 4 млн
2 потока	2	5 580 ₽ за 30 дней	до 4 млн
3 потока	3	130 ₽ за 1 час	до 6 млн
3 потока	3	510 ₽ за 24 часа	до 6 млн
3 потока	3	2 540 ₽ за 7 дней	до 6 млн
3 потока	3	7 530 ₽ за 30 дней	до 6 млн
5 потоков	5	220 ₽ за 1 час	до 10 млн
5 потоков	5	860 ₽ за 24 часа	до 10 млн
5 потоков	5	4 230 ₽ за 7 дней	до 10 млн
5 потоков	5	12 560 ₽ за 30 дней	до 10 млн
8 потоков	8	330 ₽ за 1 час	до 16 млн
8 потоков	8	1 290 ₽ за 24 часа	до 16 млн
8 потоков	8	6 390 ₽ за 7 дней	до 16 млн
8 потоков	8	18 970 ₽ за 30 дней	до 16 млн
Пробный	1	бесплатно: 3 часа, один раз на аккаунт	до 1 млн

Сверх порога подписке до 00:00 UTC (03:00 МСК) остаётся 1 поток — без доплат и без отказов. Подписки, выданные раньше промокодом «токены в сутки», работают на 3 потоках, а прежний дневной лимит стал для них таким же порогом.

Поток — один запрос в работе

Поток занят от момента, когда шлюз принял запрос, до последнего байта ответа, включая весь стрим. Потоки считаются на аккаунт: все ключи — обычные и «Агент» — делят одно число, и один ключ может занять все потоки тарифа. Сколько запросов уходит за день, не важно — важно, сколько из них идут одновременно. Без подписки действуют лимиты оплаты за токены из раздела «Лимиты».

Очередь вместо мгновенного `429`

Если все потоки заняты, запрос не получает отказ сразу: шлюз держит его в очереди до 60 секунд и пропускает, как только поток освободится. Ожидание идёт до чтения тела запроса и до любых денежных операций. Очередь работает и без подписки — на лимитах оплаты за токены.

Мест в очереди ограниченное число — на аккаунт и на весь сервер; когда они заняты, 429 приходит сразу. Строгого порядка нет: свободный поток достаётся тому из ожидающих, кто первым его увидит, но дольше 60 секунд не ждёт никто. Таймаут клиента держите с запасом: к времени генерации может добавиться до 60 секунд очереди.

`429` по осям и `Retry-After`

Отказ по параллели приходит в обычном формате ошибки шлюза — 429 rate_limit_exceeded с заголовком Retry-After, — а текст сообщения называет ось, которая не пропустила запрос. Деньги ни на одной оси не списываются.

Ось	Когда	Что делать
Ключ и аккаунт	Все потоки подписки заняты дольше, чем длится очередь. `Retry-After: 5`	Повторить через `Retry-After` секунд; если так часто — снизить параллель клиента или взять тариф с большим числом потоков
Порог честного использования	Суточный порог пройден, и единственный оставшийся поток занят	Отправлять запросы по одному до 03:00 МСК — или дождаться сброса
Пробный пул	Пробные подписки делят общий пул потоков, и он занят. `Retry-After: 10`	Повторить позже; платный тариф в общий пробный пул не входит
Сервер	Занят общий потолок одновременных запросов к модели. `Retry-After: 10`	Повторить через `Retry-After` секунд; текущее состояние — на странице статуса

Заголовок `X-Aiokno-Streams`

Подписчику на ответах шлюза 200 и 429 приходит заголовок X-Aiokno-Streams: число потоков, которое действует прямо сейчас, по тарифу или 1 после порога честного использования. По нему клиент подстраивает свою параллель: держите одновременных запросов не больше этого числа, и очередь не понадобится. Без подписки заголовка нет.

Честное использование и вычисленные токены

Порог считается в вычисленных токенах — тех, что реально нагружают видеокарту:

вычисленные = max(0, prompt_tokens − cached_tokens) + completion_tokens

Начало запроса, взятое из кэша, почти ничего не стоит видеокарте — а агент повторяет одну и ту же историю десятки раз, — поэтому в порог оно не входит. Счётчик — за сутки по UTC, обнуляется в 00:00 UTC (03:00 МСК). После порога подписке до сброса остаётся 1 поток: денег не списываем, запросов не отклоняем, они просто идут по одному. Сколько набралось сегодня, видно в кабинете.

Пробный период

3 часа, 1 поток, порог 1 млн вычисленных токенов в сутки — один раз на аккаунт, бесплатно и без автопродления. Срок считается с запуска пробного периода кнопкой в кабинете, а не с регистрации. Пробные подписки делят общий пул потоков: если он занят, запрос ждёт в очереди, а через 60 секунд получает 429 с Retry-After. Купить платный тариф можно в любой момент; оставшееся пробное время при этом не переносится.

Покупка, продление и смена тарифа

Подписка покупается в кабинете с единого баланса; согласие с условиями подписки обязательно. Срок считается с момента покупки.
Тариф с тем же числом потоков, купленный поверх действующей подписки, добавляет свой срок к текущему: ничего не пересчитывается. При переходе на тариф с другим числом потоков оставшееся время переводится по стоимости в часы тарифа на 30 дней с новым числом потоков — с точностью до секунды, — и сверху добавляется купленный срок. Срок, сложенный из нескольких покупок с одним числом потоков, оценивается при этом целиком по самому дешёвому часу среди них. Поэтому переход на меньшее число потоков срок только удлиняет: деньги не возвращаются, времени становится больше. У перехода на большее число потоков час дороже, и новый срок может оказаться раньше нынешнего — кабинет называет его до покупки.
Остаток пробного периода при покупке тарифа не переносится. Подписка, выданная промокодом «токены в сутки», продлевается тарифом с тем же числом потоков и дальше оценивается по часу тарифа на 30 дней; при прямом переходе с неё на другое число потоков её остаток не переносится.
Переход на меньшее число потоков, который всё же сократил бы действующую подписку, сервис не проводит: приходит 409 would_shorten_subscription с обоими сроками в теле, деньги не списаны. С нынешними тарифами так бывает только у промокода с тарифом на меньшее число потоков поверх подписки, выданной промокодом «токены в сутки», — её остаток ничего не стоит. Такой промокод не тратится: активируйте его после окончания текущей подписки.
Порог честного использования считается на аккаунт за сутки по UTC; покупка и смена тарифа счётчик не сбрасывают. После окончания подписки запросы оплачиваются за токены с баланса.
Если баланса не хватает, кабинет предложит доплатить картой российского банка или через СБП (ЮKassa), и подписка оформится сама после зачисления. Пока приём платежей не подключён, по вопросам подписки — в Telegram @VCameron977: пополним баланс, а подписку вы купите в кабинете сами.
Мест на сервере конечное число. Когда новые подписки закончились, кабинет показывает «Мест нет» — продление и переход на тариф с меньшим числом потоков это не затрагивает. На время паузы продаж недоступны и покупка, и продление; действующие подписки работают до конца срока.
Тариф, снятый с продажи, в таблице выше не показан: подписка на нём действует до конца срока, и её можно продлить в кабинете — на условиях, которые карточка тарифа называет перед продлением.
Возврат за неиспользованное время — пропорционально, по заявлению; порядок — в условиях подписки.
В редком случае сбоя хранилища подписок шлюз не блокирует запрос, а проводит его как оплату за токены; при пустом балансе придёт 402. Такое списание вернём на баланс по заявлению — п. 4.6 условий.

цены без подписки

Оплата за токены — только за то, что реально использовано

входные токены

20 ₽ / 1 млн

всё, что вы отправили модели

дешевле в 10 раз входные из кэша

2 ₽ / 1 млн

повторяющееся начало запроса

выходные токены

160 ₽ / 1 млн

то, что сгенерировала модель

Расход считает наш сервер по полю usage из ответа модели, сумма округляется вверх до копейки на каждом запросе. Пример: запрос на 2 000 входных токенов с ответом на 500 выходных стоит 2000×20/1e6 + 500×160/1e6 = 0,12 ₽. Тысяча таких запросов — около 120 ₽.

Как удерживаются деньги

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

резерв = (байты тела + 8192 × число картинок) × 20 ₽/млн
       + max_tokens × 160 ₽/млн            ← округление вверх до копейки

Байты тела берутся как верхняя граница входных токенов («каждый токен весит хотя бы байт»), поэтому у запроса без картинок потолок резерва задаёт тип ключа:

Тип ключа	Резерв на один запрос без картинок	Рекомендуемый запас
Обычный API	до 8,45 ₽ — предельный запрос: тело 256 КБ, ответ 20 000 токенов	от 300 ₽
Агент (агентные клиенты)	до 52,19 ₽ — предельный запрос: тело 2 МБ, ответ 64 000 токенов	от 1 000 ₽

Картинки считаются сверх этих чисел. Оценка «токенов не больше, чем байт» на изображениях не работает, поэтому на каждую часть image_url резерв закладывает 8192 входных токенов — это +0,16 ₽ к резерву за картинку, сверх потолка строки таблицы. Числа в таблице — потолок запроса без картинок; картинок в запросе не больше восьми, поэтому потолок с ними — те же числа плюс ≈1,3 ₽. Лишнее возвращается после расчёта: списывается фактический usage, а он у мелкой картинки — десятки токенов (см. лимиты).

Полные 52 ₽ агент занимает только на предельном запросе. Короткий запрос резервирует копейки: max_tokens: 1 на маленьком теле — ровно 1 копейку, и именно это число придёт в required_kopecks. А запрос без max_tokens берёт потолок 20 000 токенов и резервирует ≈3,21 ₽ — это и есть minHoldKopecks, которое показывает кабинет: сколько нужно иметь на балансе, чтобы начался запрос, не назвавший длину ответа. Если max_tokens не передан, берётся 20 000 даже для ключа «Агент».

Из этого следуют две вещи, о которых лучше знать заранее. Во-первых, при балансе меньше резерва запрос вернёт 402, даже если по факту стоил бы дешевле: точные числа приходят в теле ошибки — required_kopecks (сколько нужно зарезервировать под этот запрос) и balance_kopecks (сколько есть), обе величины в копейках. Во-вторых, каждый запрос «в полёте» держит свою долю баланса, поэтому запас должен покрывать все одновременные резервы сразу. Сколько запросов идёт параллельно, задаёт не баланс, а лимит одновременных запросов: 2 на обычный ключ, 4 на ключ «Агент» и 6 на аккаунт.

Остаток не нужно запрашивать отдельно: непотоковый ответ, за который списаны деньги, несёт заголовок X-Aiokno-Balance-Kopecks — баланс в копейках уже после списания. У успешного ответа, за который денег не сняли, заголовка нет: это запрос в рамках подписки. Отказ 402 заголовок несёт — в нём баланс до отказа, тот же, что в поле balance_kopecks тела. Идемпотентный повтор обычно несёт заголовок с балансом на момент повтора; у повтора, догнавшего ещё не завершившийся первый запрос, заголовка может не быть. В потоковом режиме заголовка может не быть.

Кэш начала запроса — и сколько он живёт

Когда начало запроса повторяется (системная подсказка, инструкция, неизменный длинный контекст), сервер модели берёт его из кэша, и такие токены считаются по цене кэша — в 10 раз дешевле обычного входа. Сколько токенов попало в кэш, видно в ответе — usage.prompt_tokens_details.cached_tokens.

Срока хранения у кэша нет. Он живёт в памяти сервера модели и обнуляется при её перезапуске или обновлении, а записи вытесняются новыми. Повтор в пределах одной сессии сервера — попадание (на длинном префиксе замерено 96 % токенов из кэша), повтор через неделю или после рестарта — полная цена входа. Считайте кэш скидкой, а не обещанной ценой: бюджет планируйте по полной ставке входа.

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

Пополнение — пока вручную

Приём оплаты картой российского банка и через СБП пойдёт через ЮKassa, но ещё не подключён. Пока баланс зачисляет оператор промокодом: напишите в Telegram или на почту — обычно подтверждаем в течение рабочего дня. Баланс на аккаунте один: с него оплачивается и API — подписка и токены, — и тариф программы.

уровни размышления

Модель умеет думать перед ответом — вы решаете, сколько

Поле reasoning_effort управляет внутренним рассуждением модели. По умолчанию оно выключено — ответ приходит сразу и дешевле. Включите уровень — и модель сначала разберёт задачу по шагам: ход рассуждения вернётся в отдельном поле reasoning, а чистый ответ — как обычно в content.

`reasoning_effort`	Что происходит	Когда выбирать
`none` (по умолчанию)	Без размышления — модель отвечает сразу	Чат-боты, классификация, извлечение данных, короткие ответы
`low`	Короткая прикидка перед ответом	Простая математика, проверка условий
`medium`	Развёрнутый разбор задачи	Многошаговые задачи, анализ текста
`high`	Максимальное усилие (наибольший объём рассуждения)	Сложная логика, код, планирование

answer = client.chat.completions.create(
    model="aiokno-standard",
    messages=[{"role": "user", "content": "Реши: у поезда 9 вагонов..."}],
    reasoning_effort="medium",
    max_tokens=4000,
)
print(answer.choices[0].message.reasoning)  # ход рассуждения
print(answer.choices[0].message.content)    # чистый ответ

Как это тарифицируется. Токены размышления — обычные выходные токены (160 ₽ за миллион): они входят в usage.completion_tokens и ограничены вашим max_tokens вместе с ответом. Отсюда практическое правило: с включённым размышлением ставьте max_tokens с запасом (от 2 000) — если бюджета не хватит, модель потратит его на рассуждение и вернёт пустой content с finish_reason: "length". Значение вне списка вернёт 400 invalid_reasoning_effort — до списания.

совместимость

Что из OpenAI-контракта работает

Таблица собрана внешней приёмкой на живом шлюзе 6 сентября 2026: каждая строка — выполненный запрос, а не намерение. Где поведение менялось в тот же день, это отмечено в строке.

Возможность	Как ведёт себя
`tools` — вызов функций	один и несколько вызовов за ответ, дельты в потоке, ответ инструмента обратно в истории (`role: "tool"`)
`tool_choice`	`auto`, `none`, `required` и именованная функция. `required` и именованный выбор принуждают вызов с 6 сентября 2026 — до этого модель могла ответить текстом
`response_format`	`json_object` и `json_schema`
`logprobs`, `top_logprobs`	возвращаются
`stop`	строка и массив строк
`seed`, `temperature`, `top_p`, `presence_penalty`, `frequency_penalty`, `logit_bias`	принимаются; при `temperature: 0` и одном `seed` ответы совпадают
`stream`	SSE как у OpenAI; рассуждение тоже приходит дельтами, в том числе вместе с вызовами функций
Картинки (`image_url`)	только `data:`-URI (base64 в теле): принимаются, тарифицируются как входные токены, не больше 8 на запрос. Внешняя ссылка — `400`. Резерв — в лимитах
Длинный контекст	проверено до 60 000 входных токенов в одном запросе; выше упирается в размер тела

Не поддержано: embeddings, генерация изображений (/v1/images/generations), Responses API, старый /v1/completions, несколько вариантов ответа (n, best_of), выбор из нескольких моделей и звук с видео на вход (audio_url, video_url, input_audio — модель текстово-зрительная, такие части возвращают 400).

лимиты

Границы, в которых работает шлюз

Что	Значение
Размер тела запроса	до 256 КБ; ключ «Агент» — до 2 МБ. Больше — `413`
Длина ответа	`max_tokens` или `max_completion_tokens` до 20 000; ключ «Агент» — до 64 000. Не передали — берётся 20 000. Значение — целое ≥ 1, иначе `400`
Частота	120 запросов в минуту с одного IP-адреса
Ключей на аккаунт	до 10 активных одновременно
Каталог моделей	`GET /api/v1/models` с тем же ключом — см. раздел «Модели»
Повтор запроса без двойного списания	заголовок `Idempotency-Key`, см. ниже
Контекст модели	262 144 токена
Время ожидания ответа	до 25 минут (долгая генерация с рассуждением); в потоковом режиме первые токены приходят сразу
Потоковая передача (`stream`)	поддерживается: `stream: true` отдаёт ответ по мере генерации (SSE, как у OpenAI). `usage` приходит ровно один раз — в финальном чанке с пустым `choices: []`, и только если передать `stream_options: {"include_usage": true}`. Контентные чанки поля `usage` не несут: суммировать их не нужно и нечего
Рассуждения (reasoning)	по умолчанию выключены; включаются полем `reasoning_effort`
Несколько вариантов (`n`, `best_of`)	всегда один ответ
Картинки на вход	принимаются в поле `image_url` только как `data:`-URI и не больше 8 частей на запрос (считаются по всему телу, вместе с историей); списываются по факту, резервируются с запасом — см. абзац «Про картинки» под таблицей

Про длину ответа. Модель выдаёт около 60 токенов в секунду, потолок ожидания — 25 минут, так что максимальные 20 000 токенов ответа успевают сгенерироваться с запасом. Для долгих ответов удобнее stream: true — текст приходит по мере генерации. Обрыв оплачивается по тому, что модель успела сгенерировать к моменту, когда шлюз узнал о разрыве. Разрыв — это закрытие соединения клиентом: через край сети он доходит до шлюза за 1–2 секунды, то есть плюс до ~100 токенов сверх прочитанного (замер 7 сентября 2026: 23 токена напрямую, 91 через край). Если клиент просто перестал читать поток, не закрыв соединение, модель догенерирует ответ до конца или до max_tokens — и это будет списано целиком.

Про пустой ответ. Без режима рассуждения модель иногда завершала ответ первым же токеном: 200, finish_reason: stop, пустой content и одна копейка за ничего. С 8 сентября 2026 шлюз всегда передаёт модели min_tokens (по умолчанию 2, ваше значение уважается, но не больше max_tokens) — первый токен не может быть концом ответа. Если пустой ответ всё же пришёл, пришлите X-Request-Id.

Про счётчики. max_tokens, max_completion_tokens и n обязаны быть целыми числами не меньше 1. Ноль, дробь, строка и отрицательное значение возвращают 400 invalid_request_error — до того, как с баланса что-то резервируется. Отсутствующее поле и явный null по-прежнему означают «не задано»: тогда берётся 20 000 токенов — в том числе для ключа «Агент», его 64 000 нужно попросить явно.

Про картинки. Изображение передаётся частью image_url и только как data:image/…;base64,… строго в нижнем регистре (DATA:, IMAGE/, BASE64 — 400) (base64 прямо в теле запроса): ссылку на внешний адрес шлюз отклоняет 400 invalid_request_error — до резерва и до вызова модели. Картинок в одном запросе — не больше 8, и считаются они по всему телу, вместе с историей переписки; девятая — тоже 400. Списывается изображение по факту, из usage: замер приёмки 6 сентября 2026 — +66 входных токенов на картинку, одинаково для 1×1, 64×64 и 256×256; более крупные не измерялись и могут стоить дороже. Резерв заранее факт не знает, поэтому закладывает 8 192 входных токенов на каждую часть image_url (≈0,16 ₽) и возвращает лишнее после расчёта. Этот запас идёт сверх потолков из раздела «Цены»: предельные восемь картинок поднимают резерв примерно на 1,3 ₽.

Про размер запроса. Контекст модели — 262 144 токена, но тело запроса обычного ключа ограничено 256 КБ (ключ типа «Агент» — 2 МБ), поэтому реально в запрос помещается меньше. Тело больше потолка возвращает 413 payload_too_large — с телом ошибки и заголовком X-Request-Id, на любом превышении, вплоть до нескольких байт за границей.

Текущее состояние сервисов — на странице статуса. Частота считается по IP-адресу, а не по ключу: несколько ключей с одного сервера делят общий лимит. При превышении приходит 429 с заголовком Retry-After — повторяйте с экспоненциальной задержкой. Тот же 429 приходит и на слишком много одновременных запросов: без подписки по одному ключу — 2 (обычный) и 4 («Агент»), и не больше 6 на аккаунт, а у подписки — число потоков тарифа. Сначала такой запрос до 60 секунд ждёт свободного места в очереди, и 429 приходит, только если место не освободилось; деньги при этом не списываются.

Поля запроса, которые сервер меняет сам

Несколько полей OpenAI-контракта сервер обрабатывает сам. Ошибку они не вызывают — запрос выполняется без них:

chat_template, mm_processor_kwargs, prompt, echo, documents — вырезаются молча: сборку промпта на сервере мы наружу не отдаём.
n и best_of — приводятся к одному варианту ответа (сам n при этом обязан быть целым ≥ 1, иначе 400).
max_tokens и max_completion_tokens — зажимаются в потолок вашего ключа; если переданы оба, берётся меньшее.
cache_salt — серверный: именно он разделяет кэш между аккаунтами.
stream_options — в потоке сервер сам включает подсчёт usage (иначе нечем подтвердить списание при обрыве), но usage-чанк приходит вам, только если вы попросили его сами.

Поля управления шаблоном add_generation_prompt и continue_final_message отвергает сама модель — 400 invalid_request_error.

Повтор запроса без двойного списания — `Idempotency-Key`

OpenAI-совместимые SDK сами повторяют POST на 408, 429 и 5xx. Если первый запрос успел сгенерироваться и списаться, а ответ до вас не дошёл, «безопасный» повтор запустил бы вторую генерацию и второе списание. Чтобы этого не случилось, передайте свой уникальный идентификатор запроса в заголовке Idempotency-Key.

curl https://aiokno.ru/api/v1/chat/completions \
  -H "Authorization: Bearer sk-aiokno-ВАШ_КЛЮЧ" \
  -H "Idempotency-Key: 8f14e45f-ea0b-4c1e-9f8a-0b7c2f1d3e55" \
  -H "Content-Type: application/json" \
  -d '{"model":"aiokno-standard","messages":[{"role":"user","content":"Привет!"}]}'

Заголовок необязателен — без него всё работает как раньше.
Действует только на непотоковые запросы: поток не переигрывается.
Запоминаются только успешные ответы, и живут они 24 часа; после этого тот же ключ снова считается новым.
Повтор с тем же ключом отдаёт сохранённый ответ бесплатно и помечает его заголовком Idempotent-Replay: true; в X-Request-Id при этом приходит идентификатор первого запроса — по нему и ищется списание.
Один ключ — один запрос: тот же ключ с другим телом вернёт 422 idempotency_key_reuse, а не чужой ответ. Генерируйте новый идентификатор на каждый логически новый вызов.
Область действия — аккаунт, а не отдельный API-ключ: тот же Idempotency-Key с другим ключом того же аккаунта отдаст сохранённый ответ и не спишет деньги повторно (замена ключа посреди ретраев не должна приводить ко второй генерации). У другого аккаунта тот же идентификатор независим — чужой ответ не отдаётся никогда.
Пока первый запрос с этим ключом ещё выполняется, второй получит 409 idempotency_in_progress с Retry-After — дождитесь ответа вместо параллельного повтора.
Длина ключа — до 255 символов, иначе 400 invalid_request_error; нижней границы нет, но берите UUID — короткий идентификатор легко столкнётся с вашим же прошлым запросом.

коды ошибок

Что означает ответ и что с ним делать

Все ошибки приходят в привычном виде {"error":{"code":"…","message":"…"}}. На каждом ответе шлюза — и успешном, и ошибочном — есть заголовок X-Request-Id: назовите его в обращении, и мы найдём запрос в логах. Заголовок ставится в самом начале обработки, поэтому он есть и там, куда запрос не дошёл: 404 на несуществующий путь, 405 на неверный метод, 429 от ограничителя частоты. Единственное исключение — редкий обрыв соединения между краем сети и шлюзом: тогда приходит голый 502 без нашего формата и без заголовка. Денег такой ответ не списывает (списывать нечего — usage нет), запрос можно повторить.

Код	Что означает	Что делать
401 `invalid_api_key`	Ключ отсутствует, отозван или не начинается с `sk-aiokno-`	Создать новый ключ в кабинете
402 `insufficient_balance`	На балансе меньше, чем требуется зарезервировать. В теле — точные числа: `required_kopecks` и `balance_kopecks`	Пополнить баланс (см. раздел «Цены»)
400 `invalid_model`	Запрошена неизвестная модель	Использовать `aiokno-standard`
400 `invalid_request_error`	Тело — не JSON-объект, либо модель отвергла параметры (роль, `top_p`, отсутствующий `messages`)	Поправить тело запроса. Повтор без изменений не поможет
413 `payload_too_large`	Тело больше 256 КБ; для ключа «Агент» — больше 2 МБ. Приходит с телом ошибки и `X-Request-Id` на любом превышении, вплоть до нескольких байт за границей	Сократить историю сообщений
400 `invalid_reasoning_effort`	`reasoning_effort` вне списка `none`/`low`/`medium`/`high`	Взять значение из таблицы уровней. Деньги не списываются
409 `too_many_keys`	Уже 10 активных ключей на аккаунт	Отозвать ненужный ключ в кабинете
422 `idempotency_key_reuse`	Присланный `Idempotency-Key` уже использован с ДРУГИМ телом запроса — чужой ответ мы не отдаём	Взять новый ключ. Повтор без изменений не поможет
409 `idempotency_in_progress`	Запрос с этим `Idempotency-Key` ещё выполняется	Подождать `Retry-After` секунд и повторить
503 `server_misconfigured`	Сервер модели не настроен	Написать нам, это на нашей стороне
429 `rate_limit_exceeded`	Либо слишком часто с одного адреса (по умолчанию 120 запросов в минуту), либо все одновременные запросы ключа или аккаунта (у подписки — все потоки) заняты дольше, чем длится очередь, либо модель перегружена. Ось называет текст сообщения — см. «429 по осям»	Подождать `Retry-After` секунд. Деньги не списываются
502 `upstream_unavailable`	Сбой на НАШЕЙ стороне: недоступен бэкенд модели (туннель, ключ сервера, имя модели)	Повторить позже — сначала загляните на страницу статуса. Деньги не списываются, тело запроса менять не нужно
504 `upstream_timeout`	Модель не уложилась во время ожидания	Повторить, а если ответ длинный — уменьшить `max_tokens`. Деньги не списываются
502 `upstream_error`	Модель не ответила либо ответила неразборчиво — без блока `usage` списывать нечего	Повторить; если повторяется — проверить статус сервисов. Деньги не списываются
503 `server_unavailable`	Временно недоступно хранилище	Повторить позже; текущее состояние — на странице статуса

Ошибки кабинета — другой формат

Эндпоинты кабинета (/api/account/*: вход, ключи, баланс, промокоды, подписка) обслуживают сам сайт и отвечают плоской строкой {"error":"код"} — без вложенного объекта, как у шлюза. Неизвестные поля тела они игнорируют; создание ключа отвечает 201 Created. Частые коды:

Ответ	Когда приходит
401 `unauthenticated`	нет сессии кабинета или она истекла
401 `invalid_credentials`	неверная пара почта / пароль
400 `invalid_json`	тело не разобралось как JSON
400 `invalid_request`	обязательное поле тела отсутствует или пусто — например, `newPassword` у `/password-set` и `/password-change`
415 `unsupported_media_type`	тело прислано без `Content-Type: application/json`
400 `consent_required`	регистрация без согласия на обработку данных
400 `invalid_email`, 409 `email_taken`	адрес не разобран или уже занят
400 `weak_password`	пароль короче 8 или длиннее 200 символов
409 `password_already_set`	`/password-set` нужен аккаунту без пароля (вход через Telegram); когда пароль уже есть, его меняют через `/password-change`. Поле нового пароля в обоих — `newPassword`
400 `invalid_scope`	тип ключа не `api` и не `agent`
409 `too_many_keys`	уже 10 активных ключей на аккаунте; выдача ключей идёт по своему бюджету, поэтому потолок достижим подряд, без пауз
404 `not_found`	отзыв чужого или уже отозванного ключа
400 `invalid_code`, 409 `already_redeemed`, 410 `expired`	промокод не найден, уже активирован или просрочен
409 `plan_unavailable`, 409 `would_shorten_subscription`	промокод с тарифом: тарифа больше нет в каталоге (снятый с продажи тариф код по-прежнему выдаёт) либо код с тарифом на меньшее число потоков сократил бы действующую подписку (в теле — `expiresUtc` и `wouldExpireUtc`). Код не потрачен — его можно активировать позже
402 `insufficient_balance`	покупка подписки: на балансе меньше цены тарифа; в теле — `requiredKopecks`, `balanceKopecks` и `shortfallKopecks`
400 `unknown_plan`, 400 `offer_not_accepted`	покупка подписки или пробный период: тариф не найден или не продаётся (снятый с продажи тариф продлевает только его держатель) либо не передано согласие с офертой (`acceptOffer: true`)
409 `would_shorten_subscription`	покупка подписки: переход на меньшее число потоков закончился бы раньше действующей подписки; в теле — `expiresUtc` (срок действующей) и `wouldExpireUtc` (срок после покупки). Ничего не списано
409 `sold_out`, 409 `idempotency_conflict`	покупка подписки: мест нет либо тот же `idempotencyKey` уже использован для другого тарифа
409 `trial_used`, 409 `already_active`	пробный период уже был на этом аккаунте либо подписка уже активна
503 `sales_disabled`, 503 `trial_disabled`	продажа подписок или пробный период временно выключены; действующие подписки работают
503 `payments_not_configured`	пополнение картой: приём платежей не подключён
400 `invalid_intent`, 400 `offer_not_accepted`, 400 `unknown_plan`, 503 `sales_disabled`, 409 `would_shorten_subscription`	пополнение с намерением купить подписку: намерение не разобрано, нет согласия с условиями, тариф не продаётся, продажи на паузе или переход на меньшее число потоков сократил бы действующую подписку — всё это до создания платежа, деньги не списаны
429 `rate_limited`	слишком часто: вход и регистрация — 20 попыток за 10 минут с адреса, создание ключей — 30 за 10 минут на аккаунт. Ответ несёт `Retry-After` и поле `retryAfterSeconds`
503 `storage_unavailable`	база кабинета временно недоступна

границы раннего доступа

Что мы обещаем и чего пока не обещаем

Обещаем

Ключ выдаётся сразу, без ожидания
Вызов функций (tools) и картинки на вход
Списание — по usage из ответа модели
При ошибке модели деньги не списываются
Запросы обрабатываются в России
X-Request-Id для разбора любого списания

Пока не обещаем

Соглашение об уровне сервиса (SLA)
Выбор из нескольких моделей
Генерация изображений
Оплата картой без участия оператора
Круглосуточная поддержка

Данные запросов

Текст запроса уходит на наш сервер в России — иначе модель не сможет ответить. Мы не используем ваши запросы для обучения. При этом сервер модели ведёт технический журнал, поэтому не отправляйте в API персональные данные и секреты, пока мы не закроем этот пункт отдельно.

вопросы по интеграции

Коротко о главном

Подойдёт ли мой код, написанный под OpenAI?

Да, если он использует Chat Completions. Достаточно поменять api_key и base_url на https://aiokno.ru/api/v1.

Работает: вызов функций (tools, tool_choice — auto, required и по имени), картинки на вход (image_url с data:-URI), response_format (включая json_schema), seed, stop, logprobs, штрафы и temperature/top_p.

Не сработает: embeddings, генерация изображений (/v1/images/generations), Responses API и старый /v1/completions. Построчно проверенная таблица — в разделе «Совместимость».

Почему пришёл 402, если на балансе есть деньги?

Перед запросом резервируется максимально возможная стоимость этого запроса: вход по размеру тела плюс max_tokens по цене вывода. Запрос без max_tokens берёт потолок 20 000 токенов и резервирует ≈3,21 ₽; предельный запрос без картинок — 8,45 ₽ у обычного ключа и 52,19 ₽ у ключа «Агент», а каждая часть image_url добавляет к резерву ещё ≈0,16 ₽ сверх этих чисел. Если баланса не хватает на резерв, запрос отклоняется, даже когда по факту он стоил бы дешевле; сколько именно нужно на этот запрос, видно в теле ответа — required_kopecks и balance_kopecks. Пополните баланс: рекомендуемый запас — от 300 ₽ для обычного ключа и от 1 000 ₽ для агента. Разбор резерва — в разделе «Цены». У активной подписки резерва нет, и такой 402 ей не приходит.

Как посчитать расход самостоятельно?

В ответе есть блок usage с числом входных и выходных токенов. Умножьте их на цены из раздела «Цены». В личном кабинете тот же расход показывается по дням, там же виден остаток баланса.

Что будет, если модель не ответит?

Придёт 502 (или 504, если модель не уложилась во время ожидания), резерв вернётся на баланс полностью — за такой запрос вы не платите. Отдельный код 502 upstream_unavailable означает, что сломалось на нашей стороне и тело запроса менять не нужно. Повторите запрос; если ошибка держится, напишите нам и назовите X-Request-Id.

Можно ли получить счёт и закрывающие документы?

Пока нет: продажа идёт в раннем доступе, оплату подтверждает оператор вручную. Если нужны документы для юридического лица — напишите, обсудим отдельно.

ранний доступ

Ключ — в личном кабинете

Регистрация занимает минуту, ключ создаётся сразу. Начните с пробной подписки — 3 часа бесплатно — или пополните баланс промокодом.

Открыть кабинет

По вопросам подписки и баланса — в Telegram @VCameron977