Kilo Code (VS Code / PyCharm)

Kilo Code — open-source AI-ассистент для редактора: он читает и правит файлы, выполняет команды в терминале и ведёт задачу в несколько шагов, опираясь на инструменты, которые выдаёт ему модель. Соединить его со SpeShu.AI нужно, чтобы агент работал на моделях из одного каталога, с одним балансом и оплатой в рублях.

Всё подключение сводится к двум значениям: https://speshu.ai/api/v1 как адрес OpenAI-совместимого провайдера и ваш API-ключ. Эндпоинт /api/v1/chat/completions совместим с OpenAI Chat Completions, поэтому Kilo Code работает через штатный режим «провайдер, совместимый с OpenAI» — код расширения менять не нужно. Ключ создаётся в личном кабинете, подробности — в разделе Аутентификация.

Ключ и идентификатор модели

Положите ключ в переменную окружения

Полное значение ключа показывается один раз — сохраните его сразу при создании.

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

Проверьте, что ключ принят, запросом баланса: он не стоит токенов и не обращается к моделям.

cURL

curl -s https://speshu.ai/api/v1/balance \
  -H "Authorization: Bearer $SPESHU_API_KEY"

Возьмите идентификатор модели из каталога

Идентификаторы текстовых моделей не зашивайте в код: состав каталога меняется, и зашитая в настройки расширения строка начинает падать с 404 model_not_found без предупреждения. Возьмите id из ответа API один раз при настройке:

cURL

export SPESHU_MODEL=$(curl -s https://speshu.ai/api/v1/models \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  | jq -r '.data[0].id')
echo "$SPESHU_MODEL"

.data[0] — первый элемент, чтобы команда была запускаемой. Выбирайте сами по context_length, cost_completion и наличию зрения. Поля ответа разобраны в разделе Модели и цены.

Проверьте, что ключ и модель работают, до настройки редактора

Тот же запрос, который Kilo Code отправит при первом обращении к модели:

cURL

curl -s https://speshu.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$SPESHU_MODEL\",
    \"messages\": [{\"role\": \"user\", \"content\": \"Ответь одним словом: работает?\"}]
  }" | jq -r '.choices[0].message.content, .usage.cost.total_cost'

Если команда ответила текстом и числом списания, проблем в конфигурации расширения нет — остаётся перенести те же два значения в настройки.

Настройка в расширении

Названия полей и их порядок менялись между версиями Kilo Code, поэтому ниже — смысл каждого поля, а не схема конфига. В расширении для VS Code путь такой: откройте панель Kilo Code (иконка в боковой панели), нажмите на шестерёнку — откроются Kilo Settings — и перейдите на страницу провайдера. В плагине для JetBrains (PyCharm, IntelliJ) это те же настройки: иконка Kilo Code на правой панели → Settings → страница провайдера.

Выберите OpenAI-совместимого провайдера

В списке API Provider выберите пункт для OpenAI-совместимого провайдера — в английском интерфейсе это OpenAI Compatible или Generic OpenAI Compatible. Не выбирайте пункт конкретного провайдера: те зашивают свой адрес и свой протокол.

Заполните три поля

Поле	Значение
Base URL	`https://speshu.ai/api/v1`
API Key	значение `SPESHU_API_KEY` целиком, с префиксом `sk-`
Model ID	результат команды из шага выше

Адрес пишите без завершающего слэша. Вариант https://speshu.ai/api/v1/ склеится с /chat/completions в двойной разделитель, и сервер ответит 404 при вполне рабочем ключе.

Сохраните и проверьте список моделей

На странице провайдера есть действие загрузки списка моделей по адресу выше. Если после нажатия список не наполнился, впишите Model ID вручную — поле принимает произвольную строку, а не только элемент выпадающего списка.

Пустой список моделей — не ошибка доступа к API. GET /api/v1/models отдаёт поля каталога, а часть клиентов ожидает ещё и описание возможностей, которых в нём нет. Ручной Model ID работает во всех случаях.

Ключ без вставки в настройки

Если не хотите хранить ключ в настройках расширения, посмотрите в форме провайдера переключатель чтения из переменной окружения (в разных версиях он называется по-разному) и укажите имя SPESHU_API_KEY. Если такого переключателя в вашей версии нет, остаётся завести ключ в менеджере секретов или в переменной окружения и подставить его при настройке.

Не коммитьте ключ в репозиторий и не оставляйте его в скриншотах настроек. Расширение хранит его в хранилище секретов редактора, но любое экспортированное или закоммиченное значение конфигурации утекает вместе с историей git.

Что работает из коробки

