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](...);
• локальные ссылки из vault тоже поддерживаются: ![ALT](attachments/queen_for_a_day.jpg);
• embed-формат Obsidian: ![[queen_for_a_day.jpg]] и ![[path/to/img.jpg]] (параметры вида |500 игнорируются для поиска файла).

Опционально можно включить обработку пустого 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)
  Ограничение по символам. Плагин просит коротко и дополнительно обрезает результат.
• Заполнять пустой alt в заметке (fillEmptyAltEnabled)
  Для команды “заменить ALT … по всей заметке”:
  OFF (по умолчанию) — обрабатывается только alt == "ALT";
  ON — обрабатываются alt == "ALT" и пустой alt (![](...)).

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

• 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 между сессиями (persist):
  для внешних картинок ключ — URL,
  для локальных — path::mtime (если файл изменился, alt пересчитается).
• altCacheMaxEntries — ограничение размера кэша, старые записи вытесняются.

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

1. Плагин получает источник изображения:
   • внешний URL (из буфера или из события вставки),
   • или локальную ссылку из текущей заметки (для команды заполнения плейсхолдеров).
2. Проверяет, что это изображение (по расширению/типу ссылки).
3. Получает байты:
   • внешний URL: через requestUrl Obsidian,
   • локальный файл vault: через metadataCache.getFirstLinkpathDest(...) + vault.readBinary(...).
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 в одном запуске.

См. также 

• Iskra

Обновления 

0.1.2 

• Исправлено ложное срабатывание команды заполнения alt по заметке: изображения внутри inline-кода и fenced code blocks больше не обрабатываются.
• Устранены повторяющиеся ошибки Локальный файл не найден для примеров markdown/Obsidian-синтаксиса в тексте заметки.

0.1.1 

• Команда “заменить ALT … по всей заметке” теперь поддерживает не только внешние URL, но и локальные изображения из vault.
• Добавлена поддержка Obsidian embed-формата: ![[image.jpg]], ![[path/to/image.jpg]], ![[image.jpg|500]].
• Добавлен переключатель fillEmptyAltEnabled: можно заполнять пустой alt (![](...)) вместе с ALT.
• Кэш ALT расширен: для локальных файлов используется ключ path::mtime (при изменении файла alt пересчитывается).

0.1.0 

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