image-gen

Генерирует и редактирует изображения через API laozhang.ai — шлюз к моделям GPT Image — или напрямую через официальный OpenAI Images API (раздел «Провайдеры»). Всё, что нужно от пользователя: ключ LAOZHANG_API_KEY и/или OPENAI_API_KEY в ~/.config/media-skills/image-gen.env либо вход Codex по подписке ChatGPT (codex login, провайдер codex) (установка и ключи: README.md). Видео из картинки и петли для сайта — раздел «Видео из картинки» в конце и references/video.md.

Ниже SKILL — абсолютный путь к папке этого файла, PY="$SKILL/.venv/bin/python" (создаётся setup.py).

Модель по умолчанию: gpt-image-2.5 (у laozhang уходит как gpt-image-2.5-web, $0.03 за запрос). Если веб-линия отвечает HTTP 500 do_request_failed (линия лежит у провайдера, запрос не тарифицируется), generate.py сам повторяет его один раз на официальной gpt-image-2.5-flare-vip по той же цене. gpt-image-2 — только когда пользователь явно попросил старую модель.

Провайдеры: laozhang по умолчанию; официальный OpenAI — флагом --provider openai и автоматически, когда у laozhang недоступны линии 2.5 (если задан OPENAI_API_KEY). Подробно: раздел «Провайдеры: laozhang и OpenAI». Codex по подписке ChatGPT — --provider codex (раздел «Провайдер codex»). Провайдер по умолчанию задаёт IMAGE_GEN_PROVIDER в image-gen.env; если там codex, все команды ниже без --provider идут через Codex.

⛔ Параллельность и деньги

1. Запускать несколько generate.py одновременно нельзя: скрипт держит file-lock и второй процесс ждёт/падает.
2. Параллель — только через batch_generate.py (один процесс, lock, журнал, до 4 потоков).
3. Таймаут на клиенте НЕ отменяет запрос на сервере: картинка всё равно тарифицируется.
4. После отправки запроса — ноль автоповторов на ReadTimeout и ConnectionError.
5. Каждый POST пишется в журнал ledger.jsonl ДО отправки, с полным промптом.
6. Статус unknown_billed (таймаут, обрыв, 5xx) — НЕ перегенерировать автоматически. Сначала проверить историю запросов в кабинете laozhang (api2.laozhang.ai/log) и спросить пользователя.

API: POST https://api2.laozhang.ai/v1/images/generations, с --ref — /v1/images/edits (multipart image[]). OpenAI: POST https://api.openai.com/v1/images/generations и /v1/images/edits, ключ OPENAI_API_KEY. Ключи скрипт берёт сам: переменная окружения → ~/.config/media-skills/image-gen.env. Значение ключа нигде не печатается.

Скрипты:

Шаг 1 — Сбор запроса

Принять свободное описание. Если оно слишком короткое (меньше 5 слов) — уточнить только то, что меняет результат: что изображено, настроение/стиль, для чего (пост, реклама, мокап, сайт) и формат. Если описание достаточное — сразу к шагу 2.

Шаг 2 — Переписать промпт

Переписать запрос в короткий промпт (обычно по-английски).

Главное правило: не зажимать модель

GPT Image умная: освещение, композицию и детали она додумает сама. Промпт передаёт идею и настроение, а не техзадание.

Плохо (зажато): A studio product shot of a sleek smartphone, placed upright on a clean white surface, modern minimalist style, softbox lighting from left, sharp focus, 50mm macro lens, overhead slight angle, clean and premium mood, pure white background

Хорошо (свободно): Premium smartphone product shot, clean white background, modern and minimal

Плохо: dark rounded rectangle badge with a small lock icon and bold text saying "5 уроков"

Хорошо: красивая акцентная плашка про 5 уроков

Правила

