AI Alt plugin

Что это? 

AI Alt Plugin — мой плагин для Obsidian, который помогает быстро заполнять alt у картинок для сайта: берёт внешние URL изображений (мой кейс: Hugo внутри Obsidian), по команде отправляет картинки в OpenAI (vision) и возвращает короткие подписи. Это снимает рутину, когда у тебя пачки фото, и нужно просто получить «достаточно хороший» черновик, который потом можно точечно поправить.

Зачем? 

• Я заполняю alt у картинок на сайте, но руками это утомительно, особенно сериями (street/подборки).
• Плагин делает быстрый черновик подписей и возвращает их прямо в заметку.
• Я остаюсь в Obsidian: вставил ссылки, нажал команду, получил результат.

Что умеет? 

Вставка изображений без AI 

Берёт список URL из буфера обмена и вставляет в заметку markdown-картинки по шаблону, с плейсхолдером ALT.

Один URL → alt → вставить 

Берёт один URL из буфера, генерирует alt через OpenAI и вставляет готовую строку по шаблону.

Batch: много URL → alt → вставить (с прогрессом и отменой) 

Берёт список URL из буфера, прогоняет пачкой, показывает прогресс, даёт отменить.
Если отменить, оставшиеся вставляются с ALT, и в заметку добавляется лог.

Пройтись по заметке и заменить ALT плейсхолдеры 

Ищет в текущей заметке markdown-картинки, где alt ровно ALT, и заменяет на сгенерированные подписи.

Авто-обработка вставки URL (autoOnPaste) 

