本文へスキップ

Tutorial

Generate images with the Nano Banana Pro API

Submit a Nano Banana Pro image task, poll it until it finishes and download the result, with the exact request body the model's schema accepts.

Hermes AI team5 min read

This article is available in English only.

Nano Banana Pro is Google's image model; the catalog describes it as Gemini 3.0 Pro Image. On Hermes AI API it runs like every other image, video and music model: as an asynchronous task. You submit a request, poll the task until it reaches a terminal status, then download the result.

This tutorial walks through each step with curl, then puts the whole flow into one JavaScript file. Every field name and allowed value below comes from the model's input schema, the same one the Nano Banana Pro API reference shows.

Before you start

You need two things:

  • An API key. Create one in API keys and export it in your shell as HERMES_API_KEY. Keep it out of client-side code.
  • Credits. Tasks are paid from prepaid credits, and only successful tasks are charged. The current price per resolution is on the Nano Banana Pro pricing tab.
terminal
export HERMES_API_KEY=your_api_key

Pick a variant

The Nano Banana Pro page has two variants. Each one is its own model ID, which is the value you send as model.

VariantModel IDUse it to
Text to imagenano-banana-pro-text-to-image-economyGenerate an image from a prompt
Editnano-banana-pro-edit-economyChange one or more images you supply

This tutorial uses text to image first, then shows the edit request.

Build the input

The text to image variant accepts three fields. Anything else is rejected with 400 INVALID_MODEL_INPUT.

FieldTypeRequiredDefaultAllowed values
promptstringyesnoneUp to 20,000 characters
aspectRatiostringno9:161:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 5:4, 4:5, 21:9
resolutionstringyes1k1k, 2k, 4k

Two details are easy to miss. If you leave out aspectRatio, you get a portrait 9:16 image, so set it whenever you want another shape. And resolution is a lowercase string such as 2k, not a pixel size.

Here is a complete request body for a 16:9 image at 2k:

POST /api/v1/jobs
{"model": "nano-banana-pro-text-to-image-economy","input": {"prompt": "A ceramic pour-over coffee set on a walnut counter, morning window light, shallow depth of field, a handwritten label on the jar that reads \"House blend\"","aspectRatio": "16:9","resolution": "2k"}}

Submit the task

Send the body to POST /api/v1/jobs with your key and a fresh Idempotency-Key. The key is required: it lets you retry the same request after a network error without paying twice.

terminal
curl -X POST https://api.hermes-ai.net/api/v1/jobs \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "nano-banana-pro-text-to-image-economy",
    "input": {
      "prompt": "A ceramic pour-over coffee set on a walnut counter, morning window light, shallow depth of field, a handwritten label on the jar that reads \"House blend\"",
      "aspectRatio": "16:9",
      "resolution": "2k"
    }
  }'

The API validates the input, reserves the price from your credits and answers right away with 202 and the task. There is no synchronous call to wait on. The fields you need from the response:

FieldWhat it is
idThe task ID. Use it to poll.
statusqueued at first.
priceMicrosThe quote fixed at admission, in USD micro-units (1,000,000 = $1).
assetsEmpty until the task succeeds.

Poll for the result

Call GET /api/v1/jobs/{id} every few seconds. The web playground polls every 4 seconds. Stop when the status is terminal.

terminal
curl https://api.hermes-ai.net/api/v1/jobs/TASK_ID \
  -H "Authorization: Bearer $HERMES_API_KEY"
StatusTerminalMeaning
queuednoAccepted and waiting for a worker.
submittingnoBeing sent to the model provider.
runningnoThe model is generating.
succeededyesFinished. Results are in assets.
failedyesFinished without a result. The hold is released.
reconciliation_requiredyesThe result is being verified. Keep the task ID and do not resubmit automatically.

A failed task is not charged. If you see reconciliation_required, do not send the request again on your own; keep the ID and check the task later in Task logs.

Download the image

When the task succeeds, each entry in assets has an id, a type and a url. The URL is a same-origin link of the form /api/v1/results/<uuid>, and it needs the same credentials as the rest of the API (the key's media:read scope).

terminal
curl -L https://api.hermes-ai.net/api/v1/results/RESULT_ID \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -o nano-banana-pro-result

Save the file with an extension that matches the asset's type.

Edit an image

The edit variant adds imageUrls, a list of one to ten images, and keeps prompt, aspectRatio and resolution. Without aspectRatio, the output size adapts to your input.

Each image can be a public HTTPS URL or a media:<uuid> reference. To send a local file, upload it first; the response contains the reference to put in imageUrls.

terminal
curl -X POST https://api.hermes-ai.net/api/v1/media \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @input.png
POST /api/v1/jobs
{"model": "nano-banana-pro-edit-economy","input": {"imageUrls": ["https://example.com/your-photo.png"],"prompt": "Replace the background with a plain light grey studio backdrop and keep the product unchanged","resolution": "2k"}}

Replace the example URL with your own image or with the reference from the upload.

Retry safely

  • After a network error, retry with the same Idempotency-Key and the same body. If the first attempt was accepted, you get that task back with replayed: true and no second charge.
  • Use a new key for a changed request. Reusing a key with different input returns 409 IDEMPOTENCY_CONFLICT.
  • To refuse a price change, read the price from GET /api/v1/prices and send it as expectedPriceMicros. A mismatch returns 409 PRICE_CHANGED before anything is charged.

The whole flow in JavaScript

The same three steps in Node.js 18 or later, with no dependencies:

generate.mjs
const API = "https://api.hermes-ai.net/api/v1";
const headers = { Authorization: `Bearer ${process.env.HERMES_API_KEY}` };

const submit = await fetch(`${API}/jobs`, {
  method: "POST",
  headers: {
    ...headers,
    "Content-Type": "application/json",
    // Reuse the same key only when retrying this exact request.
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    model: "nano-banana-pro-text-to-image-economy",
    input: {
      prompt: "A ceramic pour-over coffee set on a walnut counter, morning window light",
      aspectRatio: "16:9",
      resolution: "2k",
    },
  }),
});
let task = await submit.json();
if (!submit.ok) throw new Error(task.code);

const terminal = ["succeeded", "failed", "reconciliation_required"];
while (!terminal.includes(task.status)) {
  await new Promise((resolve) => setTimeout(resolve, 4000));
  task = await (await fetch(`${API}/jobs/${task.id}`, { headers })).json();
}
if (task.status !== "succeeded") throw new Error(`${task.status}: ${task.errorCode}`);

for (const asset of task.assets) {
  const file = await fetch(new URL(asset.url, API), { headers });
  console.log(asset.type, (await file.arrayBuffer()).byteLength, "bytes");
}

Next steps

All prompt examples

Product shot on a seamless backdrop

Studio product photo of a matte amber glass dropper bottle on a seamless warm grey backdrop. Soft key light from the upper left, a gentle shadow to the right, a thin rim light on the glass. Shot on a 100mm macro lens at eye level, centered with generous space above. The paper label reads "Night Serum" in a clean serif and "30 ml" underneath in small caps.

画像Nano Banana Pro

nano-banana-pro-text-to-image-economy