Chatbox — кроссплатформенный клиент для ИИ с приложениями для компьютера и телефона, который умеет работать с несколькими провайдерами моделей. Есть два типичных режима: встроенный сервис Chatbox AI или собственный API-ключ. Статья только о втором: как подключить Chatbox к своему OpenAI-совместимому API.

Примечание: Chatbox — продукт соответствующего правообладателя; статья носит технический характер. Названия меню и расположение полей могут отличаться между версиями — ориентируйтесь на текущую; модели и цены смотрите в разделе тарифов.

1. Определите режим работы

Режим Оплата Где настраивается Кому подходит
Chatbox AI По тарифу клиента Достаточно войти в аккаунт Тем, кто не хочет управлять ключами
Свой API-ключ По факту у API-провайдера Настройки провайдера моделей Командам со своим шлюзом или аккаунтом
Локальная модель Зависит от оборудования Локальный сервер инференса Когда данные не должны покидать устройство

Режимы можно совмещать. Назовите своего провайдера отдельно, например «ZSQH», чтобы не путать со встроенным сервисом. Перед сменой модели проверяйте, какой провайдер используется в текущем диалоге.

2. Подготовьте три параметра

  1. API-ключ: создайте в ZSQH AI Gateway и назовите по проекту.
  2. API-хост: OpenAI-совместимый адрес, обычно https://ai.zhongshangqihang.com/v1.
  3. ID модели: скопируйте точный API-идентификатор со страницы тарифов.

Сначала проверьте через curl, чтобы исключить проблемы на стороне шлюза:

export ZSQH_API_KEY="sk-ваш-ключ"

curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [{"role": "user", "content": "Ответь только OK"}]
  }'

Если возвращается choices, ключ, адрес и модель работают, остаётся только настроить клиент.

3. Добавление своего провайдера

На примере распространённой версии шаги такие (точные подписи кнопок зависят от версии):

  1. Откройте Chatbox и нажмите «Настройки» в левом нижнем углу.
  2. В левом меню выберите «Провайдеры моделей» и нажмите «+ Добавить» внизу.
  3. Дайте провайдеру узнаваемое имя.
  4. Выберите режим API «OpenAI-совместимый» или соответствующий вариант OpenAI.
  5. Укажите API-ключ и API-хост.
  6. Нажмите «Получить», чтобы загрузить список моделей, или добавьте ID вручную.
  7. Нажмите «Проверить», чтобы протестировать соединение с добавленной моделью.

Если «Получить» не срабатывает, это не обязательно означает проблему с ключом: возможно, шлюз не открывает интерфейс списка моделей. В этом случае впишите ID вручную и проверьте через «Проверить».

4. API-хост и /v1

Base URL — место, где чаще всего ошибаются при настройке своего API. Сверяйтесь с таблицей:

Параметр Рекомендуемое значение Внимание
Режим API OpenAI-совместимый Не выбирайте режим Anthropic или Gemini
API-хост https://ai.zhongshangqihang.com/v1 Без слэша в конце
API-ключ sk-... Без пробелов по краям
ID модели По странице тарифов Учитывайте регистр и суффикс версии

Если полный адрес даёт 404, попробуйте убрать /v1; если домен без пути даёт 404 — добавьте /v1. Разные версии клиента по-разному склеивают путь, поэтому ориентируйтесь на фактический результат запроса. 401 — сначала проверяйте ключ, 404 — сначала путь; такой порядок экономит много времени.

5. ID модели и настройка возможностей

При ручном добавлении модели обычно нужно выбрать её тип и возможности. Типичные соответствия:

Тип модели Назначение Какие возможности включить
Чат-модель Вопросы, тексты, перевод Текст, потоковый вывод
Рассуждающая Сложный анализ, планирование Рассуждение или цепочка мыслей
Визуальная Понимание изображений, вопросы по скриншотам Ввод изображений
Инструментальная Вызов функций, плагины Вызов инструментов

