СПРАВОЧНИК

API-референс

Полное описание всех эндпоинтов: параметры запроса, схемы ответов и примеры. Генерируется из той же спецификации, что и сам API.

Base URL — https://api.altrouter.ai/v1. Машиночитаемая спецификация: openapi.json — импортируйте в Postman, Insomnia или генератор клиентов.

Создать chat completion

POST/v1/chat/completions

Текстовые и мультимодальные ответы, с опциональным стримингом и вызовом инструментов.

Параметры тела

modelstringrequired

ID модели из каталога, например "gpt-5.4". См. GET /v1/models.

messagesarrayrequired

Диалог: массив сообщений с ролями system / user / assistant / tool. Поддерживает мультимодальный content (текст + image_url).

streambooleandefault false

Если true — ответ приходит потоком server-sent events (SSE), совместимым с OpenAI. Поток завершается строкой data: [DONE].

max_tokensinteger

Максимум токенов в ответе. Псевдоним max_completion_tokens тоже принимается. По умолчанию — серверный лимит.

Claude строго проверяет значение против своего потолка вывода (8192) и отвечает 400, если оно больше; остальные модели молча ограничивают сверху.

temperaturenumber0–2default 1

Случайность генерации. Выше — креативнее, ниже — детерминированнее.

Модели Gemini. GPT-5 и Claude сэмплинг-параметры не принимают.

top_pnumber0–1default 1

Nucleus sampling — доля вероятностной массы, из которой выбираются токены.

Модели Gemini. GPT-5 и Claude сэмплинг-параметры не принимают.

stoparray

Строка или массив строк, на которых генерация останавливается.

toolsarray

Определения функций (function calling) в формате OpenAI.

Модели с возможностью «tools».

tool_choiceobject

Управление вызовом инструментов: auto / required / none / конкретная функция.

reasoning_effortstringlow | medium | high | xhigh

Бюджет «размышлений» для reasoning-моделей. Reasoning-контент возвращается в message.reasoning_content.

Reasoning-модели, но диапазон свой у каждого семейства: gpt-5.4/5.5 — low…xhigh, gpt-5.2 — low или high, Gemini — low/medium/high, Claude — бинарно (любое значение включает размышления). Актуальный набор значений — на странице модели.

response_formatobject

Структурированный вывод: { "type": "json_object" } или { "type": "json_schema", "json_schema": … }. См. раздел Structured outputs.

Модели Gemini и GPT. Не поддерживается моделями Claude.

web_searchbooleandefault false

Веб-поиск на стороне модели: ответы с учётом свежих данных из интернета.

Все модели GPT-5.x и большинство Gemini — там, где запрос идёт через kie. Claude не поддерживает. Точный список — на странице модели.

seedinteger

Seed для воспроизводимости, где модель это поддерживает.

Только модели Gemini. GPT-5.x и Claude сэмплинг-параметры не принимают.

frequency_penaltynumber−2–2

Штраф за повтор токенов по частоте.

Только модели Gemini. GPT-5.x и Claude сэмплинг-параметры не принимают.

presence_penaltynumber−2–2

Штраф за токены, которые уже встречались.

Только модели Gemini. GPT-5.x и Claude сэмплинг-параметры не принимают.

Ответ

idstring

Идентификатор ответа.

objectstring

Всегда "chat.completion".

createdinteger

Unix-время создания (сек).

modelstring

Модель, обработавшая запрос.

choicesarray

Варианты ответа. Каждый: index, message { role, content, reasoning_content, tool_calls }, finish_reason.

usageobject

Токены: prompt_tokens, completion_tokens, total_tokens.

Пример

cURLJSON

curl https://api.altrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer ar-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.4","messages":[{"role":"user","content":"Hi"}]}'

Ошибки

400Некорректный запрос.

401Нет или неверный API-ключ.

402Недостаточно кредитов или исчерпан потолок трат ключа.

403Поверхность вне скоупов ключа.

404Модель не найдена.

429Превышен лимит запросов.

500Внутренняя ошибка шлюза.

502Ошибка на стороне модели.

503Модель временно недоступна.

504Запрос превысил допустимое время.

Создать изображение

POST/v1/images/generations

Генерация или редактирование изображения. Результат рехостится на наш CDN и возвращается ссылкой.

Параметры тела

modelstringrequired

ID image-модели из каталога, например "nano-banana-pro".

promptstringrequired

Текстовое описание желаемого изображения.

imagearray

Референсные изображения (URL или base64) для редактирования. Роутер выбирает edit-вариант модели автоматически.

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

resolutionstring1K | 2K | 4K

