Модели ассистента в API bota.chat: каталог, стартовая модель, набор

Модели ассистента — это идентификаторы OpenRouter вида vendor/model (anthropic/claude-opus-5, openai/gpt-5.5) или «всегда свежие» псевдонимы ~vendor/family-latest (~google/gemini-flash-latest). Какие id вообще можно выбрать, отдаёт каталог; настройки ассистента читает и пишет /assistants/{assistantId}/models.

BASE=https://framesuite.app/api/v1
KEY=user_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
ASSISTANT=53

Каталог моделей

Получить каталог моделей

Список моделей, у которых в настройках ассистента есть галочка. Это те же id, что имеет смысл класть в enabled_models и enabled_image_models. Каталог строится из фида OpenRouter и не зависит от ассистента.

GET /models/catalog

Параметр	Тип	Обяз.	Описание
`type`	string	нет	Строка запроса. `all` (по умолчанию), `text`, `image`, `video`, `speech`, `transcription` или `embedding`.
`full`	boolean	нет	Строка запроса. `1` — полные карточки (цены, контекст, признаки), иначе только `id`, `name`, `provider`, `modality`.

curl -s "$BASE/models/catalog" \
  -H "Authorization: Bearer $KEY"

{
  "success": true,
  "type": "all",
  "count": 272,
  "models": [
    {
      "id": "anthropic/claude-opus-5.5",
      "name": "Anthropic: Claude Opus 5.5",
      "provider": "Anthropic",
      "modality": "text"
    },
    {
      "id": "~google/gemini-flash-latest",
      "name": "Google: Gemini Flash Latest",
      "provider": "Google",
      "modality": "text"
    }
  ]
}

С full=1 карточка выглядит так:

{
  "id": "google/gemini-3.1-flash-lite-image",
  "name": "Google: Nano Banana 2 Lite (Gemini 3.1 Flash Lite Image)",
  "provider": "Google",
  "vision": true,
  "image_gen": true,
  "audio": false,
  "reasoning": true,
  "tools": false,
  "modality": "image",
  "context_length": 65536,
  "pricing": {
    "prompt": 2.5e-07,
    "completion": 1.5e-06,
    "image": null,
    "request": null,
    "audio": null,
    "input_audio": null
  },
  "image_price_rub": null,
  "created": 1782837225
}

Свойство	Тип	Описание
`id`	string	Id модели для настроек ассистента.
`name`	string	Название для людей.
`provider`	string	Разработчик модели.
`modality`	string	`text`, `image`, `video`, `speech` (аудиомодели), `transcription` (распознавание речи) или `embedding`. Каждое значение выбирается фильтром `type`.
`vision`, `image_gen`, `audio`, `reasoning`, `tools`	boolean	Только с `full=1`: принимает картинки, рисует картинки, работает со звуком, умеет рассуждать, умеет вызывать инструменты.
`context_length`	integer	Только с `full=1`: окно контекста в токенах.
`pricing`	object	Только с `full=1`: цены OpenRouter в долларах за токен, картинку или запрос.
`created`	integer	Только с `full=1`: время появления модели, Unix-время.

Пустой models при type=all означает, что сервер не смог получить фид OpenRouter; повторите запрос позже. У узкого фильтра пустой список — обычное дело: сейчас type=speech отдаёт четыре модели, а transcription и embedding — ни одной: таких моделей в каталоге сейчас нет.

HTTP	Когда
200	Каталог отдан.
401	Нет ключа или ключ неверный.
422	Неизвестный `type`: `{"success":false,"error":"invalid_type","message":"type must be one of: all, text, image, video, speech, transcription, embedding"}`.

Модели ассистента

Получить модели ассистента

GET /assistants/{assistantId}/models

Параметр	Тип	Обяз.	Описание
`assistantId`	integer	да	Путь. Id ассистента.

curl -s "$BASE/assistants/$ASSISTANT/models" \
  -H "Authorization: Bearer $KEY"

{
  "success": true,
  "ai_model": "default-model",
  "enabled_models": [
    "anthropic/claude-opus-5",
    "openai/gpt-5.5",
    "google/gemini-3.6-flash",
    "…"
  ],
  "free_model": "deepseek/deepseek-v4-flash-0731",
  "default_model": "~google/gemini-flash-latest",
  "credit_multiplier": 1.5,
  "image_model": null,
  "enabled_image_models": [
    "google/gemini-3.1-flash-image-preview",
    "google/gemini-3-pro-image-preview",
    "openai/gpt-5-image"
  ],
  "video_model": null
}

HTTP	Когда
200	Настройки отданы.
404	Ассистента нет или к нему нет доступа: `{"error":"Project not found or access denied"}`.

Свойства моделей ассистента

Свойство	Тип	Описание
`ai_model`	string, до 120	Стартовая модель: на ней открывается чат. Кроме id принимает два особых значения: `default-model` — стартовать на Default-модели (по умолчанию у новых ассистентов), `auto-free` — стартовать на `free_model`.
`default_model`	string или null, до 120	Модель, которую человек видит в выборе моделей как «Default», без настоящего имени. По умолчанию у новых ассистентов `~google/gemini-flash-latest`.
`enabled_models`	array строк	Модели, доступные человеку в выборе моделей. Заменяется целиком. Стартовой модели в списке быть не обязано.
`free_model`	string или null, до 120	Бесплатная модель: ответы на ней не списывают кредиты.
`credit_multiplier`	number, 1–10	Старый множитель для оценок стоимости. На списание не влияет: списывается стоимость ответа у OpenRouter, маржу задаёт число кредитов в тарифах, см. Пейволл и тарифы.
`image_model`	string или null, до 120	Стартовая модель картинок.
`enabled_image_models`	array строк, до 300	Модели картинок, доступные человеку. Заменяется целиком.
`video_model`	string или null, до 120	Модель видео. Работает при включённой `capability_video`, см. Возможности.

