CloseRouter API

Документация CloseRouter API

Короткая документация по публичному inference API: модели, запросы, ключи, баланс и ошибки.

Скачать .mdAPI-ключиМодели
Base URL
https://api.closerouter.dev/v1
Авторизация
Authorization: Bearer closerouter_...
Каталог
GET /models

Модели

Каталог показывает публичные ID моделей, цены, modalities, поддерживаемые параметры и endpoint-ы.

Получить каталог

curl
export CLOSEROUTER_API_KEY="closerouter_your_key"

curl https://api.closerouter.dev/v1/models \
  -H "Authorization: Bearer $CLOSEROUTER_API_KEY"

Разработчики, фильтр и пагинация

Сначала получите компактный список разработчиков, затем фильтруйте плоский каталог по точным slug. Пагинация включается только при передаче limit.

curl
curl https://api.closerouter.dev/v1/model-authors \
  -H "Authorization: Bearer $CLOSEROUTER_API_KEY"

curl "https://api.closerouter.dev/v1/models?model_authors=anthropic,openai&limit=50&offset=0" \
  -H "Authorization: Bearer $CLOSEROUTER_API_KEY"

Catalog endpoint-ы

GET /models

Каталог моделей, цены, modalities и поддерживаемые endpoint-ы.

GET /models/count

Количество доступных моделей.

GET /model-authors

Компактный список разработчиков и количество их видимых моделей.

GET /models/{provider}/{model}/endpoints

Параметры и streaming для одной модели.

GET /providers

Модели и доступные provider options для каждой.

PATCH /providers

Сохранить provider по умолчанию для модели.

Как выбрать модель

  • ID модели имеет формат provider/model, например openai/gpt-5.4-mini.
  • model_authors=anthropic,openai использует OR между точными slug разработчиков; неизвестный slug возвращает 400 invalid_model_author.
  • Фильтры разработчика, input_modalities=text,image,audio и output_modalities=text,image,video комбинируются через AND. GET /models/count принимает те же фильтры.
  • Без limit GET /models остается плоским и непагинированным. limit принимает 1–1000, offset — неотрицательное число; ответ добавляет total_count и links.next.
  • Ключ с model allowlist видит в каталоге, списке разработчиков, count и model detail только разрешенные модели.
  • Поле endpoints показывает совместимые API: chat, responses, messages, images_generations, images_edits, videos_submit.
  • Цены возвращаются в unit: usd_per_million_tokens, usd_per_image или usd_per_second.
  • GET /models/{provider}/{model}/endpoints показывает supports_streaming и supported_parameters для конкретной модели.

Бесплатные модели

  • Сейчас бесплатными являются opencode/big-pickle и opencode/north-mini-code-free; определяйте их только по access.type = "free", а не по нулевой цене.
  • Для бесплатных моделей нужен Telegram, привязанный к текущему аккаунту; подключить его можно на /settings.
  • Все бесплатные модели, API-ключи, API endpoint-ы, Dashboard-чат и Telegram-чат делят один лимит 100 принятых запросов за календарный день UTC.
  • Смена API-ключа, модели или способа вызова не создает новый лимит; provider retry и fallback внутри принятого запроса повторно не считаются.
  • Бесплатный запрос может пройти с нулевым балансом и исчерпанным spend limit, но только после проверки Telegram и дневного лимита.

Настроить reasoning effort

Сначала проверьте supported_reasoning_efforts нужного endpoint-а. reasoning_effort передается верхнеуровневым полем, а reasoning и output_config — объектами, как в примерах. Responses использует reasoning.effort; Messages — output_config.effort или верхнеуровневый reasoning_effort, если он явно указан. Значение none явно отключает reasoning у моделей, которые его публикуют; это не пропуск поля. Обычно доступны low, medium и high; xhigh и max — только у отдельных моделей. У openai/gpt-5.6-luna, openai/gpt-5.6-sol и openai/gpt-5.6-terra также доступен уровень ultra.

Фрагменты JSON body
{
  "reasoning_effort": "high"
}

{
  "reasoning": {
    "effort": "high"
  }
}

{
  "output_config": {
    "effort": "high"
  }
}

Получить провайдеров моделей

GET /providers возвращает selected_provider_chain в сохраненном порядке и provider options в текущем Auto-порядке с auto_rank, success rate, лимитами, возможностями и availability.

curl
curl https://api.closerouter.dev/v1/providers \
  -H "Authorization: Bearer $CLOSEROUTER_API_KEY"

Выбрать провайдера для одного запроса

Передайте provider как строку: auto, provider-1, provider-5 и так далее.

curl
curl https://api.closerouter.dev/v1/chat/completions \
  -H "Authorization: Bearer $CLOSEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-opus-4.8",
    "provider": "provider-5",
    "messages": [
      { "role": "user", "content": "Reply with exactly: ok" }
    ],
    "max_tokens": 16
  }'

Сохранить одного провайдера (совместимый формат)

Старый provider-формат остается поддержан и сохраняет цепочку из одного провайдера.

curl
curl https://api.closerouter.dev/v1/providers \
  -X PATCH \
  -H "Authorization: Bearer $CLOSEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-opus-4.8",
    "provider": "provider-5"
  }'

Сохранить цепочку провайдеров

PATCH /providers сохраняет строгую цепочку на аккаунт. Порядок элементов provider_chain — порядок попыток для всех API-ключей аккаунта и кабинета /models.

curl
curl https://api.closerouter.dev/v1/providers \
  -X PATCH \
  -H "Authorization: Bearer $CLOSEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-opus-4.8",
    "provider_chain": [
      { "name": "provider-5" },
      { "name": "provider-2" }
    ]
  }'

Вернуться к Auto

provider: "auto" очищает сохраненную цепочку и возвращает автоматический выбор.

curl
curl https://api.closerouter.dev/v1/providers \
  -X PATCH \
  -H "Authorization: Bearer $CLOSEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-opus-4.8",
    "provider": "auto"
  }'

Режимы Flex, Default и Priority

  • provider-9 поддерживает режимы для openai/gpt-5.6-luna, openai/gpt-5.6-sol, openai/gpt-5.6-terra, google/gemini-3.1-pro-preview, google/gemini-3.5-flash, google/gemini-3.5-flash-lite и google/gemini-3.6-flash. Для google/gemini-3.1-flash-lite сейчас доступен только Flex.
  • Передайте суффикс :flex или :priority в model для точного разового выбора. Базовый ID и суффикс :default выбирают Default.
  • Flex дешевле, но может дольше ждать в очереди провайдера; Default — сбалансированный режим; Priority получает максимальный приоритет обработки и стоит дороже.
  • GET /providers возвращает service_tier у конкретного варианта. В кабинете /models все режимы объединены в одной карточке провайдера: кнопки меняют итоговую цену CloseRouter и ID модели, а сохранение выбранного option_id закрепляет точный режим на аккаунт.
  • Auto не подменяет Default более дешевым Flex или дорогим Priority, когда у provider-9 доступны все три режима.

Порядок и приоритеты

  • Цепочка строгая: после ошибки последнего выбранного провайдера API не добавляет невыбранных Auto-провайдеров и возвращает финальную ошибку.
  • provider в inference-запросе — разовый override с приоритетом над сохраненной цепочкой; provider: "auto" включает Auto только для этого запроса.
  • provider.order задает порядок публичных вендоров моделей и не является сохраненной цепочкой upstream-провайдеров.
  • PATCH /providers с provider: "auto" очищает сохраненную цепочку; legacy provider: "provider-5" сохраняет цепочку длиной один.
  • Для точного variant-level выбора остается поддержка provider.option_id.