Nano Banana API Reference

Base URL

https://www.nananobanana.com/api/v1

Authentication

Authenticated endpoints require:

Authorization: Bearer nb_your_api_key_here

The key is shown only once at creation time.

Endpoints

GET /models

• Authentication: not required.
• Purpose: resolve the current model catalog.
• Recommendation: call this before passing an explicit selectedModel.

Live verification on 2026-03-25 returned model IDs including gemini-2.5-flash-image, nanobanan-2, nanobanan-2-2k, seedream-5.0-2k, and nanobanan2&pro. This differs from the static docs example that uses nano-banana, so treat /models as authoritative.

GET /credits

• Authentication: required.
• Response shape:

{
  "data": {
    "credits": 100
  }
}

POST /generate

• Authentication: required.
• Core request fields:

{
  "prompt": "Required prompt text",
  "selectedModel": "Optional model id from /models",
  "referenceImageUrls": ["Optional image URL"],
  "aspectRatio": "Optional aspect ratio",
  "mode": "sync | stream | async"
}

Sync

• mode: sync or omitted.
• Returns when generation completes.
• Best for: one-shot agent tasks and simple server-side integrations.

Common success shape:

{
  "success": true,
  "generationId": "clxx...",
  "imageUrls": ["https://..."],
  "creditsUsed": 1,
  "remainingCredits": 99
}

Stream

• mode: stream
• Response content type: text/event-stream
• Event examples:

data: {"type":"status","message":"Starting generation...","progress":0}
data: {"type":"status","message":"Processing...","progress":50}
data: {"type":"complete","message":"Generation complete","progress":100,"data":{"success":true,"imageUrls":["https://..."]}}

Expect status, complete, and error event types.

Async

• mode: async
• Submission returns immediately with a generationId.
• Poll with GET /generate?id=<generationId>.

Submission example:

{
  "success": true,
  "async": true,
  "generationId": "clxx...",
  "message": "Generation started. Use GET /api/v1/generate?id={generationId} to poll for results.",
  "creditsUsed": 1,
  "remainingCredits": 99
}

GET /generate?id=<generationId>

• Authentication: required.
• Purpose: inspect async job state or result.

Relevant processingStatus values:

• processing
• completed
• failed

Completion example:

{
  "data": {
    "id": "clxx...",
    "prompt": "A landscape in ink wash style",
    "outputImageUrls": ["https://..."],
    "modelUsed": "nano-banana",
    "processingStatus": "completed",
    "creditsUsed": 1,
    "createdAt": "2025-01-01T00:00:00.000Z"
  }
}

Request Mode Selection

• Use sync for the simplest agent execution path.
• Use stream when progress updates need to be surfaced live.
• Use async for long-running or queued work, especially when a turn should not block on submission.

Errors

• 400 Bad Request: invalid parameters such as missing prompt or invalid mode.
• 401 Unauthorized: missing or invalid API key.
• 402 Payment Required: insufficient credits.
• 403 Forbidden: API access not enabled on the account.
• 500 Internal Server Error: server-side failure.
• 503 Service Unavailable: server busy. Docs note this is specific to async queue saturation.

Operational Notes

• Generated image URLs expire after 15 days.
• Image-to-image inputs increase credit consumption.
• API access may require account enablement in addition to having a valid key.
• The published docs repo is useful for examples, but live endpoint behavior may change first. Verify unstable values through the API.
• Some CDN-protected image URLs may reject the default Python urllib user agent with 403. The bundled CLI sends an explicit browser-like User-Agent for API requests and image downloads to avoid that failure mode.