Генерация по референсному изображению: как это работает

Обновление, октябрь 2026. Генерация изображений через Zukko временно недоступна. Актуальный список моделей — страница «Модели»↗ или GET https://api.zukko.pro/v1/models. Ближайшая замена: прямой замены среди доступных моделей нет; для анализа изображений (vision) подойдут модели Claude и GPT, например claude-sonnet-5 или gpt-5.6-sol.

Генерация изображений в шлюзе делится на три режима, и режим определяется не отдельным параметром, а выбором модели. Если задача — перенести стиль или композицию образца на новую сцену, нужна конкретная модель: nano-banana-2-reference-to-image-developer.

Чем reference отличается от edit

Эти два режима легко перепутать, потому что оба принимают исходное изображение на входе.

nano-banana-2-edit-developer меняет ту же самую картинку: убрать объект, перекрасить фон, дорисовать деталь — результат остаётся узнаваемо тем же кадром, просто с внесённой правкой.

nano-banana-2-reference-to-image-developer строит совершенно новую сцену с нуля по тексту в prompt, а образец передаёт только стиль, палитру или композицию — не конкретные пиксели. Если нужный результат описывается как «тот же герой, но в другой обстановке» или «в такой же манере, но другой сюжет» — это reference, а не edit.

Формат запроса

curl https://api.zukko.pro/v1/images/generations \
  -H "Authorization: Bearer fetch_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2-reference-to-image-developer",
    "prompt": "Тот же персонаж сидит за рабочим столом в офисе, дневной свет из окна",
    "images": ["https://example.com/character-reference.png"]
  }'

Поле images — массив, можно передать публичную ссылку на файл или data URL напрямую (data:image/png;base64,...). Для изображений, которых нет по публичному адресу, data URL удобнее: не нужно ничего заранее выкладывать в сеть, только закодировать файл в base64 на своей стороне.

Что переносится хорошо, а что нет

Общий стиль, цветовую палитру и композицию модель держит уверенно. С точным повторением конкретных деталей — лицо, логотип, узнаваемый узор на ткани — хуже: чем специфичнее деталь, тем выше шанс, что она поплывёт при построении новой сцены. Если в проекте критична точность одного элемента, например логотип должен остаться пиксель в пиксель, надёжнее собрать композицию отдельно и наложить элемент постобработкой, а не полагаться на reference целиком.

Несколько образцов в одном запросе технически допустимы — images это массив, а не одиночное поле. Но чем больше картинок в списке, тем менее предсказуемо, чей стиль в итоге победит в генерации. На практике один чёткий референс работает стабильнее, чем два-три смешанных с разной эстетикой.

Частая ошибка: не тот идентификатор модели

images работает только с моделями, которые вообще принимают вход-изображение. Отправить это поле в nano-banana-2-text-to-image бессмысленно — эта модель обучена только на prompt, режим определяется исключительно идентификатором модели, а не набором полей в теле запроса. Если результат генерации выглядит так, будто референс вообще не учли, первое, что стоит проверить — действительно ли в model указан nano-banana-2-reference-to-image-developer, а не text-to-image вариант по невнимательности.

То же самое верно и для линейки OpenAI-совместимых image-моделей в каталоге: у openai-gpt-image-2-text-to-image и openai-gpt-image-2-edit нет отдельного reference-режима, только text-to-image и edit. Актуальный список идентификаторов моделей отдаёт /v1/models (в нём только id, object, created, owned_by), а цены и параметры моделей — /v1/models/info:

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

Биллинг

Изображения тарифицируются за штуку, а не по токенам — kind=image в каталоге моделей означает отдельную схему оплаты, независимую от длины prompt. Точную актуальную цену для конкретной модели, включая nano-banana-2-reference-to-image-developer, стоит смотреть в расширенном списке, а не держать цифру в голове или в старой заметке:

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

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

После каждого запроса на генерацию в ответе приходят заголовки X-Zukko-Cost-Micros — стоимость именно этого запроса в микродолларах (1 000 000 = $1) — и X-Fetch-Balance-Cents — остаток баланса после списания (несмотря на название, тоже в микродолларах; точный баланс в центах — GET /v1/balance). Если генераций много, оба заголовка удобно логировать на своей стороне вместо того, чтобы сверяться с историей в кабинете вручную.

Баланс проверяется до обращения к модели: если средств не хватает, вернётся 402 с кодом insufficient_balance, и сама генерация не запускается — неудачный запрос ничего не стоит.

Практический сценарий

Типичная задача — карточка товара в едином визуальном стиле: один и тот же продукт нужно показать на десяти разных фонах, не пересъёмкой, а генерацией. Референсом идёт исходное фото товара, а prompt на каждой итерации меняет только сцену: «на деревянном столе у окна», «на белом фоне студийного света», «в руках у человека на улице». Модель и images остаются одинаковыми, меняется только текст — это дешевле и быстрее, чем городить десять отдельных edit-запросов.

Качество исходника имеет значение. Референс с низким разрешением или в сильном сжатии несёт меньше деталей для переноса стиля, и результат выходит более общим, размытым по характеру, чем хотелось бы. Формат файла — PNG или JPEG — на результат почти не влияет, а вот чёткость и адекватное разрешение самого образца влияют напрямую.

Подключение

Адрес и ключ те же, что для остальных запросов к шлюзу: https://api.zukko.pro/v1/images/generations, заголовок Authorization: Bearer fetch_.... Ключ создаётся в кабинете на странице /app/api-keys↗ и показывается там один раз — если он был потерян, проще выпустить новый, чем пытаться его вспомнить.