Obsidian: настройка ИИ-плагина на своём API-ключе

Плагины вроде Text Generator и Copilot for Obsidian не привязаны к одному провайдеру — у них есть поле под произвольный OpenAI-совместимый адрес. Это ровно то, что нужно для подключения через шлюз: один ключ fetch_... открывает доступ к Claude, GPT и GLM, и плагин даже не заметит разницы между ними, потому что снаружи всё выглядит как один и тот же Chat Completions API.

Что писать в поля плагина

В настройках плагина обычно три поля: базовый адрес API, ключ и имя модели.

• API Base URL / Endpoint: https://api.zukko.pro/v1
• API Key: ваш ключ вида fetch_..., полученный на странице zukko.pro/app/api-keys↗
• Model: claude-sonnet-5, gpt-5.6-sol, glm-5.3-flash — любой из каталога (актуальный список — GET https://api.zukko.pro/v1/models)

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

Самая частая причина 404 — двойной /v1

Некоторые плагины сами дописывают /chat/completions к тому, что вы ввели в поле адреса. Если в это поле попадёт https://api.zukko.pro/v1, а плагин ещё раз добавит /v1 перед путём — запрос уйдёт на несуществующий адрес и вернётся 404. Проверить, как именно плагин формирует URL, проще всего через сетевую вкладку логов Obsidian (Ctrl+Shift+I → Network) — там виден итоговый адрес запроса.

Если сомневаетесь, проверьте ключ отдельно от плагина:

curl https://api.zukko.pro/v1/chat/completions \
  -H "Authorization: Bearer fetch_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"привет"}]}'

Если curl отвечает нормально, а плагин — нет, проблема в том, как именно плагин собирает адрес, а не в ключе.

Какую модель ставить под какую задачу

Для суммаризации заметок и расстановки тегов подойдёт glm-5.3-flash ($0.04 за миллион токенов) — задача простая, платить за неё как за флагман нет смысла. Для помощи с текстом заметок и связного письма попробуйте claude-sonnet-5 — и проверьте на своих заметках, устраивает ли результат. Если нужно прогнать через ИИ весь vault целиком одним запросом — у моделей Claude и GPT контекст 1,000,000 токенов (у GLM — 128K), этого хватает на сотни заметок разом; актуально для claude-opus-5-5 с extended thinking, когда требуется не просто ответ, а разбор связей между заметками.

Список моделей и цены можно получить без ключа:

curl https://api.zukko.pro/v1/models/info

Отдельный ключ для Obsidian и лимит на него

Плагины с автозапуском (например, автоматическая генерация тегов при сохранении файла) способны незаметно наделать сотни запросов за вечер, если в заметки попадёт цикл или очень большой файл. На странице ключа в кабинете можно задать дневной лимит расхода в долларах и список разрешённых моделей — разумно завести для Obsidian отдельный ключ с небольшим лимитом, а не использовать тот же, что и для остальной работы.

Кэш для повторяющихся вопросов

Если вы регулярно спрашиваете одно и то же про одну и ту же заметку (например, «сократи» для заметки, которая с прошлого раза не менялась), одинаковые запросы кэшируются на срок до 7 суток. Основной способ включить кэш — заголовок X-Zukko-Cache: true (если плагин позволяет добавить свои заголовки): он работает для любой модели. temperature: 0 тоже включает кэш, но только для моделей, которые принимают это значение, — новые модели Claude (claude-sonnet-5, claude-opus-5-5) могут отклонить temperature, отличную от 1, с ошибкой 400, так что для них поле температуры в плагине лучше оставить пустым. Кэш срабатывает только при полном совпадении тела запроса: стоит поправить в заметке хоть один абзац — это уже новый запрос. Повторный вопрос с тем же текстом возвращается мгновенно и бесплатно, в ответе появляется заголовок X-Zukko-Cache: hit, а в /v1/usage такие попадания не пишутся. Через интерфейс плагина этот заголовок не виден, но при отладке через curl проверить попадание в кэш легко — второй запрос с идентичным телом ответит заметно быстрее первого.

Что означают типичные ошибки

• 401 — ключ не принят: проверьте, не прилип ли пробел при копировании, и что поле называется именно Authorization / API Key, а не что-то ещё.
• 402 — баланс пуст: {"error":{"message":"Недостаточно средств на балансе","code":"insufficient_balance"}}. Баланс проверяется до обращения к модели, так что неудачная попытка ничего не стоит.
• 404 model_not_found — опечатка в имени модели: Claude-Sonnet-5 не то же самое, что claude-sonnet-5, регистр важен.
• 429 key_daily_limit_reached — сработал тот самый дневной лимит на ключе; либо подождать сброса (в 00:00 UTC), либо поднять лимит на странице ключа. Своего rate limit у шлюза нет: прочие 429 приходят от провайдера.

Отслеживание расхода

GET /v1/balance с тем же заголовком авторизации покажет остаток на счету и общий расход. GET /v1/usage отдаёт историю списаний постранично (курсорная пагинация, поле next_cursor): в каждой записи created_at, model, input_tokens, output_tokens, total_tokens и cost_cents (в дробных центах). История общая на весь аккаунт — все ключи вместе, фильтра по ключу нет, а баланс тоже один на аккаунт. Чтобы видеть расход плагина отдельно от остальных проектов, логируйте заголовок X-Zukko-Cost-Micros у себя (он есть только у нестриминговых ответов) или заведите под Obsidian отдельный аккаунт.

Если модель временно недоступна

Изредка конкретная модель на время отключается в каталоге — ответ придёт с кодом 503 provider_unavailable или model_disabled. Это не поломка плагина и не проблема с ключом, а временное состояние конкретной модели. Если плагин не умеет сам переключаться на резервную модель, проще всего на несколько минут вручную поменять значение в поле «Model» на другую модель из того же семейства — например, с claude-sonnet-5 на gpt-5.6-sol — и вернуть обратно, когда основная снова заработает. Держать в заметках план Б на этот случай дешевле, чем разбираться, почему плагин молчит именно в момент, когда нужно быстро сократить длинный текст.

Учтите, что 503 model_disabled приходит и тогда, когда модель выключена надолго, а не на несколько минут. Если ошибка не проходит, проверьте актуальный список — GET https://api.zukko.pro/v1/models или страница «Модели» в кабинете: если модели там нет, возвращать старое имя в конфиг смысла нет, нужно один раз поправить поле модели на актуальное значение.