• 1–3 предложения.
• Описывать, что хочешь видеть, а не как это технически сделать.
• Стиль одним словом: cinematic, 3D, editorial, product, flat illustration.
• Не прописывать линзы, ISO, f-stop, конкретные hex-цвета.
• Для брендов: «фирменный цвет бренда X», а не #FF6B35.
• Для UI-элементов: намерение («красивая плашка»), а не конкретика («rounded rectangle with lock icon»).
• Для правки (--ref) — ещё короче: модель уже видит картинку. Описывать только изменение.

Исключение: макеты с точным текстом

Когда на картинке нужен конкретный текст (плакат в руках, рекламный макет, обложка), правила выше не действуют. Промпт пишется на языке текста, длинный, с дословным перечислением строк, цветом и кеглем каждой. Кириллица на GPT Image 2.5 держится чисто: и многострочный макет, и мелкий текст внутри карточек, и подписи под иконками. С --ref точно переносятся лицо человека, фирменный стиль и логотип, поэтому сложные макеты выходят с первого раза. Отказываться от такой генерации или предлагать вместо неё вёрстку не нужно.

Ограничения, проверенные на практике:

• Фотографию из референса модель воспроизводит близко, но не пиксель в пиксель. Где нужна точная копия снимка, его вставляют в готовый макет отдельным шагом.
• С --ref модель склонна копировать текст с референса и игнорировать правку цифры. Если меняется только число или дата — генерировать без референса или проверять каждую цифру глазами.
• Редкие буквы (казахские Ң, Ү, Ө и подобные) в мелком кегле ломаются: держите такие строки короткими и крупными, проверяйте увеличением. Слова «неровные штрихи», «небрежный почерк» в промпте убивают читаемость.
• Каждую готовую картинку смотреть глазами до выдачи: текст, руки, лица, логотипы.

Как показывать промпт пользователю

📝 Промпт:
[переписанный промпт одной строкой]

⚙️ Параметры: ratio [X:X] · model gpt-image-2.5 · provider laozhang
💰 Стоимость: $0.03

С --provider openai в строке стоимости оценка из таблицы «Провайдеры» (качество и размер), например ≈$0.043 (high, 9:16); фактическую цену скрипт печатает после ответа.

Если пользователь уже сказал «генерируй сразу» или поручил задачу целиком — не добавлять лишний шаг согласования. Иначе показать промпт и ждать «ок / давай»; при правках — скорректировать и показать снова.

Шаг 3 — Генерация

# Текст → картинка
"$PY" "$SKILL/generate.py" --prompt "..." --ratio 1:1 --name cover --project acme/2026-10-02-launch

# Правка / композиция по референсам (image-to-image)
"$PY" "$SKILL/generate.py" --prompt "..." --ratio 4:5 --ref /abs/ref1.png /abs/ref2.png --name cover-v2

# Официальный OpenAI: качество по умолчанию medium; high руками для живых людей и лиц
"$PY" "$SKILL/generate.py" --provider openai --quality medium --prompt "..." --ratio 9:16 --name hero

# Вырезанный объект с прозрачным фоном (PNG с альфой, без хромакея)
"$PY" "$SKILL/generate.py" --provider openai --background transparent --prompt "..." --ratio 1:1 --name cutout

# Старая модель — только по явной просьбе
"$PY" "$SKILL/generate.py" --prompt "..." --model gpt-image-2 --name legacy

В конце скрипт печатает строку __FILE__:<путь> — рабочая копия для доставки (чат-бот или агент может приложить её). Постоянный файл — путь, который вернул скрипт (см. «Хранение»). Не конструировать путь как <name>.png вручную.

Пакет (2+ картинок)

# Через JSONL (рекомендуется от 3 картинок)
"$PY" "$SKILL/batch_generate.py" --jobs /abs/jobs.jsonl --project acme/2026-10-02-launch

# Через аргументы
"$PY" "$SKILL/batch_generate.py" --prompts "prompt 1" "prompt 2" --names one two --ratio 9:16

Формат JSONL (пример: examples/jobs.jsonl):

