Cherry Studio: добавление API-провайдера Zukko

Cherry Studio — десктопный клиент для работы с языковыми моделями, в котором можно добавить собственного API-провайдера. Zukko подключается как провайдер с OpenAI-совместимым API: один ключ fetch_... открывает модели Claude, GPT и GLM. Ниже — настройка по официальной документации Cherry Studio, особенности поля API Host, добавление моделей и разбор ошибок.

Как добавить API-провайдера в Cherry Studio

1. Нажмите на шестерёнку «Настройки» в левой панели.
2. Откройте раздел со списком провайдеров — в английском интерфейсе он называется Model Provider.
3. Под списком провайдеров нажмите + Add (Add Provider).
4. Укажите название провайдера, например Zukko, и тип OpenAI. Нажмите «Добавить».
5. Откройте созданного провайдера и заполните API Key и API Host.
6. Добавьте модели (см. ниже) и нажмите Check.
7. Включите провайдера переключателем в правом верхнем углу его страницы.

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

Что вписать в API Host

Cherry Studio сам достраивает адрес: по документации достаточно указать корень, а /v1/chat/completions приложение добавит автоматически. В актуальных версиях Cherry Studio не дублирует версию, если она уже есть в адресе, поэтому вариант https://api.zukko.pro/v1 тоже приведёт к правильному запросу. Под полем показывается предпросмотр итогового адреса — убедитесь, что /v1 в нём встречается один раз.

Если в конце адреса поставить #, Cherry Studio перестанет что-либо дописывать и будет использовать адрес как есть. Для Zukko это не нужно.

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

Есть два способа:

• Загрузить список. Кнопка получения списка моделей запрашивает их у API. Zukko отдаёт список по GET /v1/models, поэтому все доступные модели подтянутся сами. В открывшемся окне управления моделями нажмите + рядом с нужными — в списках выбора появятся только добавленные модели.
• Добавить вручную. Кнопка Add Model открывает форму: Model ID (например, claude-sonnet-5), Model Name для отображения и Group Name для группировки.

Документация Cherry Studio советует добавлять только те модели, которыми вы реально пользуетесь, и сверять фактический id модели — он показан под её названием.

Проверка подключения

Нажмите Check на странице провайдера и выберите модель для теста. Если проверка прошла, создайте новый диалог, выберите в нём модель Zukko и отправьте короткое сообщение. Если проверка не прошла, документация советует в первую очередь посмотреть, нет ли в списке моделей ошибочных или неподдерживаемых id.

Модели по умолчанию: где можно сэкономить

В Cherry Studio есть отдельные настройки моделей по умолчанию:

• Default Assistant Model — используется, если у ассистента не задана своя модель;
• Quick Model — для служебных задач вроде автоматического названия диалогов и выделения ключевых слов. Документация советует брать сюда лёгкую недорогую модель;
• Translate Model — для перевода сообщений.

Служебные запросы отправляются автоматически, поэтому для Quick Model разумно выбрать glm-5.3-flash — самую дешёвую модель Zukko. Для основного общения выбирайте модель по своим задачам.

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

Пример: 100 сообщений в день, каждое — 3 000 входных и 700 выходных токенов, всего 370 000 токенов в день. На claude-sonnet-5 это 370 000 × $0.3 / 1 000 000 = $0.111 в день, на gpt-5.6-luna — $0.037, на glm-5.3-flash — $0.0148.

Какая модель лучше подходит под ваши задачи, проверьте сами: задайте двум-трём моделям одни и те же 10–20 типичных вопросов и сравните ответы и расход в разделе «Использование» кабинета. Актуальный список моделей — GET https://api.zukko.pro/v1/models (см. документацию по моделям↗) или страница «Модели» в кабинете.

Частые ошибки

Модели не видны в чате

Провайдер не включён переключателем или модели не добавлены в список кнопкой +. Проверьте оба пункта.

404

Адрес собран неверно: например, /v1 попал в адрес дважды или в API Host вставлен полный путь с /chat/completions. Укажите https://api.zukko.pro и проверьте предпросмотр адреса под полем.

401

Ключ скопирован не полностью, с пробелом или удалён в кабинете. Ключ начинается с fetch_.

Check проходит, а в диалоге ошибка

Скорее всего, ассистент в этом диалоге использует другую модель — например, ту, что указана в Default Assistant Model, от другого провайдера. Откройте настройки ассистента и явно выберите модель Zukko. Та же логика у служебных задач: если Quick Model указывает на провайдера без ключа, названия диалогов не будут генерироваться.

400 на моделях Claude

Модели claude-sonnet-5 и claude-opus-5-5 могут отклонять запрос с ошибкой 400, если temperature отличается от 1 или top_p меньше 0.99. Проверьте настройки ассистента: если там задана temperature или top_p, для Claude отключите их или верните значения по умолчанию.

402, 403, 429

402 — закончился баланс. 403 model_not_allowed_for_key — модели нет в списке разрешённых для ключа, добавьте её в настройках ключа. 429 — слишком частые запросы, подождите и повторите.

Частые вопросы

Можно ли подключить Claude в формате Anthropic?

Zukko принимает и Anthropic-формат, а у провайдера в Cherry Studio есть отдельное поле Anthropic API Host. Но это не обязательно: шлюз сам конвертирует запросы, и модели Claude работают через OpenAI-совместимое подключение. Подробнее о форматах — в документации о выборе формата↗.

Можно ли добавить несколько ключей?

Cherry Studio поддерживает несколько ключей у одного провайдера и использует их по очереди. Для Zukko это обычно не нужно: баланс общий. Удобнее завести отдельных провайдеров с разными ключами и лимитами — например, для работы и для экспериментов.

Где смотреть расходы?

В кабинете Zukko, раздел «Использование». Cherry Studio баланс Zukko не показывает.

Где взять ключ?

Создайте его в кабинете Zukko↗ и вставьте в поле API Key. Если вы впервые работаете с API, начните с быстрого старта↗.