Генерация изображений

oma-image — это мультивендорный маршрутизатор изображений для oh-my-agent. Он генерирует изображения из промптов на естественном языке, диспетчеризует запрос в тот вендорский CLI, в котором вы аутентифицированы, и пишет рядом с результатом детерминированный manifest, благодаря чему каждый запуск воспроизводим.

Навык автоматически активируется по ключевым словам image, illustration, visual asset, concept art, либо когда другому навыку нужно изображение в качестве побочного результата (hero-кадр, миниатюра, продуктовое фото).

Когда использовать

Генерация изображений, иллюстраций, продуктовых фото, концепт-арта, hero/landing-визуалов
Сравнение одного и того же промпта на разных моделях бок о бок (--vendor all)
Производство ассетов из редакторского рабочего процесса (Claude Code, Codex, Gemini CLI)
Когда другой навык (дизайн, маркетинг, документация) вызывает image-конвейер как общую инфраструктуру

Когда НЕ использовать

Редактирование или ретушь существующего изображения — вне зоны ответственности (используйте отдельный инструмент)
Генерация видео или аудио — вне зоны ответственности
Inline SVG / векторная композиция из структурированных данных — используйте навык шаблонизации
Простое изменение размера / конвертация формата — используйте библиотеку для работы с изображениями, а не конвейер генерации

Краткий обзор вендоров

Навык построен по принципу CLI-first: если нативный CLI вендора может вернуть сырые байты изображения, путь через подпроцесс предпочтительнее прямого API-ключа.

