Nano Banana 2 API

Googleimage$0.142 / run

Submit a Nano Banana 2 run over HTTP, then poll it or take a webhook. Results are files on media.ezflows.io. Try it in the playground first.

Async: the POST answers at once with a request id. Poll it, or take the webhook.

  1. 01

    Submit

    Parameters at the top level of the JSON body. Answers 202 with a request id.

    curlPOST /v1/models/nano-banana-2
    curl -X POST https://api.ezflows.io/v1/models/nano-banana-2 \
      -H "Authorization: Bearer $EZFLOWS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "prompt": "A professional photograph of a beautifully crafted hand-painted gold leaf sign on a glass window pane. The central focus is the text '\''MEXITALY'\'' rendered in an elegant, red and gold script font. Below it, in larger, bold, gold beveled letters with a deep red shadow and gold outline, are the words '\''TORNABUONI'\''. Underneath, in smaller, teal and cream script lettering, is '\''Strada64'\'', followed by '\''BarandRestaurant'\'' on the final line in the same teal and cream script style. The entire text composition is framed by intricate gold and teal decorative flourishes and stylized star motifs. The reflection of a warm, bustling European street, specifically Via de'\'' Tornabuoni in Florence with its historic architecture and pedestrian crowds at twilight, is visible through the glass pane, adding depth to the image. The glass itself has a slight texture. The perspective is a straight-on medium shot, capturing the details of the lettering and the atmospheric reflection.",
        "system_prompt": ""
      }'
    
    # 202 Accepted, at once — it never waits for the model:
    # {"request_id": "req_8f2a41c9b70e4d15", "status": "queued",
    #  "poll_url": "https://api.ezflows.io/v1/requests/req_8f2a41c9b70e4d15"}
  2. 02

    Poll

    Same bearer header, every few seconds, until the status is final.

    curlGET /v1/requests/:id
    REQUEST_ID=req_8f2a41c9b70e4d15   # from the POST
    
    while :; do
      BODY=$(curl -s https://api.ezflows.io/v1/requests/$REQUEST_ID \
        -H "Authorization: Bearer $EZFLOWS_API_KEY")
      STATUS=$(echo "$BODY" | jq -r .data.status)
      case "$STATUS" in succeeded|failed|cancelled) break ;; esac
      sleep 3
    done
    
    echo "$BODY" | jq -r '.data.output.artifacts[].url'   # media.ezflows.io, kept 90 days
  3. 03

    Response

    Files are on media.ezflows.io, kept 90 days. A failed run says why and costs nothing.

    json200 · succeeded
    {
      "data": {
        "id": "req_8f2a41c9b70e4d15",
        "model_slug": "nano-banana-2",
        "status": "succeeded",
        "http_status": 200,
        "cost": 0.141539,
        "auth_method": "api_key",
        "error": null,
        "submitted_at": "2026-09-12T18:07:21.114Z",
        "queue_started_at": "2026-09-12T18:07:21.402Z",
        "execution_started_at": "2026-09-12T18:07:22.010Z",
        "first_byte_at": "2026-09-12T18:07:52.871Z",
        "finished_at": "2026-09-12T18:07:55.203Z",
        "io_deleted_at": null,
        "canvas_id": null,
        "canvas_node_id": null,
        "client_attempt_id": null,
        "idempotency_key": null,
        "input": {
          "prompt": "A professional photograph of a beautifully crafted hand-painted gold leaf sign on a glass window pane. The central focus is the text 'MEXITALY' rendered in an elegant, red and gold script font. Below it, in larger, bold, gold beveled letters with a deep red shadow and gold outline, are the words 'TORNABUONI'. Underneath, in smaller, teal and cream script lettering, is 'Strada64', followed by 'BarandRestaurant' on the final line in the same teal and cream script style. The entire text composition is framed by intricate gold and teal decorative flourishes and stylized star motifs. The reflection of a warm, bustling European street, specifically Via de' Tornabuoni in Florence with its historic architecture and pedestrian crowds at twilight, is visible through the glass pane, adding depth to the image. The glass itself has a slight texture. The perspective is a straight-on medium shot, capturing the details of the lettering and the atmospheric reflection.",
          "system_prompt": ""
        },
        "output": {
          "artifacts": [
            {
              "index": 0,
              "kind": "image",
              "contentType": "image/png",
              "url": "https://media.ezflows.io/outputs/<account>/req_8f2a41c9b70e4d15/0.png"
            }
          ]
        }
      }
    }
  4. 04

    Webhook

    Skip polling: we POST the result to your endpoint, at least once.

    Register
    Create an endpoint under Webhooks in the dashboard; the signing secret is shown once.
    Events
    request.succeeded · request.failed · request.cancelled
    Headers
    ezflows-event-id (dedupe on it) · ezflows-timestamp (unix seconds) · ezflows-signature t=<ts>,v1=<hex HMAC-SHA256 of "<ts>.<raw body>">
    Verify
    Over the exact bytes received, in constant time; reject anything older than five minutes.
    Respond
    Any 2xx within 10 s. Redirects are not followed.
    Retries
    Five, with backoff: 30 s · 60 s · 2 min · 4 min · 8 min. Disabled after five consecutive dead deliveries.
    jsonDelivery body
    {
      "id": "82cf46a4-841e-41d6-b3c7-facc937d3252",
      "type": "request.succeeded",
      "created_at": "2026-09-12T18:07:55Z",
      "data": {
        "id": "req_8f2a41c9b70e4d15",
        "model_slug": "nano-banana-2",
        "status": "succeeded",
        "cost": 0.141539,
        "output": {
          "artifacts": [
            {
              "url": "https://media.ezflows.io/…/0.png"
            }
          ]
        }
      }
    }
    curlverify.sh
    # Create the endpoint under Webhooks in the dashboard; the signing secret is shown once.
    # ezflows-signature: t=<ts>,v1=<hex HMAC-SHA256 of "<ts>.<raw body>">
    # body.json = the exact bytes received. Reject anything older than five minutes.
    EXPECTED=$({ printf '%s.' "$TS"; cat body.json; } \
      | openssl dgst -sha256 -hmac "$EZFLOWS_WEBHOOK_SECRET" -r | cut -d' ' -f1)
    
    [ "$EXPECTED" = "$V1" ] && echo "valid" || echo "reject"