При неверном типе модель может не появиться в выборе чата; если возможности не отмечены, загрузка изображений или вызов инструментов будут завершаться ошибкой. Если сомневаетесь, начните только с текстового чата, а остальное добавляйте по одному пункту.

6. Проверка соединения

Кнопка «Проверить» обычно тестирует текст, изображения и вызов инструментов по отдельности. Как минимум убедитесь, что проходит текстовый запрос. Надёжнее отправить реальный вопрос и посмотреть на три вещи:

  1. Приходит ли первый символ сразу или долго крутится индикатор.
  2. Сохраняется ли контекст в многошаговом диалоге.
  3. Не обрывается ли длинный ответ на середине.

Если обрываются только длинные ответы, проверяйте сетевой прокси и потоковый вывод; если падают все запросы — возвращайтесь к ключу и Base URL. Можно сравнить поведение с включённым прокси на компьютере, но не вписывайте адрес прокси в поле API-хоста.

7. Типовые ошибки и решения

Симптом Частая причина Что делать
401 Unauthorized Ключ неверный, просрочен или удалён Создайте ключ заново, проверьте пробелы
404 Not Found Неверный путь API-хоста Добавьте или уберите /v1 и повторите
model not found Неверный ID или модель не включена Скопируйте значение со страницы тарифов
Тайм-аут соединения Сеть недоступна или прокси блокирует Смените сеть, проверьте межсетевой экран
Ответ обрывается Потоковое соединение прервано Отключите потоковый вывод для сравнения
429 Too Many Requests Ограничение параллельности или квоты Снизьте параллельность, посмотрите расход в шлюзе
Не загружается изображение Модель не поддерживает зрение или возможность не отмечена Выберите визуальную модель и включите ввод изображений

При разборе меняйте только один параметр за раз. Если одновременно поменять ключ, адрес и модель, даже при восстановлении нельзя понять, что именно помогло, и ошибка повторится.

8. Безопасность и расходы

  1. И мобильное, и настольное приложение могут хранить ключ — на общем устройстве будьте осторожны.
  2. Выпустите для Chatbox отдельный ключ, чтобы его можно было отозвать в любой момент.
  3. Задайте бюджет на шлюзе, чтобы долгая работа без присмотра не выжигала квоту.
  4. Не вставляйте в диалоги рабочие ключи, списки клиентов и тексты договоров.
  5. Регулярно экспортируйте или копируйте важные диалоги: удаление клиента не означает наличия резервной копии в облаке.
  6. При командном использовании выпускайте ключи по людям — так расход можно разделить.

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

Нужно ли платить за подписку при своём API-ключе?

В режиме своего ключа вызовы моделей оплачиваются провайдером по факту; условия оплаты самого клиента Chatbox смотрите в текущей версии. Это разные статьи расходов, не смешивайте их.

Почему «Получить список моделей» постоянно не срабатывает?

Возможно, шлюз не открывает интерфейс списка моделей или неверен путь Base URL. Сначала добавьте один ID вручную: если так работает, значит проблема только в интерфейсе списка.

Нужно ли добавлять /v1 к API-хосту?

Большинству OpenAI-совместимых конфигураций нужен /v1. Если ошибка возникает и с ним, и без него, сначала проверьте через curl правильный полный адрес запроса, а затем переносите его в клиент — не угадывайте.

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

Да. Дайте каждому отдельное имя и явно выбирайте модель в диалоге. При нескольких провайдерах чаще всего случается ситуация «думали, что используется A, а запрос ушёл к B».

Можно ли пользоваться с телефона?

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

Что дальше

В настройке Chatbox важны три точки: API-хост, ключ и ID модели. Сначала проверьте через curl, затем настраивайте клиент; при сбое идите по порядку: 401 — ключ, 404 — путь, model not found — ID модели. Если нужен единый вход и управление расходом, можно зарегистрироваться в ZSQH AI Gateway; модели и цены смотрите в разделе тарифов.

Читайте также: