Nano Banana API Docs
Nano Banana API Docs
DocumentationQuickstartAuthenticationPricing

Generate image

POST /api/ai/image/generate — submit a text-to-image or image-to-image task across the Nano Banana model family.

Submits a new image generation task. Credits are pre-debited on submission and refunded automatically if the upstream provider fails the task.

Supported models

Model IDModesMax refsPrompt capCredit rule
google/nano-bananatext-to-image, image-to-image105,000 charsFlat 3 credits per call
nano-banana-2text-to-image, image-to-image1420,000 chars4 / 6 / 8 credits by 1K / 2K / 4K
nano-banana-protext-to-image, image-to-image810,000 chars12 / 20 credits by 2K / 4K
gpt-image-2text-to-image, image-to-image420,000 charsSee the returned creditsUsed value

Default Nano Banana profile

When model is google/nano-banana, this endpoint behaves as a single unified text/edit API:

  • inputImageUrls omitted: text-to-image mode.
  • inputImageUrls present: image-to-image edit mode, up to 10 reference images.
  • aspectRatio supports auto, 1:1, 16:9, 9:16, 4:3, and 3:4.
  • Current public pricing is a flat 3 credits per request.

Field notes

  • prompt is required for every model.
  • inputImageUrls is the only field that switches the endpoint from generation to editing.
  • aspectRatio is the safest cross-model layout control. Resolution, output format, and similar knobs are model-specific.
  • providerInput is an advanced passthrough for provider-specific overrides. It is not schema-validated, so only use it if you control the upstream contract.
  • The submitted task response includes creditsUsed. Use that value instead of reimplementing billing logic client-side.
POST
/api/ai/image/generate

Authorization

bearerAuth
AuthorizationBearer <token>

API keys are in closed beta — send your key as Authorization: Bearer <key>. In the meantime, first-party usage from the web dashboard is authenticated via session cookie. See Authentication for details.

In: header

Header Parameters

Idempotency-Key?string

Required for provider=ai-relay. Persist before the first request; reuse the same key and body for retries. New keys are only for new business jobs.

Length8 <= length <= 200

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://nanobanana-api.com/api/ai/image/generate" \  -H "Content-Type: application/json" \  -d '{    "prompt": "A luxury skincare bottle on warm paper, embossed serif label, soft editorial side light",    "model": "google/nano-banana",    "aspectRatio": "4:5"  }'
{
  "taskId": "tsk_01J9XA5M2R9W4QZC4PYJF3N7ND",
  "status": 0,
  "creditsUsed": 12,
  "relayStatus": "string",
  "providerTaskId": "string",
  "requestId": "string",
  "httpRequestId": "string",
  "upstreamHttpStatus": 0,
  "pollAfterSeconds": 5,
  "submissionUncertain": true,
  "effectiveWatermark": true,
  "demo": true,
  "expiresAt": "2019-08-24T14:15:22Z",
  "creditRefunded": true
}
{
  "taskId": "tsk_01J9XA5M2R9W4QZC4PYJF3N7ND",
  "status": 0,
  "creditsUsed": 12,
  "relayStatus": "string",
  "providerTaskId": "string",
  "requestId": "string",
  "httpRequestId": "string",
  "upstreamHttpStatus": 0,
  "pollAfterSeconds": 5,
  "submissionUncertain": true,
  "effectiveWatermark": true,
  "demo": true,
  "expiresAt": "2019-08-24T14:15:22Z",
  "creditRefunded": true
}
{
  "error": "Invalid request",
  "details": {}
}
{
  "error": "Unauthorized"
}
{
  "error": "Insufficient credits",
  "required": 12
}
{
  "error": "string"
}
{
  "taskId": "tsk_01J9XA5M2R9W4QZC4PYJF3N7ND",
  "status": 0,
  "creditsUsed": 12,
  "relayStatus": "string",
  "providerTaskId": "string",
  "requestId": "string",
  "httpRequestId": "string",
  "upstreamHttpStatus": 0,
  "pollAfterSeconds": 5,
  "submissionUncertain": true,
  "effectiveWatermark": true,
  "demo": true,
  "expiresAt": "2019-08-24T14:15:22Z",
  "creditRefunded": true
}
{
  "error": "string"
}

Table of Contents

Supported modelsDefault Nano Banana profileField notes
prompt*string

What to generate. Individual models enforce their own prompt length caps; see the pricing and credits guides for model-specific limits.

Length1 <= length <= 20000
model*string

Model ID. See Pricing for the current public model list and credit rules.

Value in"google/nano-banana" | "nano-banana-2" | "nano-banana-pro" | "gpt-image-2"
negativePrompt?string

Concepts to avoid (support depends on model).

Lengthlength <= 2000
width?integer
Range64 <= value <= 4096
height?integer
Range64 <= value <= 4096
aspectRatio?string

Aspect ratio token like 1:1, 16:9, or auto. Allowed values are model-specific; the default google/nano-banana profile supports auto, 1:1, 16:9, 9:16, 4:3, and 3:4.

numOutputs?integer
Default1
Range1 <= value <= 10
seed?string

Optional deterministic seed (string to accept large values).

guidanceScale?number
Range0 <= value <= 100
numInferenceSteps?integer
Range1 <= value <= 150
inputImageUrls?array<>

Reference images for image-to-image mode. gpt-image-2 supports up to 4, nano-banana-2 up to 14, nano-banana-pro up to 8, and google/nano-banana up to 10.

Itemsitems <= 14
providerInput?

Advanced passthrough for provider-specific fields that override defaults. This object is not schema-validated, so treat it as an expert-only escape hatch.

provider?string

Omit for the existing provider flow. Use the separate Relay request shape for ai-relay.

Value in"kie"
provider*unknown
model*string

Exact model ID returned by GET /api/ai/models with application pricing enabled.

Length1 <= length <= 100
prompt*string
Length1 <= length <= 8000
resolution*string

A discovered resolution for this model.

Length1 <= length <= 30
numOutputs?integer
Default1
watermark?boolean
Defaultfalse