Редактирование изображений через API: пошагово

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

Редактирование изображения через шлюз идёт через тот же эндпоинт, что и генерация с нуля — POST /v1/images/generations, только с моделью из edit-линейки и самим изображением в теле запроса. Разница между «сгенерировать» и «отредактировать» — это разница между моделями в каталоге, а не между эндпоинтами.

Модели для редактирования

Из каталога генерации изображений к правке относятся:

• nano-banana-2-edit-developer — редактирование по текстовому промпту
• nano-banana-2-reference-to-image-developer — генерация с опорой на референсное изображение (не чистая правка, а перенос стиля/композиции)
• openai-gpt-image-2-edit и openai-gpt-image-1.5-edit — правка в стиле OpenAI, включая работу с масками

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

Базовый запрос на редактирование

curl https://api.zukko.pro/v1/images/generations \
  -H "Authorization: Bearer fetch_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2-edit-developer",
    "prompt": "Убери фон и замени на однотонный белый",
    "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "n": 1
  }'

Изображение передаётся как data URL с base64-содержимым внутри поля image. Ответ — стандартная структура с URL или base64 результата, в зависимости от того, что модель отдаёт по умолчанию для этого типа запроса.

Редактирование с маской (openai-gpt-image)

Модели линейки openai-gpt-image поддерживают явную маску — прозрачные области указывают, что именно менять:

from openai import OpenAI

client = OpenAI(base_url="https://api.zukko.pro/v1", api_key="fetch_ваш_ключ")

result = client.images.edit(
    model="openai-gpt-image-2-edit",
    image=open("product.png", "rb"),
    mask=open("mask.png", "rb"),
    prompt="Замени фон на студийный, с мягким градиентом от серого к белому",
    n=1,
    size="1024x1024",
)
print(result.data[0].url)

mask.png должен быть того же размера, что и исходное изображение, с альфа-каналом: прозрачные пиксели — зона правки, непрозрачные — то, что остаётся нетронутым. Без маски модель интерпретирует промпт как правку всего изображения целиком.

Reference-to-image: перенос стиля

nano-banana-2-reference-to-image-developer берёт референс и применяет его характеристики (стиль, цветовую палитру, композицию) к новому изображению, сгенерированному по промпту — это не точечная правка, а генерация с оглядкой на образец:

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": "Кроссовок на белом фоне в том же стиле освещения",
    "reference_image": "data:image/png;base64,...",
    "n": 2
  }'

n: 2 запросит два варианта за один вызов — оплата идёт за каждое сгенерированное изображение, поэтому пакетный запрос из двух вариантов стоит как два отдельных.

Node.js: правка через официальный SDK

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI({
  baseURL: "https://api.zukko.pro/v1",
  apiKey: "fetch_ваш_ключ",
});

const result = await client.images.edit({
  model: "openai-gpt-image-1.5-edit",
  image: fs.createReadStream("photo.png"),
  prompt: "Добавь снег на заднем плане",
  n: 1,
});

console.log(result.data[0].url);

Проверка стоимости перед массовой обработкой

Раз оплата идёт за штуку, а не за токены, для пакетной обработки (например, правки 200 карточек товара) стоит сначала прогнать один запрос и посмотреть заголовок X-Zukko-Cost-Micros в ответе, чтобы посчитать бюджет на всю партию заранее:

curl -i https://api.zukko.pro/v1/images/generations \
  -H "Authorization: Bearer fetch_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana-2-edit-developer","prompt":"тест","image":"data:image/png;base64,..."}' \
  | grep -i x-zukko-cost-micros

Умножив цену одного вызова на количество изображений в партии, легко понять, хватит ли баланса — проверить остаток можно на GET /v1/balance.

Идемпотентность при повторной генерации

Если пайплайн ретраит запрос при сетевой ошибке, повторная генерация того же изображения спишет деньги дважды за фактически одинаковый результат промпта. Idempotency-Key здесь не поможет: идемпотентность и кэш в Zukko работают только для POST /v1/chat/completions, /v1/messages и /v1/responses, а не для /v1/images/generations. Поэтому повторы генерации стоит ограничивать на стороне пайплайна — например, сохранять результат каждой задачи и не перезапускать её, если он уже получен.

Lite-версии для черновой правки

У некоторых моделей есть постфикс -lite-* (например, у линейки nano-banana-2-text-to-image-lite-*) — это более быстрый и дешёвый вариант для черновых прогонов, когда нужно посмотреть на пять вариантов композиции перед финальной генерацией в полноценной модели. Разумный порядок работы: сначала прогнать несколько вариантов на lite-модели, выбрать лучший промпт, и только затем повторить его на полной версии для финального результата — это дешевле, чем сразу генерировать десять вариантов на дорогой модели.

Частые ошибки

400 model_not_found на модели с «-developer» в названии — опечатка в суффиксе, эти модели различаются по полному id, включая постфикс -developer или -lite-*; сверяйте точное имя через GET /v1/models.

Маска игнорируется — модели без явной поддержки масок (например, nano-banana-2-edit-developer) читают только текстовый промпт и исходное изображение; поле mask в запросе к ним не имеет эффекта, маски работают только с openai-gpt-image-*-edit.

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

Результат непохож на референс — reference_image влияет на стиль и композицию, а не гарантирует точное повторение объекта; для точной правки конкретного объекта нужен image + маска, а не референс.