Инструменты агента. Чтение и запись файлов, запуск команд в терминале, правки по задаче — это вызовы функций, которые Kilo Code формирует сам и отправляет в поле tools. Поэтому модель обязана поддерживать вызов инструментов: агентный цикл на модели без такой поддержки не поедет. Проверить это стоит сразу, первым же запросом на изменение файла. Полный цикл вызова — в гайде Вызов функций. Потоковая передача. Ответ приходит по частям — в этом API поток включается на стороне сервера параметром stream, и агент подписывается на него сам. Формат кадров, маркер [DONE] и кадр со списанием разобраны на странице Потоковая передача. Изображения во входе. Скриншот, схема или файл из рабочей области уходят в модель, если у выбранной модели есть зрение. Модель без зрения отвергает такой запрос целиком с 400 invalid_request. Требования к ссылке и формам блоков контента — в гайде Медиаввод. Расход. Списание в рублях приходит в каждом ответе в поле usage.cost.total_cost. Собственный счётчик токенов в редакторе — оценка по внутренним ценам расширения, а не фактическое списание: сверяйтесь с балансом через GET /api/v1/balance и с тарификацией.

О чём предупредить

Эндпоинта эмбеддингов у SpeShu.AI нет: /api/v1/embeddings не существует. Если вы включаете индексацию кодовой базы и она требует вектора, этот шаг нужно увести на другого провайдера — со своим адресом, своим ключом и своей моделью для эмбеддингов. Соблазн вписать в поле Base URL адрес SpeShu.AI, чтобы «схватить всё сразу», приведёт к 404 ровно на этом шаге, тогда как обычные запросы чата продолжат работать.

Генерация изображений, видео и музыки в Kilo Code не встроена: медиа-API асинхронный, с оплатой при создании задачи и отдельным опросом статуса, и интерфейс расширения под него не рассчитан. Задачи создавайте напрямую через POST /api/v1/async/media/tasks — состав запроса, конверт ответа и Idempotency-Key разобраны в разделе Создать задачу.

Частые проблемы

404 на первом же запросе, хотя ключ верен

Проверьте адрес целиком: правильное значение — https://speshu.ai/api/v1. Варианты https://speshu.ai/api и https://speshu.ai/api/v1/ одинаково дают 404. Если ключ и модель уже проверены curl-командой из шага 3, дело точно в адресе, а не в доступе.

401 invalid_api_key

Ключ скопирован не полностью, с кавычками вокруг или с переносом строки, либо отозван в разделе API-ключей профиля. Проверьте командой curl -s https://speshu.ai/api/v1/balance -H "Authorization: Bearer $SPESHU_API_KEY" — если она отвечает, значит, проблема в том, что попало в настройки расширения.

404 model_not_found после обновления каталога

В поле Model ID зашит идентификатор, которого больше нет в GET /api/v1/models. Возьмите id заново той же командой и впишите его в настройки. Зашитый список моделей устаревает молча.

Агент не вызывает инструменты, только пишет текст

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

422 content_too_large на длинной задаче

Запрос не поместился в контекстное окно модели — context_length из каталога. Уменьшите объём переданного контекста, закройте лишние вкладки в диалоге агента или возьмите модель с большим окном. Разбор — в разделе Модели и цены.

402 insufficient_quota

На балансе нет положительной суммы. Пополнение — в личном кабинете на speshu.ai/profile; проверка баланса делается до обращения к модели, за отказ деньги не списываются.

Всё остальное

Полная таблица кодов, три формата ошибок и цикл повторов — на странице Ошибки, таймауты и квоты — в разделе Лимиты.

Что дальше

Начало работы

Полный маршрут от ключа до медиа-задачи

Модели и цены

Как выбрать идентификатор и на что смотреть

Вызов функций

Как устроены инструменты агента

Тарификация и оплата

Как читать списание в рублях

Начало работы

Возможности моделей

Генерация медиа

Фреймворки

Базы данных

Агенты и редакторы

No-code и автоматизация

Ключ и идентификатор модели

Настройка в расширении

Ключ без вставки в настройки

Что работает из коробки

О чём предупредить

Частые проблемы

Что дальше

Начало работы

Модели и цены

Вызов функций

Тарификация и оплата

​Ключ и идентификатор модели

​Настройка в расширении

​Ключ без вставки в настройки

​Что работает из коробки

​О чём предупредить

​Частые проблемы

​Что дальше

Начало работы

Модели и цены

Вызов функций

Тарификация и оплата

Ключ и идентификатор модели

Настройка в расширении

Ключ без вставки в настройки

Что работает из коробки

О чём предупредить

Частые проблемы

Что дальше