{"prompt": "...", "name": "file1", "ratio": "9:16"}
{"prompt": "...", "name": "file2", "ratio": "9:16", "ref": ["/abs/ref.png"], "quality": "high"}
{"prompt": "...", "name": "file3", "ratio": "9:16", "model": "gpt-image-2", "keep_2k": true, "project": "acme/2026-10-02-launch"}
{"prompt": "...", "name": "file4", "ratio": "9:16", "provider": "openai", "quality": "medium"}
{"prompt": "...", "name": "file5", "ratio": "1:1", "provider": "openai", "background": "transparent", "moderation": "low"}

--provider openai в командной строке ставит OpenAI всем задачам без своего provider.

--parallel по умолчанию min(число картинок, 4); три параллельных запроса на 2.5 проходят без 429. --parallel 1 — для осторожности с тяжёлыми референсами. У OpenAI лимит в картинках в минуту (Tier 1 — 5, Tier 2 — 20): на Tier 1 ставьте --parallel 1. В конце — отчёт: success / unknown_billed / failed с причиной каждого отказа + стоимость (у OpenAI фактическая по usage). Отказы до генерации (503, 4xx, модерация) идут в failed и не тарифицируются. Код выхода 2, если что-то не дошло.

Параметры

--ratio

Генерация идёт в 2K, а на диск ложится размер доставки: цена поштучная и от размера не зависит, а держать 2K везде незачем.

--model

Любая другая модель отвергается до отправки. Доступность линий зависит от группы вашего токена у laozhang (GET /v1/models показывает, что видит ключ). Цены — оценка по прайсу провайдера, не гарантия биллинга. Документация: https://docs.laozhang.ai/api-capabilities/gpt-image-2-5

С --provider openai те же алиасы уходят в OpenAI как: gpt-image-2.5 и gpt-image-2.5-flare → gpt-image-2.5-flare (быстрая, по умолчанию), gpt-image-2.5-sunburst → gpt-image-2.5-sunburst (точнее держит исходник в правках по --ref), gpt-image-2 → gpt-image-2 (только по явной просьбе). Цена за токен у всех одинаковая.

--quality

low / medium / high / xhigh / max. У laozhang без флага параметр не передаётся. Веб-линия значение принимает, но время и расход от него не меняются; реальный эффект — на flare/sunburst.

У OpenAI качество — это число выходных токенов, то есть детализация и прямо цена. Без флага скрипт шлёт medium: иначе OpenAI сам выбирает уровень (auto) и цена плавает. high ставить руками. Таблица — в разделе «Провайдеры».

--provider

laozhang (по умолчанию), openai или codex. В пакете — поле "provider" у задачи или --provider на всю пачку. Без флага берётся IMAGE_GEN_PROVIDER из image-gen.env.

--background

transparent или opaque. transparent даёт PNG с настоящей альфой — вырезанные предметы и герои для моушена без зелёного фона. У laozhang работает только на vip-линиях.

--moderation

Только OpenAI: auto (по умолчанию) или low — мягче фильтр. Ставить, когда в сцене тело, купальники, медицина, и запрос отбили с moderation_blocked. Это для ложных срабатываний, не для обхода правил.

--size

Обычно не нужен: размер задаётся через --ratio. Явный --size ШxВ уходит в API как есть. Правила API (скрипт проверяет до отправки):

• стороны кратны 16 (1080x1920 не примут — писать 1088x1920);
• сторона не больше 3840;
• соотношение от 1:3 до 3:1;
• пикселей от 655 360 до 8 294 400.

Ставить вместе с --keep-2k, иначе файл ужмётся до размера доставки:

--ratio 9:16 --size 2160x3840 --keep-2k    # вертикальный 4K

--keep-2k

Сохраняет разрешение оригинала (сжатие веса всё равно выполняется). Нужен, когда картинка потом ложится на холст шире 1080: обложки и hero на 2160 px, печать, кадры для видео-моделей. В остальных случаях не нужен.

--ref

--ref /abs/image1.png                   # один референс
--ref /abs/img1.png /abs/img2.png       # несколько