Если включено, при вставке списка URL (и только если все ссылки на изображения) плагин перехватывает вставку и запускает batch.
Можно ограничить по префиксу домена (например, только https://static.antomal.com/...).

Сортировка URL по номеру в имени файла 

Опционально сортирует список URL по числу в имени файла внутри URL (например, IMG_6610_... или 123_...), чтобы вставка шла в “правильном” порядке. Если числа нет, такие ссылки уходят в конец.

Маленькая типографика (кавычки) 

После генерации подписи плагин делает один маленький штрих: заменяет обычные кавычки " на русские «ёлочки».
Это не “типографика на максималках”, а просто аккуратная правка, чтобы русские подписи выглядели чище.

Команды (Command palette) 

• AI Alt: вставить URL-ы как изображения с ALT (без AI)
• AI Alt: один URL с alt от AI
• AI Alt: несколько URL-ов с alt от AI (с прогрессом)
• AI Alt: заменить ALT в изображениях на alt от AI (по всей заметке)

Настройки 

Базовые 

• OpenAI API Key
  Хранится локально в данных плагина.
• Model
  По умолчанию: gpt-4o-mini
  Дополнительно: gpt-5-nano, gpt-5-mini, gpt-5 (и/или “custom model id”).
• Шаблон вывода (template)
  По умолчанию: ![{alt}]({url})
  Можно заменить на любой формат, включая Hugo-шорткоды.
• Максимальная длина alt (maxAltLength)
  Ограничение по символам. Плагин просит коротко и дополнительно обрезает результат.

Авто-вставка и сортировка 

• autoOnPaste — включить перехват вставки списка URL.
• autoPasteUrlPrefix — фильтр по префиксу URL.
• sortAscending — сортировать ссылки по номеру в имени файла (как описано выше).

Image оптимизация (важное для расходов) 

• maxLongSidePx (default 768)
  Перед отправкой в OpenAI картинка уменьшается до 768px по длинной стороне (без апскейла).
• jpegQuality (default 0.75)
  Картинка приводится к JPEG перед отправкой.
• imageDetail (low / high, default low)
  low экономит токены, для alt обычно достаточно.

Производительность и лимиты 

• maxConcurrent — сколько картинок обрабатывать одновременно.
• rpmLimit / tpmLimit — троттлинг, чтобы не ловить 429 и не устраивать “стадо запросов”.
• timeout — тайм-аут на скачивание и на запрос к модели.
• retryMax + backoff + jitter — повторы при 429/5xx/сетевых ошибках.

Кэш и дедуп 

• dedupeUrlsInBatch — одинаковые URL внутри одного запуска не отправляются повторно.
• altCacheEnabled — сохранять alt по URL между сессиями (persist).
• altCacheMaxEntries — ограничение размера кэша, старые записи вытесняются.

Как это устроено (логика)? 

1. Плагин получает URL (из буфера или из события вставки).
2. Проверяет, что это ссылки на изображения (по расширению).
3. Скачивает изображение через requestUrl Obsidian.
4. Делает downscale (max 768px по длинной стороне) и JPEG-реэнкод.
5. Отправляет изображение в OpenAI vision с коротким промптом на русском.
6. Получает текст, чистит/обрезает, экранирует, типографит кавычки («ёлочки»), вставляет по template.
7. Batch работает параллельно (до maxConcurrent), но с общей очередью/лимитером.
8. Ошибки фиксируются и при необходимости добавляются в лог-блок внутри заметки.

Промпт 

Плагин запрашивает:

• короткий alt на русском,
• без слов “картинка/изображение”,
• без хэштегов,
• максимум N символов,
• текст на картинке учитывать только если он прям очевидный (OCR не “главная ставка”).

Лог ошибок в заметку 

Лог появляется только если:

• были ошибки,
• или была отмена batch.

Обычно содержит:

• статистику (всего/успешно/вставлено как ALT),
• список ошибок по URL,
• примечание об отмене (если отменяли).

Приватность и безопасность 

• Плагин отправляет изображения в API (OpenAI), чтобы получить подписи.
• API ключ хранится локально в Obsidian данных плагина.
• Если не хочется, чтобы конкретная картинка уходила в API, я просто не гоняю её через плагин и пишу alt руками.

Расходы и контроль 

• Основной рычаг экономии: уменьшение картинки до 768px + detail=low.
• Если нужно ещё дешевле:
  • уменьшить maxLongSidePx (например, 640),
  • оставить low,
  • держать модель на gpt-4o-mini или ещё более экономной (если подходит).
• Контроль на платформе:
  • Usage по проекту/модели,
  • месячный budget (скорее алерты),
  • если хочешь “жёстко не тратить больше N”, лучше prepaid кредиты и выключить автопополнение.

Типовой воркфлоу 

1. Загружаю пачку фото на сайт/статик, получаю URL-ы.
2. Вставляю список URL в заметку Obsidian.
3. Запускаю batch-команду.
4. Быстро пробегаю глазами alt-ы и правлю только то, что реально важно.
5. Если нужно, позже запускаю команду “заменить ALT плейсхолдеры” по всей заметке.

Устранение неполадок 

ALT вставился, но текста нет / пусто 

Модель вернула пустой ответ или отвалился запрос. Смотри лог ошибок.

429 / слишком много запросов 

Уменьшить maxConcurrent, уменьшить rpmLimit, подождать минуту.

Не скачивается изображение 

URL не публичный / требует авторизацию / временная ссылка / сервер блокирует.
Если URL не открывается в браузере без логина, плагин тоже не скачает.

Отмена 

Нормально: оставшиеся URL получат ALT, лог добавится. Потом можно догнать повторным запуском (часть подхватится из кэша).

Глоссарий (для себя) 

• Batch: пакетная обработка, сразу список URL.
• Dedup: дедупликация, не делать одинаковый запрос повторно для одинаковых URL в одном запуске.

Обновления 

1.0 

• Генерация alt через OpenAI vision.
• Downscale до 768px + JPEG перед отправкой.
• Прогресс-модалка, отмена batch, лог ошибок в заметку.
• Кэш alt по URL (persist), дедуп в батче.
• Авто-вставка URL по префиксу (опционально).
• Опциональная сортировка URL по номеру в имени файла.
• Авто-замена кавычек на «ёлочки» в русских подписях.