Image generation API prompt versioning: compare changes without losing provenance

Image generation API prompt versioning makes a visual change explainable. Saving only the final prompt loses the context that determines what was actually requested: model, aspect ratio, image count, seed, reference images, negative prompt, and provider-specific parameters. A useful version record captures the whole approved request and links it to its resulting job and artifacts.

Genace’s image endpoint maps prompt, aspect_ratio, n, seed, image_inputs, negative_prompt, and extra into the provider parameters. It defaults to nano-banana when no model is supplied. For comparisons, specify the model explicitly so a later default change does not silently alter your experiment.

Version the experiment, not just the sentence

The following JSON is a local experiment record. The genace_request object is the portion suitable for the image generation endpoint; the surrounding version and evaluation fields belong in your application database, not in the public request body.

{
  "prompt_version": "product-studio-v3",
  "parent_version": "product-studio-v2",
  "hypothesis": "A simpler background will improve product separation",
  "genace_request": {
    "model": "nano-banana",
    "prompt": "A ceramic travel mug on a warm gray studio surface, soft side light, clean negative space",
    "aspect_ratio": "1:1",
    "n": 1,
    "seed": 42
  },
  "evaluation": {
    "product_visibility": null,
    "background_distraction": null,
    "reviewer_notes": "Awaiting review"
  }
}

Store a canonical input hash after serializing the exact approved request. Include the content hash of each reference image when possible: a URL can point to different bytes later. Keep private source URLs in protected storage rather than publishing them in experiment summaries.

Change one variable deliberately

Choose one concrete hypothesis for a revision, such as reducing background clutter or improving room for a text overlay. Hold the model and relevant parameters constant while comparing that change. If you intentionally change the model too, label it as a separate experiment because you can no longer attribute the difference solely to prompt wording.

The current Nano Banana schema accepts one through four requested images and supports five common aspect ratios. More samples increase the requested work and credits. Keep sample count constant across versions when comparing quality per request, or record the difference explicitly in the evaluation.

A supplied seed is useful provenance, but it is not a guarantee of identical output across model changes, upstream implementation changes, or time. Retain the actual generated artifacts as evidence. Re-running a prompt later is not a substitute for storing the original result.

Link versions to jobs and decisions

Save the POST response’s job_id against the experiment version, then attach terminal snapshots and validated output records. Record why a reviewer accepted or rejected a result using a small rubric. A version is useful when another person can reconstruct the requested inputs and understand the selection decision without relying on the author’s memory.

Verification checklist

Compare two saved versions and confirm that their differences match the stated hypothesis. Check that each has an explicit model, exact request, reference hashes where applicable, job identifier, and archived outputs. Confirm that retrying artifact delivery does not create a new experiment sample.

Continue with image generation basics, JSON prompting, and output storage.

Continue with production operations

• AI video API webhook vs polling: which one to use and when
• How to call a video generation API without blocking your agent
• generation operation unique key: deduplicate local intent without inventing API idempotency
• Browse all production operations guides

Models covered on this page

• Nano Banana