Чат и стриминг

POST /v1/chat/completions — основной эндпоинт. Формат запроса и ответа повторяет OpenAI, поэтому работает любой совместимый SDK.

Параметры

Поле	Тип	Описание
`model`	string, обязательное	Идентификатор из `GET /models` или псевдоним (`gpt-4o`, `claude-opus`)
`messages`	array, обязательное	История диалога; последнее сообщение пользователя — это промпт
`stream`	boolean	`true` — ответ приходит по SSE
`stream_options`	object	`{"include_usage": true}` добавит финальный чанк с расходом токенов
`temperature`	number	Как у OpenAI. Принимают не все модели: у GPT-5.x/5.6/6 и Claude его нет — проверьте `supported_parameters` в `GET /models`
`max_tokens`	integer	Потолок длины ответа
`max_completion_tokens`	integer	Синоним `max_tokens` для новых SDK
`reasoning_effort`	string	Глубина рассуждения: `off`, `low`, `medium`, `high`, `xhigh` или `max` — набор зависит от модели, см. режимы рассуждения. Для роутеров (`typesafe/jev-router`) — подсказка: роутер выбирает уровень сам и может её переопределить
`tools`	array	Описания инструментов в формате OpenAI; передаются модели как есть — как готовить
`tool_choice`	string \| object	`auto`, `none`, `required` или конкретный инструмент
`web_search`	bool \| string	`true`/`"auto"` — нативный поиск модели, где есть, иначе Exa; `"native"`/`"exa"` — явно. Источники — в `message.annotations`; подробно — веб-поиск
`response_format`	object	`{"type": "json_object"}` или `{"type": "json_schema", …}` — гарантированный JSON — структурный вывод
`stop`	array	До 4 стоп-последовательностей: генерация прекращается, как только в ответе встретилась одна из них
`seed`	integer	Зерно сэмплирования — best-effort воспроизводимость ответов
`top_p`	number 0–1	Ядерная выборка: рассматриваются только самые вероятные токены, набирающие эту долю вероятности
`top_k`	integer	Оставить K самых вероятных токенов. Есть у моделей с открытыми весами
`min_p`	number 0–1	Отбросить токены ниже этой доли от вероятности лидера
`frequency_penalty`	number −2…2	Штраф тем больше, чем чаще токен уже встречался
`presence_penalty`	number −2…2	Штраф за сам факт появления токена
`repetition_penalty`	number 0–2	Штраф за повторение промпта и написанного ответа
`logprobs`	boolean	Вернуть логарифмы вероятностей выбранных токенов
`top_logprobs`	integer 0–20	Сколько альтернатив на позицию вернуть; требует `logprobs`
`provider`	object	Выбор маршрута: `order`, `only`, `ignore`, `sort` — выбор провайдера
`service_tier`	string	`flex` — дешевле и медленнее, `priority` — дороже и быстрее; тир есть не у всех моделей
`plugins`	array	Плагины апстрима как есть; для `typesafe/jev-router` — свой пул моделей: `[{"id": "jev-router", "models": ["anthropic/", "openai/gpt-6"]}]` (поля `models`/`allowed_models`, `excluded_models`, `cost_tier`)

Набор принимаемых параметров у моделей разный: апстрим отбрасывает то, чего модель не знает, вместо ошибки. Фактический список каждой модели — в поле supported_parameters ответа GET /models.

Роутеры

typesafe/jev-router сам выбирает модель и глубину размышления под каждый запрос — фактическая модель приезжает в поле served_model ответа (в стриминге — отдельный чанк с пустым choices перед usage-чанком). Поле появляется только когда фактическая модель отличается от запрошенной. Списание — по тарифу выбранной модели.

Стриминг

stream = client.chat.completions.create(
    model="gpt-5.6-luna",
    messages=[{"role": "user", "content": "Напиши хайку про дедлайн"}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

const stream = await client.chat.completions.create({
  model: 'gpt-5.6-luna',
  messages: [{ role: 'user', content: 'Напиши хайку про дедлайн' }],
  stream: true,
  stream_options: { include_usage: true },
})
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '')
}

curl -N https://api.mixen.ai/v1/chat/completions \
  -H "Authorization: Bearer $MIXEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-luna",
    "messages": [{"role": "user", "content": "Напиши хайку про дедлайн"}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

Поток идёт как text/event-stream и завершается строкой data: [DONE]. С include_usage перед ней придёт чанк с usage — по нему удобно логировать расход: там же cost / cost_rub — сколько списалось за запрос (см. Токены и списания).

В usage есть и prompt_tokens_details.cached_tokens — сколько входных токенов пришло из кэша контекста. Подробнее — Кэширование контекста.

Изображения на вход

Модели с capabilities.vision: true принимают картинку в составе сообщения:

resp = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Что не так на этом графике?"},
            {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KG..."}},
        ],
    }],
)

