Gemini image API relay guide

A Gemini image API relay is an API gateway between your application and a Gemini image model. To use one, you need an image-capable model ID, the relay's request format, and a way to retrieve the actual image. Changing a text client's base URL is not enough to establish image-generation support.

On OmniaKey, the documented image workflow is create a task → poll its status → download the asset, using POST /v1/media/tasks. This guide walks through that contract and shows what to check when another service exposes Google's native API or an OpenAI-compatible interface.

What kind of relay do you need?

Here, “relay” means an application API service that handles model requests, authentication and responses. A network proxy forwards traffic but does not, by itself, convert one image API into another. Choose the integration by its documented contract.

Google's current image-generation guide uses Interactions API examples. The GenerateContent reference describes a separate contract. Do not mix their request fields or response parsers, or assume a relay exposes both.

Image understanding is another distinction: a model that accepts a picture and describes it may still return only text. A successful text call proves neither image generation nor image editing. Likewise, an “OpenAI-compatible” label does not prove that a particular image route supports every OpenAI SDK method.

Select an image model, not a family name

Google's model-selection guidance distinguishes these IDs:

• Nano Banana 2.1: gemini-nano-banana-2.1, the starting point Google recommends for new general image workflows.
• Nano Banana Pro: gemini-3-pro-image, a separate option for more demanding visual tasks.
• Nano Banana 2: gemini-3.1-flash-image, the earlier generation; not an alias for 2.1.

Copy the ID from the service you will call. Check model access, generation versus editing, supported size, and billing unit. For the 2.1 task route, OmniaKey documents parameters.aspect_ratio and parameters.image_size, with 1K, 2K and 4K output tiers. These names are not interchangeable with Google's native imageConfig or GPT Image's size and quality fields.

Use the Nano Banana 2.1 model page for the current gateway listing. Our 2.1 vs Pro comparison covers model selection in more depth.

Generate an image through OmniaKey

The following commands require Bash, cURL, jq and an OmniaKey API key stored in your local OMNIAKEY_API_KEY environment variable. Run them on your backend or development machine; keep the key out of browser code. The example prompt is deliberately simple so you can check the API workflow before evaluating image quality.

1. Create and save the task

Choose a unique Idempotency-Key for this logical image request. The example uses a readable demo value: replace it once for a new job, then keep that value and the body unchanged when retrying that job. Save both in your application before sending the request.

curl --fail-with-body --silent --show-error \
  https://api.omniakey.com/v1/media/tasks \
  -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: gemini-image-demo-20261014-001" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "type": "image",
    "operation": "generate",
    "input": {"prompt": "A blue ceramic cup on a white studio table, no text"},
    "parameters": {"aspect_ratio": "1:1", "image_size": "1K"}
  }' -o task.json

Continue only if cURL succeeds and task.json contains an id. A new task returns 202 Accepted; replaying the same key and body returns the original task with 200. Acceptance means the job exists, not that the image is finished. See the documented task lifecycle.

2. Poll the saved ID

This Bash example stops after a bounded number of checks. If it reaches the limit, it leaves the saved ID available for later polling; it does not cancel or create another job.

TASK_ID="$(jq -er '.id' task.json)" || exit 1
for attempt in {1..60}; do
  curl --fail-with-body --silent --show-error \
    "https://api.omniakey.com/v1/media/tasks/$TASK_ID" \
    -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
    -o result.json || exit 1
  STATUS="$(jq -er '.status' result.json)" || exit 1
  case "$STATUS" in
    succeeded) break ;;
    failed|canceled) jq '.error' result.json; exit 1 ;;
    queued|processing) sleep 3 ;;
    *) exit 1 ;;
  esac
done

If creation times out before you receive an ID, recover by repeating the same body and idempotency key. Once you have an ID, query that task. A new key can create a second billable job. Recovery is subject to retention: the documentation specifies task records retained for 24 hours after creation.

3. Download only a successful result

jq -e '.status == "succeeded"' result.json >/dev/null || exit 1
ASSET_URL="$(jq -er '.assets[0].url' result.json)" || exit 1
curl --fail --location --silent --show-error \
  "$ASSET_URL" -o generated-image

Read the asset's mime_type to choose the correct file extension, then verify the file opens and has the expected dimensions. Signed URLs expire: poll again for a fresh URL while the task and asset remain available. Download results you need to keep; a signed link is not permanent storage.

Edit with a reference image

Use operation: "edit" and supply inline Base64 in input.image, or use input.images for multiple references where supported. Keep input.prompt as the editing instruction. The image API documentation shows the full request shape.

The task API limits the whole request body to 1 MiB, including Base64. Compress or resize a reference if necessary. Google's direct API upload limits do not override a relay's body limit. Start with one small reference and a clear change, then check that the parts meant to stay unchanged remain usable.

A changed prompt, reference, model or parameter is a different request: use a new idempotency key. Reusing the old key with a changed body yields 409 idempotency_key_reused.

Troubleshoot the failing layer

Google's troubleshooting guide explains its own error and retry behavior. A relay adds another layer, so preserve the HTTP status, error code, task ID and timing in redacted logs. Do not log API keys or private reference images. A 200 JSON response alone is not proof of a usable image.

Compare cost and validate the integration

Google's direct billing and a relay's price are separate offers. Check the current OmniaKey pricing and the relevant model's unit before estimating a batch. Do not apply a text-token price to image output or assume a consumer Gemini subscription pays for relay calls.

A useful comparison is total charged spend ÷ number of accepted images. Include charged retries and outputs rejected during review. This is a planning formula, not a measured benchmark or a promise that one provider is cheaper.

Before increasing volume, run five small acceptance cases:

1. A text prompt returns an image that opens, with the expected format and dimensions.
2. One reference-image edit makes the requested change and preserves required details.
3. Replaying an identical request with the same key returns the same task ID.
4. A local polling timeout can resume by ID without creating a new task.
5. An invalid parameter or unavailable model produces an actionable error, not a false success.

Record model ID, parameters, elapsed time, final task state, charge and review outcome. Check the relay's data-handling terms for prompts and reference images before sending production material.

Common questions

Can I just change the base URL in my existing SDK?

Only when the relay documents the exact endpoint, request fields and image response that your SDK expects. Test the image operation itself. A working chat request is insufficient evidence.

Does a relay remove Gemini's limits?

No. Provider limits, model capabilities, relay limits and account permissions can all apply. A gateway does not establish unlimited image output or regional availability.

Which model should I start with?

Check the current catalog, then evaluate a supported image model on a small task. The Nano Banana 2.1 guide explains the model changes; this article focuses on connecting and validating the API.

Sources and next step

The primary references are Google's image guide, GenerateContent API reference, and troubleshooting guide, plus OmniaKey's linked task and image documentation. The Google reference links are in English. Contracts were checked on October 14, 2026; confirm current model access before running the example.