Вендор	Стратегия	Модели	Триггер	Стоимость
`pollinations`	Прямой HTTP	Бесплатно: `flux`, `zimage`. По кредитам: `qwen-image`, `wan-image`, `gpt-image-2`, `klein`, `kontext`, `gptimage`, `gptimage-large`	Установлен `POLLINATIONS_API_KEY` (бесплатная регистрация на https://enter.pollinations.ai)	Бесплатно для `flux` / `zimage`
`codex`	CLI-first — `codex exec` через ChatGPT OAuth	`gpt-image-2`	`codex login` (API-ключ не нужен)	Списывается с вашего тарифа ChatGPT
`gemini`	CLI-first → откат на прямой API	`gemini-2.5-flash-image`, `gemini-3.1-flash-image-preview`	`gemini auth login` или `GEMINI_API_KEY` + биллинг	По умолчанию отключён; требуется биллинг

pollinations — вендор по умолчанию, потому что flux / zimage бесплатны, поэтому автоматический триггер по ключевым словам безопасен.

Быстрый старт

# Бесплатно, без настройки — использует pollinations/flux
oma image generate "minimalist sunrise over mountains"

# Сравнить параллельно всех аутентифицированных вендоров
oma image generate "cat astronaut" --vendor all

# Конкретный вендор + размер + количество, без подтверждения стоимости
oma image generate "logo concept" --vendor codex --size 1024x1024 -n 3 -y

# Оценка стоимости без расходов
oma image generate "test prompt" --dry-run

# Проверить аутентификацию и статус установки по каждому вендору
oma image doctor

# Список зарегистрированных вендоров и поддерживаемых ими моделей
oma image list-vendors

oma img — алиас для oma image.

Slash-команда (внутри редактора)

/oma-image a red apple on white background
/oma-image --vendor all --size 1536x1024 jeju coastline at sunset
/oma-image -n 3 --quality high --out ./hero "minimalist dashboard hero illustration"

Slash-команда перенаправляется в тот же конвейер oma image generate — здесь работают все CLI-флаги.

Справочник CLI

oma image generate "<prompt>"
  [--vendor auto|codex|pollinations|gemini|all]
  [-n 1..5]
  [--size 1024x1024|1024x1536|1536x1024|auto]
  [--quality low|medium|high|auto]
  [--out <dir>] [--allow-external-out]
  [-r <path>]...
  [--timeout 180] [-y] [--no-prompt-in-manifest]
  [--dry-run] [--format text|json]

oma image doctor
oma image list-vendors

Ключевые флаги

Флаг	Назначение
`--vendor <name>`	`auto`, `pollinations`, `codex`, `gemini` или `all`. При `all` каждый запрошенный вендор должен быть аутентифицирован (строгий режим).
`-n, --count <n>`	Количество изображений на вендора, 1–5 (ограничение по wall-time).
`--size <size>`	Соотношение сторон: `1024x1024` (квадрат), `1024x1536` (портрет), `1536x1024` (пейзаж) или `auto`.
`--quality <level>`	`low`, `medium`, `high` или `auto` (значение по умолчанию вендора).
`--out <dir>`	Директория вывода. По умолчанию `.agents/results/images/{timestamp}/`. Пути вне `$PWD` требуют `--allow-external-out`.
`-r, --reference <path>`	До 10 эталонных изображений (PNG/JPEG/GIF/WebP, ≤ 5 МБ каждое). Допускается повторение или перечисление через запятую. Поддерживается на `codex` и `gemini`; отвергается на `pollinations`.
`-y, --yes`	Пропустить запрос подтверждения стоимости для запусков с оценкой ≥ `$0.20`. Также через `OMA_IMAGE_YES=1`.
`--no-prompt-in-manifest`	Записывать SHA-256 промпта вместо сырого текста в `manifest.json`.
`--dry-run`	Вывести план и оценку стоимости без расходов.
`--format text\|json`	Формат вывода CLI. JSON — точка интеграции для других навыков.
`--strategy <list>`	Эскалация только для Gemini, например `mcp,stream,api`. Переопределяет `vendors.gemini.strategies`.

Эталонные изображения

Прикрепите до 10 эталонных изображений, чтобы задать стиль, идентичность субъекта или композицию.

oma image generate -r ~/Downloads/otter.jpeg "same otter in dramatic lighting" --vendor codex
oma image generate -r a.png -r b.png "blend these styles" --vendor gemini
oma image generate -r a.png,b.png "blend these styles" --vendor gemini

Вендор	Поддержка эталонов	Как
`codex` (gpt-image-2)	Да	Передаёт `-i <path>` в `codex exec`
`gemini` (2.5-flash-image)	Да	Встраивает base64 `inlineData` в запрос
`pollinations`	Нет	Отвергается с кодом выхода 4 (требуется хостинг по URL)

Где находятся прикреплённые изображения

Claude Code — ~/.claude/image-cache/<session>/N.png, отображаются в системных сообщениях как [Image: source: <path>]. Привязаны к сессии: скопируйте в постоянное место, если хотите использовать позже.
Antigravity — директория загрузок рабочей области (IDE показывает точный путь)
Codex CLI как хост — должен передаваться явно; вложения внутри диалога не пробрасываются

Когда пользователь прикрепляет изображение и просит сгенерировать или отредактировать новое на его основе, вызывающий агент обязан пробросить его через --reference <path>, а не описывать словами. Если локальный CLI слишком старый и не поддерживает --reference, выполните oma update и повторите попытку.

Структура вывода

Каждый запуск пишет в .agents/results/images/ директорию с временной меткой и хеш-суффиксом:

.agents/results/images/
├── 20260424-143052-ab12cd/                 # запуск с одним вендором
│   ├── pollinations-flux.jpg
│   └── manifest.json
└── 20260424-143122-7z9kqw-compare/         # запуск --vendor all
    ├── codex-gpt-image-2.png
    ├── pollinations-flux.jpg
    └── manifest.json

manifest.json фиксирует вендора, модель, промпт (или его SHA-256), размер, качество и стоимость — каждый запуск воспроизводим только из манифеста.

Стоимость, безопасность и отмена

Защита от перерасхода — запуски с оценкой ≥ $0.20 запрашивают подтверждение. Обход через -y или OMA_IMAGE_YES=1. pollinations по умолчанию (flux/zimage) бесплатен, поэтому подтверждение для него пропускается автоматически.
Безопасность путей — выходные пути вне $PWD требуют --allow-external-out, чтобы избежать неожиданных записей.
Возможность отмены — Ctrl+C (SIGINT/SIGTERM) прерывает все активные вызовы провайдеров и оркестратор разом.
Детерминированные результаты — manifest.json всегда пишется рядом с изображениями.
Максимум n = 5 — ограничение по wall-time, а не квота.
Коды выхода — согласованы с oma search fetch: 0 ok, 1 general, 2 safety, 3 not-found, 4 invalid-input, 5 auth-required, 6 timeout.

Протокол уточнений

Перед вызовом oma image generate вызывающий агент проходит этот чек-лист. Если чего-то не хватает и невозможно вывести из контекста, он либо спрашивает, либо расширяет промпт и показывает расширение для подтверждения.

Обязательно:

Субъект — что является главным объектом изображения? (предмет, человек, сцена)
Окружение / фон — где это происходит?

Настоятельно рекомендуется (спросить, если отсутствует и невыводимо):

Стиль — фотореализм, иллюстрация, 3D-рендер, масляная живопись, концепт-арт, плоский вектор?
Настроение / освещение — яркое или мрачное, тёплое или холодное, драматичное или минималистичное
Контекст использования — hero-изображение, иконка, миниатюра, продуктовый кадр, постер?
Соотношение сторон — квадрат, портрет или пейзаж

Для краткого промпта вроде "a red apple" агент не задаёт уточняющих вопросов. Вместо этого он расширяет inline и показывает пользователю:

Пользователь: "a red apple" Агент: "Я сгенерирую так: a single glossy red apple centered on a clean white background, soft studio lighting, photorealistic, shallow depth of field, 1024×1024. Продолжать или предпочтёте другой стиль/композицию?"

Когда пользователь предоставил полный креативный бриф (≥ 2 из: субъект + стиль + освещение + композиция), его промпт уважается дословно — без уточнений и без расширения.

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

Общий вызов (из других навыков)

Другие навыки вызывают генерацию изображений как общую инфраструктуру:

oma image generate "<prompt>" --format json

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

Конфигурация

Конфиг проекта: config/image-config.yaml
Переменные окружения:
- OMA_IMAGE_DEFAULT_VENDOR — переопределяет вендора по умолчанию (иначе pollinations)
- OMA_IMAGE_DEFAULT_OUT — переопределяет директорию вывода по умолчанию
- OMA_IMAGE_YES — 1 для обхода подтверждения стоимости
- POLLINATIONS_API_KEY — требуется для вендора pollinations (бесплатная регистрация)
- GEMINI_API_KEY — требуется, когда вендор gemini откатывается на прямой API
- OMA_IMAGE_GEMINI_STRATEGIES — порядок эскалации для gemini через запятую (mcp,stream,api)

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

Симптом	Вероятная причина	Решение
Код выхода `5` (auth-required)	Выбранный вендор не аутентифицирован	Запустите `oma image doctor`, чтобы увидеть, какому вендору нужен вход. Затем `codex login` / задайте `POLLINATIONS_API_KEY` / `gemini auth login`.
Код выхода `4` на `--reference`	`pollinations` отвергает эталоны, либо файл слишком большой / неверный формат	Переключитесь на `--vendor codex` или `--vendor gemini`. Каждый эталон должен быть ≤ 5 МБ и в PNG/JPEG/GIF/WebP.
`--reference` не распознан	Локальный CLI устарел	Запустите `oma update` и повторите. Не откатывайтесь к описанию словами.
Подтверждение стоимости блокирует автоматизацию	Запуск оценён в ≥ `$0.20`	Передайте `-y` или установите `OMA_IMAGE_YES=1`. Лучше: переключитесь на бесплатный `pollinations`.
`--vendor all` сразу прерывается	Один из запрошенных вендоров не аутентифицирован (строгий режим)	Аутентифицируйте недостающий вендор или выберите конкретный `--vendor`.
Вывод записан в неожиданную директорию	По умолчанию `.agents/results/images/{timestamp}/`	Передайте `--out <dir>`. Пути вне `$PWD` требуют `--allow-external-out`.
Gemini не возвращает байты изображения	Агентский цикл Gemini CLI не отдаёт сырые `inlineData` в stdout (по состоянию на 0.38)	Провайдер автоматически откатывается на прямой API. Установите `GEMINI_API_KEY` и убедитесь, что биллинг включён.

Связанное

Навыки — двухслойная архитектура навыков, на которой работает oma-image
Команды CLI — полный справочник команд oma image
Опции CLI — матрица глобальных опций

Когда использовать​

Когда НЕ использовать​

Краткий обзор вендоров​

Быстрый старт​

Slash-команда (внутри редактора)​

Справочник CLI​

Ключевые флаги​

Эталонные изображения​

Где находятся прикреплённые изображения​

Структура вывода​

Стоимость, безопасность и отмена​

Протокол уточнений​

Общий вызов (из других навыков)​

Конфигурация​

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

Связанное​