Когда: правка существующей картинки (цвет, элемент, текст), перенос стиля, композиция из нескольких картинок, продукт на новом фоне, консистентность персонажа (одно и то же лицо в серии).

--project

--project <клиент>/<дата-слаг> — промпт и картинки ложатся в папку проекта (см. «Журнал»). Ставьте всегда, когда работа идёт для конкретного клиента/задачи: потом легко найти, что уже генерировали.

Сжатие и хранение

После каждой успешной генерации файл сжимается: JPEG quality 95, subsampling 4:4:4. Прозрачность остаётся в PNG (compress_level=3), без белой подложки. Если перекодирование увеличивает вес, остаётся исходник. При ошибке сжатия оригинал остаётся в архиве — повторный платный запрос не нужен. Сжатие с потерями минимально (PSNR 45–49 dB на портретах, фото, макетах с текстом), вес в среднем −70%.

Постоянные файлы (база IMAGE_GEN_DATA_DIR, по умолчанию ~/.local/share/image-gen):

• с --project → <база>/creatives/<project>/images/image-<уникально>/<name>.jpg;
• без проекта → <база>/image-gen/images/YYYY-MM/image-<уникально>/<name>.jpg.

Расширение бывает .png или .webp, если сохранена прозрачность/исходник. Уникальная папка не даёт перезаписать одноимённые генерации. generate_image() возвращает фактический постоянный путь; его же пишут журналы. Рабочие копии и lock живут в ~/.cache/image-gen (база IMAGE_GEN_CACHE_DIR).

Готовое изображение (исходник не меняется, разрешение сохраняется):

"$PY" "$SKILL/compress.py" --input /abs/photo.png --project acme/assets

Не прогонять уже сжатый файл повторно: для выдачи и загрузки использовать полученный постоянный путь.

Журнал промптов — что уже генерировали

Каждая генерация (успешная и нет) пишется в два места:

• <база>/image-gen/ledger.jsonl — машинный журнал: полный промпт, модель, размер, quality, refs, project, статус, время, путь результата;
• Markdown для глаз и повторного использования промптов:
  • без --project → <база>/image-gen/prompts/YYYY-MM.md;
  • с --project → <база>/creatives/<project>/prompts.md.

Журнал — личный: у каждого пользователя он начинается пустым и в git не попадает. Подробно: references/storage.md.

Провайдеры: laozhang и OpenAI

Замер OpenAI (октябрь 2026), flare, 1152x2048 (9:16), простой промпт:

• Квадрат 1:1 в OpenAI запрашивается как 1024x1024 (2048x2048 стоит в 2.5 раза дороже); явный --size 2048x2048 по-прежнему работает.
• Площадь дорожает быстрее линейного, меньше 9:16 2K цена почти не падает. Скрипт оценивает цену до отправки, факт пишет после ответа.
• Каждый --ref добавляет ≈1500 входных image-токенов (≈$0.012). Правка по референсу на OpenAI держит сцену точно: композиция, свет и предметы остаются, меняется только названное.
• Лимит OpenAI — картинки в минуту по уровню аккаунта (Tier 1 — 5, Tier 2 — 20, Tier 3 — 50); текущий виден на platform.openai.com → Limits.
• Факт списания по каждой картинке: строка "status": "billed" в ledger.jsonl (usage + cost_usd) и цена в prompts.md.

Когда что брать:

• обычная генерация — дефолт (laozhang, при его падении скрипт сам уйдёт в OpenAI);
• нужна скорость, предсказуемость или серия картинок для ролика — --provider openai;
• по умолчанию medium: фоны, предметы, иллюстрации, макеты;
• --quality high руками для фотореалистичных людей и лиц: на medium кожа глянцевая, на high живая текстура;
• xhigh/max — только для одиночных героев крупным планом;
• вырезанные объекты — --provider openai --background transparent.

Провайдер codex (подписка ChatGPT)

