Reference-based image generation: how it works

Update, October 2026. Image generation through Zukko is temporarily unavailable. The current model list is on the Models page↗ or at GET https://api.zukko.pro/v1/models. Closest replacement: there is no direct replacement among the available models; for image analysis (vision), the Claude and GPT models work, e.g. claude-sonnet-5 or gpt-5.6-sol.

Image generation in the gateway splits into three modes, and the mode is set by which model you call, not by a separate parameter. If the goal is to carry a sample's style or composition into a new scene, there's a specific model for it: nano-banana-2-reference-to-image-developer.

Reference vs. edit

These two modes are easy to mix up, because both take a source image as input.

nano-banana-2-edit-developer changes the same picture: remove an object, recolor the background, add a detail — the result stays recognizably the same shot, just with the edit applied.

nano-banana-2-reference-to-image-developer builds an entirely new scene from scratch based on the text in prompt, and the sample only supplies style, palette, or composition — not specific pixels. If what you want is "the same character but in a different setting" or "the same visual style, different subject," that's reference mode, not edit.

Request shape

curl https://api.zukko.pro/v1/images/generations \
  -H "Authorization: Bearer fetch_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2-reference-to-image-developer",
    "prompt": "The same character sitting at an office desk, daylight from a window",
    "images": ["https://example.com/character-reference.png"]
  }'

The images field is an array; you can pass a public URL or a data URL directly (data:image/png;base64,...). For images that don't live at a public address, a data URL is more convenient — nothing needs to be hosted anywhere, just base64-encoded on your side.

What transfers well and what doesn't

Overall style, color palette, and composition come through reliably. Exact reproduction of specific details — a face, a logo, a recognizable fabric pattern — is weaker: the more specific the detail, the more likely it drifts while the model builds the new scene. If a project depends on one element being pixel-exact, such as a logo, it's more reliable to compose that separately and overlay it in post rather than trust the reference pass alone.

Multiple samples in one request are technically allowed — images is an array, not a single field. But the more pictures in the list, the less predictable whose style wins out in the final generation. In practice, one clear reference performs more consistently than two or three mixed ones with different aesthetics.

The common mistake: wrong model id

images only does anything with models that actually accept image input. Sending that field to nano-banana-2-text-to-image is pointless — that model only trains on prompt; the mode is set strictly by the model identifier, not by which fields happen to be in the request body. If a generation looks like the reference was ignored entirely, the first thing to check is whether model is actually set to nano-banana-2-reference-to-image-developer and not a text-to-image variant picked by mistake.

The same applies to the OpenAI-compatible image line in the catalogue: openai-gpt-image-2-text-to-image and openai-gpt-image-2-edit have no separate reference mode, only text-to-image and edit. The current list of model ids comes from /v1/models (it only has id, object, created, owned_by), while prices and model parameters come from /v1/models/info:

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

Billing

Images are billed per piece, not per token — kind=image in the model catalogue means a separate pricing scheme, independent of prompt length. The exact current price for a specific model, including nano-banana-2-reference-to-image-developer, is worth checking in the extended listing rather than trusting a number written down somewhere else:

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

The catalogue changes over time, and keeping the price anywhere other than the source is a reliable way to eventually check against a stale figure.

Every generation response carries X-Zukko-Cost-Micros — the cost of that exact request, in micro-dollars (1,000,000 = $1) — and X-Fetch-Balance-Cents — the remaining balance after the charge (despite the name, also in micro-dollars; the exact balance in cents is at GET /v1/balance). If generations run at volume, logging both headers on your side beats reconciling against the dashboard's history by hand.

Balance is checked before the model is called: if funds run out, the response is a 402 with insufficient_balance, and the generation never starts — a failed request costs nothing.

A practical scenario

A common task is a product card in one consistent visual style: the same product needs to appear on ten different backgrounds, without reshooting, by generating each variant. The reference is the original product photo, and prompt changes only the scene on each pass: "on a wooden table by a window," "on a white studio background," "held by a person outdoors." The model and images stay the same; only the text changes — cheaper and faster than building ten separate edit requests.

Source quality matters. A low-resolution or heavily compressed reference carries fewer details to transfer, and the output ends up more generic, less true to the original character than intended. File format — PNG or JPEG — barely affects the result; the sharpness and reasonable resolution of the sample itself does.

Connecting

The address and key are the same as for any other gateway call: https://api.zukko.pro/v1/images/generations, an Authorization: Bearer fetch_... header. Keys are created in the dashboard at /app/api-keys↗ and shown there once — if one gets lost, issuing a new one is simpler than trying to recall it.