Выбор моделей в чате человек видит при capability_model_selector: true, а платность выбора задаёт paid_features.models — оба поля в /features.

Изменить модели ассистента

Частичное обновление: меняется только то, что пришло. Id сверяются с каталогом: то, чего в каталоге нет, сохраняется, но галочки в настройках не получит, и такие id возвращаются в unknown_models.

PUT /assistants/{assistantId}/models

Параметр	Тип	Обяз.	Описание
`assistantId`	integer	да	Путь. Id ассистента.
`strict`	boolean	нет	Тело или строка запроса. `true` — незнакомое поле или id не из каталога дают 422, ничего не пишется.
остальные	—	нет	Тело, JSON. Свойства из таблицы выше.

curl -s -X PUT "$BASE/assistants/$ASSISTANT/models" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled_image_models":["google/gemini-3.1-flash-image-preview","openai/gpt-5-image"]}'

{
  "success": true,
  "applied": ["enabled_image_models"],
  "ignored": []
}

Если в списке есть id, которых нет в каталоге:

{
  "success": true,
  "applied": ["enabled_models"],
  "ignored": [],
  "unknown_models": ["x-ai/grok-4-fast", "qwen/qwen3.8-max"],
  "warning": "Нет в каталоге визарда (галочек не будет): x-ai/grok-4-fast, qwen/qwen3.8-max"
}

Сверяются enabled_models (ожидаются текстовые модели), enabled_image_models (модели картинок), image_model и video_model. Модель не той модальности тоже попадает в unknown_models с пометкой, например "… (modality image, ожидалась text)". ai_model, default_model и free_model не сверяются.

HTTP	Когда
200	Записано. Проверьте `unknown_models`.
404	Ассистента нет или к нему нет доступа.
422	Ошибка валидации: `{"success":false,"errors":{"credit_multiplier":["The credit multiplier field must not be greater than 10."]}}`.
422	`strict=true` и id не из каталога: `{"success":false,"error":"unknown_models","message":"Моделей нет в каталоге визарда: foo/bar","unknown_models":["foo/bar"]}`.
422	`strict=true` и незнакомое поле: `{"success":false,"error":"unknown_fields",…}`.

Открытая вкладка настроек перезапишет изменения

Страница «Возможности» в настройках ассистента сохраняет все свои поля разом, включая модели и модели картинок. Если вкладка была открыта до записи через API, её «Сохранить» вернёт старые значения. После записи через API перезагрузите вкладку.

Сбросить модели к набору по умолчанию

Ставит рекомендованный набор текстовых моделей — тот же, что получает новый ассистент. Тело не нужно.

POST /assistants/{assistantId}/models/defaults

Что записывается:

Поле	Значение
`enabled_models`	Новейшая версия каждого семейства: Claude Opus, Sonnet, Haiku, Fable; флагман GPT и GPT mini; Gemini Flash; Grok; DeepSeek; Qwen Max; Llama; Mistral Large; Perplexity Sonar. Без псевдонимов `latest`, preview, экспериментальных и бесплатных вариантов. Версии выбираются по живому фиду OpenRouter.
`default_model`	`~google/gemini-flash-latest`
`ai_model`	`default-model`

free_model, модели картинок и видео не трогаются. Если фид OpenRouter недоступен, enabled_models остаётся прежним, остальные два поля всё равно записываются.

curl -s -X POST "$BASE/assistants/$ASSISTANT/models/defaults" \
  -H "Authorization: Bearer $KEY"

{
  "success": true,
  "ai_model": "default-model",
  "default_model": "~google/gemini-flash-latest",
  "enabled_models": [
    "anthropic/claude-opus-5.5",
    "anthropic/claude-sonnet-5",
    "…"
  ]
}

HTTP	Когда
200	Набор записан.
404	Ассистента нет или к нему нет доступа.

Сбросить модели картинок к набору по умолчанию

То же для картинок. enabled_image_models получает все модели картинок из каталога, кроме preview, экспериментальных, бесплатных и пакетных вариантов. image_model — первая модель Google с flash-image в id, а если её нет — первая из набора. Тело не нужно.

POST /assistants/{assistantId}/models/image-defaults

curl -s -X POST "$BASE/assistants/$ASSISTANT/models/image-defaults" \
  -H "Authorization: Bearer $KEY"

{
  "success": true,
  "image_model": "google/gemini-3.1-flash-lite-image",
  "enabled_image_models": [
    "google/gemini-3.1-flash-lite-image",
    "google/gemini-3.1-flash-image",
    "…"
  ]
}

HTTP	Когда
200	Набор записан.
404	Ассистента нет или к нему нет доступа.
503	Каталог картинок пуст, ничего не записано: `{"success":false,"error":"empty_catalog","message":"Каталог картинок пуст (холодный кэш OpenRouter) — ничего не меняли."}`.

Какие id допустимы

Надёжный путь — брать id из GET /models/catalog нужной модальности. Сервер сохранит и id не из каталога, но в настройках ассистента у них не будет галочки, их легко потерять при правке в интерфейсе. Частые причины unknown_models: модель пропала из фида OpenRouter или из отбора каталога, опечатка в id, модель картинок в enabled_models или наоборот.

Псевдонимы latest и рассуждения

Псевдоним ~google/gemini-flash-latest всегда указывает на свежую модель, но у неё может включаться режим рассуждений, а ответ с ним стоит заметно дороже. Учитывайте это, выбирая default_model.

Дальше

Возможности, сайдбар и задержка — выбор модели в чате, картинки, видео, платные функции.
Пейволл и тарифы — кредиты и списание.
Настройки бота и шапка — имя, промпт и остальная идентичность ассистента.