generate.py --provider codex запускает официальный codex exec, который вызывает встроенный инструмент image_gen (GPT Image) в счёт подписки ChatGPT: ни ключей, ни оплаты за картинку. Вход держит сам Codex (codex login, на сервере codex login --device-auth); скрипт токены не читает.

• --ref работает (до 5 картинок): референсы прикладываются к запросу Codex как изображения.
• --ratio передаётся словами в промпт; размер выбирает модель (9:16 ≈ 941x1672, 1:1 ≈ 1254x1254, 4:5 ≈ 1122x1402). Нужен 2K и больше — потом upscale.py.
• --quality, --size, --moderation не действуют. --background transparent передаётся просьбой в промпт.
• 30–60 с на картинку. Пакет batch_generate.py с "provider": "codex" идёт так же, до 4 потоков; лимиты общие с подпиской Codex, при исчерпании Codex вернёт ошибку (NotBilledError, ничего не списано).
• Ошибка «Codex не вернул картинку … codex login» — вход протух: пользователю выполнить codex login --device-auth.
• Журнал и промпты пишутся как у остальных провайдеров, цена $0.000.

Ошибки — что значит код и платим ли мы

Когда у laozhang исчерпаны повторы на линиях 2.5 (503 или do_request_failed), скрипт переходит в OpenAI на ту же модель (flare/sunburst), quality по умолчанию medium, и печатает строку у laozhang 2.5 недоступна, перехожу в OpenAI. gpt-image-2 не переводится. Без ключа OpenAI — failed, ничего не списано.

Примеры промптов

Пользователь: «нарисуй тёмный постер про AI» Промпт: Dark moody AI poster, glowing neural network, futuristic and mysterious

Пользователь: «фото продукта для рекламы» Промпт: Premium smartphone product shot, clean white background, modern and minimal

Пользователь: «обложка карусели: 4 суперсилы нейросети» Промпт: Instagram carousel cover, glowing AI assistant logo crushing a stack of paperwork, 3D epic scene, dark background with fire, bold text "4 СУПЕРСИЛЫ"

Пользователь: (с --ref) «сделай заголовок оранжевым, плашку богаче» Промпт: Make the headline brand orange and the lessons badge look more premium

Пользователь: «рекламный баннер 9:16 со скидкой» Промпт (точный текст): Вертикальный рекламный баннер кофейни. Сверху огромными белыми буквами в две строки: «КОФЕ −30%». Ниже меньшим кремовым шрифтом: «только до воскресенья». Внизу тёплое фото капучино на деревянном столе, мягкий утренний свет. Низ кадра чистый.

Больше шаблонов и разбор частых ошибок: references/prompting.md.

Апскейл — когда нужно качество, а не новая картинка

Жалоба «мыло, шум, волосы нечёткие» на готовом креативе — это апскейл, а не генерация. Перегенерация через --ref рисует кадр заново: текст переносится, но лицо человека выходит другим.

python3 "$SKILL/setup.py" --with-upscale        # один раз: torch CPU + spandrel (~1 ГБ)
"$PY" "$SKILL/upscale.py" --input /abs/original.png --output /abs/name_4k.png --size 2160x3840

Real-ESRGAN x4 на CPU снимает шум и мыло, сохраняя лицо, текст и композицию. Мелкие детали он восстанавливает нейросетью, поэтому оригинал храните, а результат сравнивайте увеличением. Считает долго: кадр 1080x1920 — 60 тайлов, ≈20 минут на 6 ядрах. Запускайте в фоне и не заворачивайте вывод в tail: прогресс идёт по тайлам.

Несколько картинок — параллельно, по процессу на файл, потоки делить по ядрам (6 ядер = 3 процесса по --threads 2):

for n in 1 2 3; do
  "$PY" "$SKILL/upscale.py" --input p$n.jpg --output out$n.png --size 2160x3840 --threads 2 > log$n.txt 2>&1 &
done; wait

Три фото так заканчиваются за ~36 минут вместо часа по очереди. Больше процессов, чем ядер — начнётся своп. Веса Real-ESRGAN скачиваются при первом запуске в ~/.cache/image-gen/models/. Подробнее: references/upscale.md.

