nanobanana-2 API

This platform provides an asynchronous image-generation endpoint for the public model ID nanobanana-2.

This document is intended for client-side integrators and focuses on the public request path, authentication method, request parameters, and task result contract.

Overview:

Create task: POST /v1/images/create
Query task: GET /v1/tasks/{task_id}
Model ID: nanobanana-2
Execution mode: asynchronous task
Typical scenarios: text-to-image, image editing, search-enhanced generation

1. API Overview

HTTP method: POST
Request path: /v1/images/create
Content-Type: application/json
Result delivery:
- Immediate response returns task acceptance information
- Final result is obtained by polling /v1/tasks/{task_id} or by callback_url

2. Authentication and Headers

Example headers:

Authorization: Bearer YOUR_REACH_API_KEY
Content-Type: application/json

Header details:

Header	Required	Description
`Authorization`	Yes	Platform API key in the format `Bearer sk-xxxxxx`
`Content-Type`	Yes	Must be `application/json`

3. Create Task

Request body example:

{
  "model": "nanobanana-2",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "A cinematic street scene at dusk, realistic lighting",
    "image_urls": [],
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "output_format": "png",
    "enable_web_search": false
  }
}

3.1 Top-Level Parameters

Field	Type	Required	Description
`model`	string	Yes	Must be `nanobanana-2`
`callback_url`	string	No	HTTPS callback URL for terminal task states. Maximum length `2048`. Localhost, local network, and private network targets are rejected
`input`	object	Yes	Image generation parameters

3.2 `input` Parameters

Field	Type	Required	Description
`prompt`	string	Yes	Generation prompt. Keep it within `2000 tokens` where possible
`image_urls`	`array<string>`	No	Reference image URLs. Empty or omitted means text-to-image. Non-empty means image editing. Maximum 14 images
`aspect_ratio`	string	No	Output aspect ratio. Supported values: `1:1`, `3:2`, `2:3`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`, `1:4`, `4:1`, `1:8`, `8:1`
`resolution`	string	No	Output resolution. Supported values: `0.5k`, `1k`, `2k`, `4k`
`output_format`	string	No	Preferred output format. Supported values: `png`, `jpeg`
`enable_web_search`	boolean	No	Enables search-enhanced generation. Default is `false`

Notes:

output_format is best-effort. If conversion is unavailable, the task may still succeed with the model's original output format
The platform always uses the asynchronous task flow
The primary task result contract is data[].url

4. Request Examples

4.1 Text-to-Image Request

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nanobanana-2",
    "input": {
      "prompt": "A futuristic city at sunset, cinematic lighting, highly detailed",
      "aspect_ratio": "16:9",
      "resolution": "2k",
      "output_format": "png"
    }
  }'

4.2 Image Editing Request

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nanobanana-2",
    "input": {
      "prompt": "Turn this sneaker photo into a premium e-commerce hero shot",
      "image_urls": [
        "https://cdn.example.com/reference-1.png"
      ],
      "aspect_ratio": "1:1",
      "resolution": "2k",
      "output_format": "jpeg"
    }
  }'

4.3 Search-Enhanced Request

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nanobanana-2",
    "input": {
      "prompt": "Create a news-style illustration about global shipping trends",
      "resolution": "1k",
      "enable_web_search": true
    }
  }'

5. Create Task Response

Example response:

{
  "code": 200,
  "msg": "",
  "status": "queued",
  "task_id": "task_xxx",
  "data": []
}

Response fields:

Field	Type	Description
`code`	integer	Platform business status code
`msg`	string	Error or status message
`status`	string	Initial task state, typically `queued`
`task_id`	string	Unique task identifier used for later query
`data`	array	Empty at submission time

6. Query Task Status

Request example:

curl -X GET "https://direct.reachapi.ai/v1/tasks/task_xxx" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY"

Task states:

Status	Description
`queued`	Accepted and waiting to run
`generating`	Generation is in progress
`success`	Task completed successfully
`failed`	Task failed

Successful response example:

{
  "code": 200,
  "msg": "",
  "status": "success",
  "task_id": "task_xxx",
  "data": [
    {
      "url": "https://cdn.example.com/generated/image-1.png"
    }
  ]
}

Failed response example:

{
  "code": 500,
  "msg": "Model service request failed",
  "status": "failed",
  "task_id": "task_xxx",
  "data": []
}

If callback_url is provided when the task is created, the gateway sends a POST request to that URL when the task reaches a terminal state. The callback body uses the same JSON structure as the task query response.

Callback constraints:

Only https URLs are supported
Maximum length: 2048
localhost, .local, and obvious private-network targets are rejected
Single delivery timeout: 10s
Up to 2 retries after failure, for a maximum of 3 delivery attempts

8. Constraints and Notes

prompt must not be empty
image_urls supports at most 14 images
image_urls must be server-accessible https URLs
Each input image must be no larger than 10MB
aspect_ratio, resolution, and output_format must use the documented enum values
enable_web_search should be enabled only when real-time external context is needed