SDK quickstart

This guide uses Google’s official Python SDK. The only BananaHub-specific step is overriding base_url. See Gemini-compatible API for the concept.

You’ll need an active API key with permission for the model you call. See Authentication.

1. Install and configure

pip install google-genai

Point the client at BananaHub and pass your API key:

from google import genai
from google.genai import types

client = genai.Client(
    api_key="YOUR_BANANAHUB_KEY",
    http_options=types.HttpOptions(base_url="https://bananahub.io/api/gemini"),
)

Any Gemini client works the same way — set the base URL to https://bananahub.io/api/gemini and send your key as x-goog-api-key.

2. Text-to-image

Request the IMAGE modality and read the base64 image from the first candidate.

resp = client.models.generate_content(
    model="gemini-2.5-flash-image",
    contents="a red panda astronaut floating in a nebula",
    config=types.GenerateContentConfig(
        response_modalities=["IMAGE"],
        image_config=types.ImageConfig(aspect_ratio="16:9"),
    ),
)

image = resp.candidates[0].content.parts[0].inline_data.data  # raw PNG bytes
open("out.png", "wb").write(image)

curl -s -X POST \
  "https://bananahub.io/api/gemini/v1beta/models/gemini-2.5-flash-image:generateContent" \
  -H "x-goog-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "a red panda astronaut floating in a nebula"}]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9"}
    }
  }'

The response is standard Gemini JSON. The image is base64 in candidates[0].content.parts[0].inlineData.data.

Resolution

For NanoBanana 2 and Pro, select the output size with imageSize — 1K, 2K, 4K, plus 512px on NanoBanana 2:

config=types.GenerateContentConfig(
    response_modalities=["IMAGE"],
    image_config=types.ImageConfig(aspect_ratio="1:1", image_size="2K"),
)

imageSize is validated by the model — supported values are 1K, 2K, 4K (plus 512px on NanoBanana 2); anything else returns 400 INVALID_ARGUMENT. NanoBanana (gemini-2.5-flash-image) outputs 1K. Sizes below 1K (e.g. 512px) are billed at the 1K rate.

3. Image-to-image (edit)

Pass one or more input images plus an instruction in contents.

from pathlib import Path

resp = client.models.generate_content(
    model="gemini-3-pro-image",
    contents=[
        types.Part.from_bytes(data=Path("input.png").read_bytes(), mime_type="image/png"),
        "add a tiny astronaut helmet",
    ],
    config=types.GenerateContentConfig(response_modalities=["IMAGE"]),
)

open("edited.png", "wb").write(resp.candidates[0].content.parts[0].inline_data.data)

4. Streaming

Use generate_content_stream to receive the response as it’s produced.

stream = client.models.generate_content_stream(
    model="gemini-2.5-flash-image",
    contents="a watercolor banana wearing tiny sunglasses",
    config=types.GenerateContentConfig(response_modalities=["IMAGE"]),
)

for chunk in stream:
    for part in chunk.candidates[0].content.parts or []:
        if part.inline_data and part.inline_data.data:
            open("out.png", "wb").write(part.inline_data.data)

The raw HTTP endpoint is :streamGenerateContent?alt=sse, which returns Server-Sent Events (data: {json} frames) — exactly what the SDK consumes.

5. Count tokens

countTokens is proxied straight to Google, so you get a real token count for your request — useful for budgeting before you generate.

result = client.models.count_tokens(
    model="gemini-3-pro-image",
    contents="a red panda astronaut floating in a nebula",
)
print(result.total_tokens)

curl -s -X POST \
  "https://bananahub.io/api/gemini/v1beta/models/gemini-3-pro-image:countTokens" \
  -H "x-goog-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents": [{"parts": [{"text": "a red panda astronaut floating in a nebula"}]}]}'

Preview model ids are supported here too — see Models.

6. Handle errors

BananaHub returns errors in the Gemini envelope, so the SDK raises errors.APIError with the canonical status:

from google.genai import errors

try:
    resp = client.models.generate_content(
        model="gemini-3-pro-image",
        contents="a red panda",
        config=types.GenerateContentConfig(response_modalities=["IMAGE"]),
    )
except errors.APIError as exc:
    print(exc.code, exc.status, exc.message)
    # e.g. 403 PERMISSION_DENIED  API key missing permission for gemini-3-pro-image

See Errors for the full status list.

Get Started

Core Concepts

Gemini-compatible API

Jobs & Account

API Reference

1. Install and configure

2. Text-to-image

Resolution

3. Image-to-image (edit)

4. Streaming

5. Count tokens

6. Handle errors

​1. Install and configure

​2. Text-to-image

​Resolution

​3. Image-to-image (edit)

​4. Streaming

​5. Count tokens

​6. Handle errors

1. Install and configure

2. Text-to-image

Resolution

3. Image-to-image (edit)

4. Streaming

5. Count tokens

6. Handle errors