nanobanana API

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

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
• Execution mode: asynchronous task
• Typical scenarios: text-to-image, image editing

Current scope:

• Covers task submission and task query for nanobanana
• Does not expose a synchronous image response mode
• input.resolution is not supported
• input.enable_web_search is not supported

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:

3. Create Task

Request body example:

{
  "model": "nanobanana",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "A modern editorial illustration",
    "image_urls": [],
    "aspect_ratio": "16:9",
    "output_format": "png"
  }
}

3.1 Top-Level Parameters

3.2 input Parameters

Unsupported fields:

• input.resolution
• input.enable_web_search

Notes:

• output_format is best-effort. If conversion is unavailable, the task may still succeed with the model's original output format
• This model works best with fewer reference images

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",
    "input": {
      "prompt": "A playful landing page illustration for a fintech startup",
      "aspect_ratio": "16:9",
      "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",
    "input": {
      "prompt": "Transform this food photo into a stylized poster",
      "image_urls": [
        "https://cdn.example.com/reference-1.png"
      ],
      "aspect_ratio": "4:3",
      "output_format": "jpeg"
    }
  }'

5. Create Task Response

Example response:

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

Response fields:

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:

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": []
}

7. Callback Delivery

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 5 images
• image_urls must be server-accessible https URLs
• Each input image must be no larger than 10MB
• aspect_ratio and output_format must use the documented enum values
• For image editing quality, keep the number of reference images as low as practical