Parameters 11

NameTypeDefaultAllowedDescription
promptrequiredstringA professional photograph of a beautifully crafted hand-painted gold leaf sign on a glass window pane. The central focus is the text 'MEXITALY' rendered in an elegant, red and gold script font. Below it, in larger, bold, gold beveled letters with a deep red shadow and gold outline, are the words 'TORNABUONI'. Underneath, in smaller, teal and cream script lettering, is 'Strada64', followed by 'BarandRestaurant' on the final line in the same teal and cream script style. The entire text composition is framed by intricate gold and teal decorative flourishes and stylized star motifs. The reflection of a warm, bustling European street, specifically Via de' Tornabuoni in Florence with its historic architecture and pedestrian crowds at twilight, is visible through the glass pane, adding depth to the image. The glass itself has a slight texture. The perspective is a straight-on medium shot, capturing the details of the lettering and the atmospheric reflection.—Describe the image to generate or the changes to make to the reference images.
image_urlsstring[][]up to 14 image urlsOptional reference images for style guidance. Nano Banana 2 accepts up to 14 images.
system_promptstring——Optional high-level persona or style instructions applied to the generation.
aspect_ratioenum1:1auto · 1:1 · 2:3 · 3:2 · 4:3 · 3:4 · 4:5 · 5:4 · 16:9 · 9:16 · 21:9 · 4:1 · 1:4 · 8:1 · 1:8Choose the proportions of the generated image. "Auto" lets the model pick.
output_resolutionenum1K512px · 1K · 2K · 4KOutput detail level. Also determines the price tier.
output_formatenumjpgjpg · pngFile format of the generated image.
web_searchbooleanfalse—Ground generation in real-time web data. Recommended for news-related prompts. Also affects price.
response_modalitiesenumTEXT_AND_IMAGETEXT_AND_IMAGE · IMAGEReturn only the generated image or include a text response alongside it.
seedinteger4208750–999999999999999Seed for reproducible results.
thinking_levelenumminimalminimal · highReasoning depth. High for complex prompts, minimal for fast output.
safety_toleranceenum41 · 2 · 3 · 4 · 5 · 6Content moderation level, 1 (strictest) to 6 (least strict).

File inputs (image_urls: up to 14 image urls) take URLs. Upload the raw file to POST /v1/uploads with its own Content-Type and pass the url it returns. Inputs are kept 90 days.