Turn a Gemini Image API Response Into a Valid Download
Your backend receives a successful Gemini response. The interface says “image generated.” The download is an unreadable file, or the saved picture is the input reference rather than the new output. Another request returns a helpful sentence and no image, yet your application still creates an empty asset record.
These failures happen after generation. The repair is a precise response contract: identify the output image, decode its bytes, verify its media type, and create an asset only when those conditions hold. This walkthrough follows one illustrative product image from a completed API response to a stored file. It makes no claim about image quality or gateway performance.
The main implementation uses the current Gemini Interactions response shape. A short compatibility note covers GenerateContent at the end. Mixing those envelopes is a parser defect, even when both requests target a Gemini model.
Give the image job an explicit contract
Suppose an internal catalog tool requests one decorative background. Its application contract is one usable raster image, optional accompanying text, and enough provenance to connect the asset with the generation request. The sentence describing the background is useful context; it is not the background file.
An image-capable model is necessary. The official Gemini 3.1 Flash Image model page lists image and text output. This establishes an upstream capability, not availability through every account or gateway. Keep the selected model identifier in configuration and verify its current status before a pilot.
Decide whether your product accepts several images. This example deliberately accepts exactly one. If two images arrive, it refuses to silently choose the last one. That is an application policy, not a statement that Gemini always generates one image. The image generation guide warns that requested image counts are not always followed exactly.
A route that handles ordinary Gemini text is not sufficient evidence for this job. Confirm that the route supports the selected image model, the intended API family, image output, and the complete response fields your decoder needs. The Gemini endpoint guide provides context for making that distinction.
Find the output in the current response envelope
Google’s getting-started guide shows generated image bytes as Base64 data inside an image content block in a model_output step. The SDK also exposes output_image as a convenience. Use the full envelope when your application must preserve ordering and explain unexpected results.
Do not recursively search every object for a data property. A retrieved interaction can contain user input, and a broader workflow can include other step types. An input reference image is not a newly generated deliverable. Select model_output steps, then inspect their typed content blocks.
The current schema also differs from older Interactions examples using an outputs array. Google’s Interactions schema migration guide documents the change to steps. Treat old snippets as version-specific material, not alternative field names to guess at until something works.
The Interactions API reference documents status values and typed image content. For this synchronous example, only a completed interaction enters asset validation. Other statuses require their own handling; an incomplete result does not become acceptable merely because an image-looking block exists somewhere in the response.
Keep MIME type, encoding, and filename separate
An image block’s data is encoded content. Its mime_type describes the media. The extension is an application decision derived from the validated media type. These are three separate pieces of information.
Writing Base64 characters directly into a file named background.png does not create a PNG. Decoding JPEG bytes and assigning a .png extension does not convert them. A stored asset should retain the actual validated content type, and a later download should use matching metadata.
Use strict decoding so malformed input does not quietly become different bytes. Python’s Base64 documentation describes b64decode(..., validate=True). A successful decode still proves only that the encoding is acceptable; it does not prove the bytes form a complete image.
Open the decoded bytes with an image decoder, check the detected format against the declared MIME type, validate the file, and enforce application size limits. Pillow’s Image reference documents opening, verification, and loading. The sample permits PNG and JPEG only, keeping unsupported media explicit rather than inventing an extension.
Before decoding, retain a compact trace for the illustrative background job. The interaction identifier identifies the response; the step and block indexes identify where the output was found. Neither should be replaced by the display filename. A filename such as background-final.png tells an operator little about which response produced its bytes.
This separation also prevents an easy mistake in editing applications. Both the uploaded reference and the generated result may be valid PNG images of similar dimensions. Their file signatures cannot tell you which is the deliverable. Only the response structure establishes that role. Decode validation and output selection therefore solve different problems, and both must pass.
If an adapter flattens the response into a single text field, the image-saving function cannot reconstruct the missing bytes. If it renames fields, record and test that mapping explicitly. The useful integration question is whether the selected route preserves the evidence the application needs to identify a generated asset.
Walk one response into a file, offline
This Python example requires Pillow. It creates a synthetic one-pixel fixture in memory and uses a temporary directory. It sends no API request and needs no credentials, endpoint, or model identifier. The fixture is a parser test, not a generated-image example or a model benchmark.
The byte and pixel limits below are illustrative application policies, not Gemini limits. The decoder validates the entire selected output before storage, rejects multiple images, and returns a separate no_image result for completed text-only responses.
import base64
import binascii
import hashlib
import io
import tempfile
import uuid
from pathlib import Path
from PIL import Image
MAX_BYTES = 10 * 1024 * 1024
MAX_PIXELS = 20_000_000
FORMATS = {"image/png": ("PNG", ".png"), "image/jpeg": ("JPEG", ".jpg")}
def decode_image(block):
mime = block.get("mime_type")
if mime not in FORMATS:
raise ValueError("unsupported image MIME type")
encoded = block.get("data")
if not isinstance(encoded, str) or not encoded:
raise ValueError("inline Base64 image data required")
if len(encoded) > 4 * ((MAX_BYTES + 2) // 3):
raise ValueError("encoded image exceeds application limit")
try:
raw = base64.b64decode(encoded, validate=True)
except (ValueError, binascii.Error) as exc:
raise ValueError("invalid Base64") from exc
if not raw or len(raw) > MAX_BYTES:
raise ValueError("decoded image exceeds application limit")
expected, extension = FORMATS[mime]
with Image.open(io.BytesIO(raw)) as img:
width, height = img.size
if img.format != expected or width * height > MAX_PIXELS:
raise ValueError("format mismatch or excessive dimensions")
if getattr(img, "n_frames", 1) != 1:
raise ValueError("single-frame image required")
img.verify()
with Image.open(io.BytesIO(raw)) as img:
img.load()
return {"bytes": raw, "mime_type": mime, "extension": extension,
"width": width, "height": height,
"sha256": hashlib.sha256(raw).hexdigest()}
def read_interaction(payload):
if not isinstance(payload, dict) or payload.get("object") != "interaction":
raise ValueError("Interactions envelope required")
if payload.get("status") != "completed":
raise ValueError("interaction is not completed")
steps = payload.get("steps")
if not isinstance(steps, list):
raise ValueError("steps array required")
images, texts = [], []
for step_index, step in enumerate(steps):
if not isinstance(step, dict) or not isinstance(step.get("type"), str):
raise ValueError("typed step required")
if step["type"] != "model_output":
continue
content = step.get("content")
if not isinstance(content, list):
raise ValueError("model_output content array required")
for block_index, block in enumerate(content):
if not isinstance(block, dict):
raise ValueError("content object required")
kind = block.get("type")
if kind == "text" and isinstance(block.get("text"), str):
texts.append(block["text"])
elif kind == "image":
asset = decode_image(block)
asset["source_position"] = [step_index, block_index]
images.append(asset)
else:
raise ValueError("unsupported model output block")
if len(images) > 1:
raise ValueError("application requires exactly one output image")
return {"state": "ready" if images else "no_image", "text": texts,
"interaction_id": payload.get("id"), "images": images}
def store_one(result, destination):
if result["state"] != "ready":
return None
asset = result["images"][0]
destination = Path(destination) # trusted application directory
destination.mkdir(parents=True, exist_ok=True)
path = destination / (uuid.uuid4().hex + asset["extension"])
with path.open("xb") as output:
output.write(asset["bytes"])
return path
buffer = io.BytesIO()
Image.new("RGB", (1, 1), "white").save(buffer, format="PNG")
image_block = {"type": "image", "mime_type": "image/png",
"data": base64.b64encode(buffer.getvalue()).decode("ascii")}
fixture = {"object": "interaction", "id": "synthetic_fixture",
"status": "completed", "steps": [
{"type": "user_input", "content": [image_block]},
{"type": "model_output", "content": [
{"type": "text", "text": "Synthetic output."}, image_block]},
]}
result = read_interaction(fixture)
assert result["images"][0]["source_position"] == [1, 1]
with tempfile.TemporaryDirectory() as folder:
path = store_one(result, folder)
assert path.suffix == ".png" and path.read_bytes() == buffer.getvalue()
fixture["steps"] = [{"type": "model_output", "content": [
{"type": "text", "text": "No image in this synthetic response."}]}]
assert read_interaction(fixture)["state"] == "no_image"
assert store_one(read_interaction(fixture), "unused-output") is None
try:
decode_image({**image_block, "mime_type": "image/jpeg"})
except ValueError:
pass
else:
raise AssertionError("MIME mismatch must fail")
print("offline image response fixtures passed")Notice the source position in the assertion. The fixture intentionally includes an input image before the output image. A recursive extractor could save the wrong picture while passing a superficial “file exists” test. This parser records which output block supplied the bytes.
The code implements a narrow contract. It does not support streaming fragments, remote image URIs, animation, arbitrary media types, or cloud-object uploads. A valid upstream response outside that contract should trigger an explicit integration decision. Do not add fallback guesses merely to make the test green.
For a live implementation, obtain the current request shape and SDK method from the official image guide and use configuration variables for the confirmed model and credentials. No live request was executed for this article. Keep the response contract test separate from the first paid generation call.
A completed text response creates no image asset
A response can contain explanatory text without satisfying the image job. Preserve that text for the appropriate application or support view, but do not publish a download button or create a successful asset record. The example’s no_image state describes the missing deliverable without inventing its cause.
Do not equate no_image with a safety refusal, a network error, or a broken decoder. Those are different findings. Inspect the actual response metadata and request configuration before choosing a next action. The separate Gemini safety-response guide covers that diagnostic branch; this article stays focused on whether a valid image exists.
Similarly, a format mismatch is not a request to relabel the file. Retain enough diagnostic context to determine whether the upstream response, an adapter, or application serialization changed the bytes or MIME field. Fixing that boundary is preferable to repeatedly generating new images to satisfy a faulty parser.
Before wiring this state into the interface, add fixtures for the failures your product must distinguish. Include a valid image with surrounding text, an input image without any generated image, two generated images, malformed Base64, and declared PNG with JPEG bytes. Also include a non-completed interaction containing an image block, so the completion gate cannot be bypassed by a promising-looking payload.
The expected results should be written before running the parser. The input-only fixture creates no asset. The two-image fixture requires a product decision. Corrupt bytes fail validation. A completed response with only text remains available as text while the image task stays unsatisfied. These outcomes are more informative than checking only whether the function raised an exception.
For the first controlled live call, compare the received envelope with this fixture contract before enabling automatic storage. Keep a suitably redacted sample for regression testing if your data policy allows it. The offline tests verify application behavior; they do not prove the gateway exposes the same response shape or that the chosen model can generate an acceptable catalog background.
Store the validated asset with its identity intact
The local example creates a fresh filename independently of the model’s prose. In a real asset store, associate the stored object with the interaction identifier, selected model configuration, validated MIME type, dimensions, byte length, and content hash. Keep the generated text as a separate field.
The hash identifies the stored bytes; it does not establish authorship, visual correctness, or equivalence between resized images. If your application makes thumbnails or transcodes files, create derivative records linked to the original rather than quietly replacing the original asset’s content type.
The demo’s local write is intentionally small. Production storage needs a documented commit rule so a partial write cannot appear as a completed asset. Apply your object store’s upload and visibility semantics, then mark the application record ready only after the stored object is available. The Gemini production integration guide provides broader application context.
If the generated asset accompanies extracted document data, keep those origins separate too. The Gemini PDF table-extraction guide addresses source-grounded values; an illustrative image generated from them is a different artifact and should not replace the source record.
Keep the GenerateContent branch explicit
Existing integrations may use GenerateContent. Its API reference defines candidates[].content.parts, with REST image bytes under inlineData.data and MIME under inlineData.mimeType. That is not the Interactions steps envelope used above.
Build a separate adapter for that contract if you need it. Select the candidate intentionally, handle typed parts, and distinguish final content from thought-marked parts before calling the same byte validator. SDK object fields can differ from REST JSON; do not run a JSON parser against an SDK object by assumption.
This distinction also matters when moving between image providers. The image API migration guide explains why a model-name change alone cannot validate an existing output handler. Share asset validation across adapters when appropriate, while keeping each provider’s response extraction explicit.
For a Treerouter pilot, bring the exact required contract: one completed image result, preserved output blocks, decodable bytes, and matching MIME metadata. Confirm account and route support for the chosen Gemini image model and API family before sending the first request. Then verify one stored image end to end, including the text-only case, before connecting the route to your application’s success screen.
Learn more: Treerouter.






