Chatbox: подключение собственного API-ключа Zukko

Chatbox — чат-клиент для компьютера и телефона, в котором можно подключить свой API-ключ вместо встроенных сервисов. Zukko добавляется как провайдер типа «OpenAI API Compatible», после чего в Chatbox становятся доступны модели Claude, GPT и GLM с оплатой по токенам. Ниже — пошаговая настройка по официальной документации Chatbox, тонкости полей API Host и API Path и решения частых ошибок.

Как добавить свой API-ключ в Chatbox

Документация Chatbox даёт одну инструкцию, без разделения на настольную и мобильную версии:

1. Откройте Chatbox и нажмите кнопку настроек в боковой панели.
2. Выберите раздел Model Provider.
3. Внизу списка провайдеров нажмите Add.
4. Введите название (например, Zukko) и выберите тип API — OpenAI API Compatible.
5. Заполните API Key и API Host (значения ниже). Поле API Path оставьте пустым.
6. Добавьте хотя бы одну модель: введите её id вручную или подгрузите список кнопкой Fetch, если она есть в вашей версии.
7. Сохраните и нажмите Check — Chatbox должен сообщить об успешном подключении.
8. Вернитесь на главный экран, создайте новый диалог и выберите модель Zukko.

Какие значения вписать

Почему API Path лучше не трогать

Chatbox собирает итоговый адрес из двух частей: API Host плюс API Path. Если путь не указан, приложение подставляет /chat/completions, а если в хосте нет /v1, само его добавляет. Поэтому оба варианта хоста — https://api.zukko.pro/v1 и https://api.zukko.pro — приводят к правильному адресу https://api.zukko.pro/v1/chat/completions.

Ошибка возникает, когда /v1 указан и в хосте, и в пути: например, хост https://api.zukko.pro/v1 и путь /v1/chat/completions дают /v1/v1/... и ответ 404. Если вы заполнили API Path, проверьте, что /v1 встречается в итоговом адресе один раз.

Модели и их возможности

Модели в Chatbox добавляются вручную по id — так, как они называются в API. Для каждой модели можно отметить возможности (например, работу с изображениями или инструментами). По документации Chatbox модель без отметок считается чисто текстовой. Отмечайте возможности только тогда, когда уверены, что модель их поддерживает, иначе запросы с картинками или инструментами будут завершаться ошибкой.

Актуальный список id — GET https://api.zukko.pro/v1/models (см. документацию по моделям↗) или страница «Модели» в кабинете.

Вариант для Claude: провайдер Claude API Compatible

В списке типов есть и Claude API Compatible. Zukko принимает Anthropic-формат на POST https://api.zukko.pro/v1/messages, а Chatbox для этого типа дописывает к хосту только /messages. Поэтому в API Host и здесь нужен адрес с /v1: https://api.zukko.pro/v1.

Обязательной необходимости в этом нет: шлюз конвертирует форматы, и Claude-модели работают через обычный OpenAI-совместимый провайдер. Второй тип пригодится, если вы хотите держать модели Claude отдельной группой. Чем отличаются форматы, описано в документации о выборе формата↗.

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

Пример расчёта для одного сообщения: 2 000 токенов вопроса с историей и 800 токенов ответа, всего 2 800:

• claude-sonnet-5: 2 800 × $0.3 / 1 000 000 = $0.00084;
• gpt-5.6-luna: 2 800 × $0.1 / 1 000 000 = $0.00028;
• glm-5.3-flash: 2 800 × $0.04 / 1 000 000 = $0.000112.

Качество ответов на ваших задачах проверьте сами: добавьте в Chatbox две-три модели, задайте каждой одни и те же 10–20 типичных вопросов и сравните ответы и расход в разделе «Использование» кабинета.

Компьютер и телефон

Настройки провайдера хранятся в приложении на конкретном устройстве, поэтому на компьютере и телефоне Zukko придётся добавить отдельно. Для каждого устройства удобно завести свой ключ в кабинете: если телефон потеряется, достаточно удалить один ключ, не трогая остальные. Каждому ключу можно задать дневной и месячный лимит.

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

401 или «Invalid API key»

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

404

Почти всегда это адрес: /v1 указан дважды (в хосте и в пути) или хост введён с опечаткой. Очистите API Path и укажите хост https://api.zukko.pro/v1.

Ошибка о неизвестной модели

Id модели введён не так, как в API: например, Claude Sonnet 5 вместо claude-sonnet-5. Скопируйте id из ответа GET /v1/models.

400 на моделях Claude

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

402 или 403

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

Check проходит, а ответ не приходит

Проверьте, не отмечены ли у модели возможности, которых у неё нет, и не превышен ли лимит ключа. Если провайдер модели временно недоступен, API вернёт 503 — выберите другую модель или повторите позже.

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

Работает ли это на iOS и Android?

Да, Chatbox есть для мобильных платформ, а инструкция в документации общая: настройки → Model Provider → Add → OpenAI API Compatible. Если в вашей версии пункты называются иначе, ищите раздел провайдеров моделей.

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

Да, Chatbox позволяет держать несколько провайдеров и выбирать модель в каждом диалоге. Например, Zukko с одним ключом для работы и с другим — для личных задач.

Как посмотреть расходы?

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

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

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