Принимаются только data:-URL (data:image/png;base64,...) в последнем сообщении пользователя — внешние HTTP-ссылки не поддерживаются, картинку нужно закодировать в base64.

Файлы на вход

Модели с capabilities.file: true принимают до 5 файлов на запрос. Форматы: PDF, DOCX, TXT, CSV, XLSX, PPTX — текст извлекается и уходит модели как контекст:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Сделай выжимку по разделу «Риски»"},
    {"type": "file", "file": {"filename": "report.pdf", "file_data": "data:application/pdf;base64,JVBERi0..."}}
  ]
}

Из каждого файла берётся не более 150 000 символов; длинные обрезаются, в конец добавляется маркер [...truncated]. OCR не выполняется: PDF-скан без текстового слоя даст пустой результат — нужны документы с текстовым слоем.

Если модель не умеет читать файлы, запрос вернёт 400 — проверяйте флаг в каталоге заранее.

Аудио на вход

Модели с входом-аудио (в каталоге — capabilities.audio: true, например google/gemini-4-argon) принимают звук content-частью input_audio:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Расшифруй запись и перечисли договорённости"},
    {"type": "input_audio", "input_audio": {"data": "//uQx...", "format": "mp3"}}
  ]
}

В data — голый base64 без префикса data:audio/...;base64, (в отличие от картинок), формат — отдельным полем: mp3, wav, flac, pcm16. Аудио-токены тарифицируются отдельной ставкой входа-аудио (у мультимодальных моделей она может отличаться от текстовой — см. панель «Провайдеры» на карточке модели); повторные запросы с тем же аудио попадают под кэш аудио со скидкой.

Режимы рассуждения

У части моделей есть управляемая глубина рассуждения. Допустимые значения приходят в capabilities.reasoning_efforts — обычно это low, medium, high, xhigh, max.

{"model": "claude-opus-4.8", "reasoning_effort": "high", "messages": [...]}

Два подводных камня:

Рассуждение съедает бюджет max_tokens. Если ждёте длинный JSON от модели с включённым рассуждением, ставьте потолок с запасом — иначе ответ обрежется на середине. Обрезку видно в ответе: finish_reason: "length" (в /v1/messages — stop_reason: "max_tokens"), так что её можно поймать программно и продолжить генерацию.
Отключить рассуждение можно не везде: смотрите capabilities.can_disable_reasoning. Если там false, модель думает всегда, и это отражено в цене.

Веб-поиск

Модели с type: search (семейство Perplexity Sonar) ходят в интернет сами — отдельного эндпоинта или инструмента не нужно, просто укажите такую модель:

curl https://api.mixen.ai/v1/chat/completions \
  -H "Authorization: Bearer $MIXEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"sonar-pro","messages":[{"role":"user","content":"Что нового вышло у Anthropic за неделю?"}]}'

Для ключа с ограниченными областями доступа такие модели требуют область search, а не chat.

Параметр web_search — поиск у любой модели

Веб-поиск можно включить и любой другой текстовой модели — параметром web_search:

{
  "model": "google/gemini-3.8-flash",
  "web_search": "native",
  "messages": [{"role": "user", "content": "Курс доллара ЦБ сегодня? Одна строка с источником"}]
}

Значения: true/"auto" — нативный поиск модели, где он есть, иначе Exa; "native" — встроенный поиск провайдера; "exa" — нейтральный поиск. Нативный поиск есть у моделей OpenAI, Anthropic, Google и xAI — в каталоге это capabilities.native_search: true; источники приходят в message.annotations (url_citation) как у Sonar. В стриминге они приезжают отдельным чанком с delta.annotations перед финальным чанком с finish_reason. "native" у модели без встроенного поиска автоматически понижается до "auto". Тарификация, резерв на балансе и поведение Sonar — в гайде Веб-поиск.

Поиск оплачивается отдельно за каждый выполненный запрос (не за токены): цена видна в каталоге рядом с моделью (поле web_search_rub_per_request в GET /v1/models). Модель сама решает, нужен ли поиск и сколько раз его звать — по вопросу «что такое дробь» поиска не будет.

Другие протоколы

Помимо /v1/chat/completions, на том же ключе и балансе работают ещё два чат-протокола:

POST /v1/messages — Anthropic-совместимый (Claude Code, Anthropic SDK): принимает thinking.budget_tokens, cache_control и tool-use; есть POST /v1/messages/count_tokens. Подробнее — Claude Code.
POST /v1/responses — OpenAI Responses API (Codex CLI): stateless, принимает reasoning.effort. Подробнее — Codex CLI.