Генерация сразу в 4K (--size 2160x3840 --keep-2k) — для случая, когда нужна новая картинка, а не спасение старой.

Видео из картинки (Seedance 2.0)

Для «оживи картинку», «сделай видео из кадра», «зацикленная анимация для сайта». Полный рецепт с ценами, промптом, сжатием, встраиванием и проверкой: references/video.md.

⛔ Модель и бюджет видео

1. По умолчанию Seedance 2.0 (doubao-seedance-2-0-260128): движение аккуратнее и детальнее. Wan 2.7 подключён, но только по явной просьбе — не предлагать как дешёвую замену.
2. Видео дорогое: Seedance 5 с 720p ≈ $0.90. Сначала кадры через image-gen ($0.03), видео — после одобрения кадра.
3. Одна платная генерация на задачу, больше — только с явного «да». video_generate.py не отправит повторно то же --name.
4. Сначала --dry-run: тело запроса и цена. Нет ответа после отправки = могло списаться, не повторять.
5. Ключ LAOZHANG_SEEDANCE_API_KEY (токен группы SeeDance2) с оплатой по объёму; ответ 503 «pay-per-request» значит, что тип оплаты токена нужно переключить в консоли laozhang. Ничего не списано.

Как кадры попадают в модель. Видео-модель работает на чужом сервере и скачивает кадр по https-ссылке. Варианты: передать готовую https-ссылку в --first/--last, или настроить свою публичную папку (IMAGE_GEN_PUBLIC_DIR + IMAGE_GEN_PUBLIC_URL): тогда video_generate.py сам выложит локальный кадр под случайным именем, проверит, что ссылка открывается, и удалит файл после завершения задачи.

Порядок:

1. Кадры: первый, и последний — правкой первого (--ref): тот же ракурс, свет и фон, меняется только нужное.
2. bg_recolor.py перекрашивает ровный фон кадров в точный цвет блока сайта — видео растворяется в странице.
3. video_generate.py create … --dry-run, после согласия то же без --dry-run, затем poll.
4. video_loop.py raw.mp4 --mode pingpong --ease 12 для перехода A→B→A: Seedance двигает объект с первого кадра, --ease убирает рывок на развороте. --bg '#hex' выравнивает фон, --size = ширина показа на десктопе × 2. Выход: AV1 + H.264 + постер с хешем в имени и готовый <video>; скрипт ленивой загрузки — в references/video.md.

Качество: не пережимать. H.264 960 px CRF 32 даёт заметное мыло; хороший баланс — AV1 CRF 36 + H.264 CRF 24 в 1280 px. GIF не использовать: та же петля в GIF весит 22 МБ при 640 px и даёт полосы на градиентах.

"$PY" "$SKILL/bg_recolor.py" a.jpg first.png --color '#ff5715' --size 1280
"$PY" "$SKILL/video_generate.py" create --name acme-coin --first first.png --last last.png \
  --prompt "…" --negative "…" --duration 5 --resolution 720p --project acme/2026-10-02-coin --dry-run
"$PY" "$SKILL/video_generate.py" poll --name acme-coin
"$PY" "$SKILL/video_loop.py" <база>/creatives/acme/2026-10-02-coin/videos/acme-coin/raw.mp4 \
  --name coin --out-dir <сайт>/public/assets --mode pingpong --ease 12 --bg '#ff5715' --size 1280

Wan 2.7, только по явной просьбе: --model wan (токен LAOZHANG_WAN_API_KEY, группа Wan, около $0.45 за 5 с 720P). У Wan на краях ролика почти секунда стоянки: в video_loop.py вместо --ease подрезать --trim 10 139.

Связанные скиллы

• Монтаж и анимация нескольких картинок, моушен-реклама, ролики: motion-video.
• Озвучка: elevenlabs-voice.

Проверка установки без платных запросов

"$PY" -m unittest discover -s "$SKILL/tests" -v