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 ID	Modes	Max refs	Prompt cap	Credit rule
`google/nano-banana`	text-to-image, image-to-image	`10`	`5,000` chars	Flat `3` credits per call
`nano-banana-2`	text-to-image, image-to-image	`14`	`20,000` chars	`4 / 6 / 8` credits by `1K / 2K / 4K`
`nano-banana-pro`	text-to-image, image-to-image	`8`	`10,000` chars	`12 / 20` credits by `2K / 4K`
`gpt-image-2`	text-to-image, image-to-image	`4`	`20,000` chars	See 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.

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.

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

Response Body

`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"
}

Supported models

Default Nano Banana profile

Field notes

Authorization

Header Parameters

Request Body

Response Body

200application/json

202application/json

400application/json

401application/json

402application/json

409application/json

429application/json

500application/json

Table of Contents

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`