Тир разрешения — выбирает вариант модели и цену (quality:"hd" ⇒ 4K).

Где модель предлагает несколько разрешений.

response_formatstringurl | b64_jsondefault url

Форма результата. По умолчанию url: изображение перекладывается на наш CDN, ссылка постоянна.

Ответ

createdinteger

Unix-время создания (сек).

dataarray

Изображения. Каждое: url (ссылка на наш CDN), b64_json, revised_prompt.

Пример

cURLJSON

curl https://api.altrouter.ai/v1/images/generations \
  -H "Authorization: Bearer ar-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana-pro","prompt":"a red fox"}'

Ошибки

400Некорректный запрос.

401Нет или неверный API-ключ.

402Недостаточно кредитов или исчерпан потолок трат ключа.

403Поверхность вне скоупов ключа.

404Модель не найдена.

429Превышен лимит запросов.

500Внутренняя ошибка шлюза.

502Ошибка на стороне модели.

503Модель временно недоступна.

504Запрос превысил допустимое время.

Создать видео

POST/v1/videos

Асинхронно: запрос возвращается сразу со статусом queued, готовность опрашивается через GET /v1/videos/{id}. Резерв ставится при создании, списание — только за удавшийся рендер.

Параметры тела

modelstringrequired

ID видео-модели из каталога, например "veo-3.1-fast".

promptstringrequired

Текстовое описание сцены.

secondsinteger

Длительность клипа в секундах. Допустимые значения задаёт модель (см. её страницу), значение вне диапазона обрезается. Синоним — duration.

imagearray

Референсный кадр (URL или base64): с ним запрос уходит на image-to-video вариант модели. Для одного кадра принимается и input_reference.

Модели с image-to-video (у Hailuo 2.3 кадр обязателен).

Ответ

idstring

Идентификатор рендера (vid_…) — его опрашивают.

objectstring

Всегда "video".

statusstring

queued · in_progress · completed · failed.

created_atinteger

Unix-время создания (сек).

completed_atinteger

Unix-время завершения (сек), у терминальных статусов.

secondsinteger

Длительность, по которой посчитана цена.

urlstring

Готовый mp4 на нашем CDN — появляется при status: completed.

errorobject

Причина отказа при status: failed: { code, message }.

Пример

cURLJSON

curl https://api.altrouter.ai/v1/videos \
  -H "Authorization: Bearer ar-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"veo-3.1-fast","prompt":"a drone shot over a coastline","seconds":8}'

curl https://api.altrouter.ai/v1/videos/vid_... -H "Authorization: Bearer ar-..."

Опрос — GET /v1/videos/{id}, список последних рендеров — GET /v1/videos, редирект на готовый файл — GET /v1/videos/{id}/content.

Ошибки

400Некорректный запрос.

401Нет или неверный API-ключ.

402Недостаточно кредитов или исчерпан потолок трат ключа.

403Поверхность вне скоупов ключа.

404Модель не найдена.

429Превышен лимит запросов.

500Внутренняя ошибка шлюза.

502Ошибка на стороне модели.

503Модель временно недоступна.

504Запрос превысил допустимое время.

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

GET/v1/models

Каталог вызываемых моделей с ценами (USD) и параметрами каждой модели. Параметров запроса нет.

Ответ

Объект списка: { object: "list", data: Model[] }. Поля Model:

idstring

Идентификатор модели.

objectstring

Всегда "model".

createdinteger

Unix-время (сек).

owned_bystring

Всегда "altrouter".

surfacestring

"chat", "image" или "video".

context_lengthinteger

Размер контекста в токенах (для chat).

pricingobject

Наша цена в USD. Chat: prompt_per_1m_usd, completion_per_1m_usd. Image: per_image_usd. Video: per_second_usd или per_video_usd. Флаг approximate — цена предварительная.

paramsarray

Настраиваемые параметры модели: key, type, min/max/step или options.

Пример

cURLJSON

curl https://api.altrouter.ai/v1/models -H "Authorization: Bearer ar-..."

Ошибки

401Нет или неверный API-ключ.

Баланс кредитов

GET/v1/credits

Остаток на балансе аккаунта, которому принадлежит ключ. Параметров запроса нет.

Ответ

objectstring

Всегда "credits".

available_usdnumber

Доступно к трате (баланс за вычетом холдов), USD.

balance_usdnumber

Полный баланс, USD.

held_usdnumber

Зарезервировано незавершёнными запросами, USD.

Пример

cURLJSON

curl https://api.altrouter.ai/v1/credits -H "Authorization: Bearer ar-..."

ДалееПараметры →