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.
export HERMES_API_KEY=your_api_keyPick 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.
| Variant | Model ID | Use it to |
|---|---|---|
| Text to image | nano-banana-pro-text-to-image-economy | Generate an image from a prompt |
| Edit | nano-banana-pro-edit-economy | Change 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.
| Field | Type | Required | Default | Allowed values |
|---|---|---|---|---|
prompt | string | yes | none | Up to 20,000 characters |
aspectRatio | string | no | 9:16 | 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 5:4, 4:5, 21:9 |
resolution | string | yes | 1k | 1k, 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:
{"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.
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:
| Field | What it is |
|---|---|
id | The task ID. Use it to poll. |
status | queued at first. |
priceMicros | The quote fixed at admission, in USD micro-units (1,000,000 = $1). |
assets | Empty 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.
curl https://api.hermes-ai.net/api/v1/jobs/TASK_ID \
-H "Authorization: Bearer $HERMES_API_KEY"| Status | Terminal | Meaning |
|---|---|---|
queued | no | Accepted and waiting for a worker. |
submitting | no | Being sent to the model provider. |
running | no | The model is generating. |
succeeded | yes | Finished. Results are in assets. |
failed | yes | Finished without a result. The hold is released. |
reconciliation_required | yes | The 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).
curl -L https://api.hermes-ai.net/api/v1/results/RESULT_ID \
-H "Authorization: Bearer $HERMES_API_KEY" \
-o nano-banana-pro-resultSave 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.
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{"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-Keyand the same body. If the first attempt was accepted, you get that task back withreplayed: trueand 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/pricesand send it asexpectedPriceMicros. A mismatch returns409 PRICE_CHANGEDbefore anything is charged.
The whole flow in JavaScript
The same three steps in Node.js 18 or later, with no dependencies:
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
- Try the same request without writing code in the Nano Banana Pro playground.
- Copy a ready prompt from the Nano Banana Pro product shot prompt.
- Read the full tasks and results reference and the error codes.
- Let an agent run tasks for you: use Hermes AI API from Claude Code with MCP.