Nano Banana 2 API Examples for PoYo

Focused server-side examples for building with nano-banana-2 and nano-banana-2-edit on PoYo.

Model Page | Docs | Get API Key | Pricing | Main Examples

Nano Banana 2 is useful for fast image generation and editing workflows: product visuals, social ads, concept boards, localized creatives, and clean reference-based edits.

Sample output: see the PoYo model page samples.

These are official PoYo model page samples, not files generated by this repo.

What This Repo Covers

• Text-to-image with nano-banana-2
• Image editing with nano-banana-2-edit
• cURL and Node.js backend examples
• Async task flow: submit, store data.task_id, poll status, retrieve files
• Webhook receiver notes for production callbacks
• Prompt examples and production integration notes

Quick Start

cp .env.example .env
# Edit .env and set POYO_API_KEY

Run the Node.js example:

cd node
npm start

Keep POYO_API_KEY on the server. Do not expose it in browser code, mobile apps, screenshots, or public logs.

API Flow

Submit an image task:

POST https://api.poyo.ai/api/generate/submit
Authorization: Bearer <POYO_API_KEY>
Content-Type: application/json

Store the returned data.task_id, then poll:

GET https://api.poyo.ai/api/generate/status/{task_id}
Authorization: Bearer <POYO_API_KEY>

For production queues, pass callback_url during submit and use a webhook receiver for terminal task updates.

Generate

{
  "model": "nano-banana-2",
  "input": {
    "prompt": "A clean studio product image of a compact travel camera on a white table, soft daylight, realistic reflections, readable label area, premium ecommerce style",
    "size": "1:1",
    "resolution": "2K",
    "n": 1
  }
}

Image Edit Request

Use nano-banana-2-edit when the request includes one or more source images.

{
  "model": "nano-banana-2-edit",
  "callback_url": "https://example.com/api/poyo/webhook",
  "input": {
    "prompt": "Preserve the source subject, improve the scene composition, and keep the result realistic and production-ready",
    "size": "1:1",
    "resolution": "2K",
    "n": 1,
    "image_urls": [
      "https://example.com/source-product.png"
    ]
  }
}

Examples

Path	What it covers
curl/generate.md	Copy-paste submit and status requests.
node/	Native Node.js submit and poll flow.
webhooks/express-webhook/	Minimal Express receiver for PoYo callbacks.
docs/prompt-examples.md	Practical prompts for product workflows and creative tests.
docs/production-notes.md	Security and reliability notes before launch.

Expected Submit Response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-example",
    "status": "not_started",
    "created_time": "2026-05-23T08:00:00"
  }
}

Expected Status Response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-example",
    "status": "finished",
    "progress": 100,
    "files": [
      {
        "file_url": "https://storage.poyo.ai/generated/image.png",
        "file_type": "image"
      }
    ],
    "error_message": null
  }
}

Production Checklist

• Keep POYO_API_KEY server-side only.
• Validate prompts and source media URLs before submit.
• Store data.task_id before polling or waiting for webhooks.
• Treat finished and failed as terminal states.
• Log task IDs and status transitions, not API keys or private prompts.
• Make webhook handlers idempotent.
• Download returned files before they expire.
• Check current model availability and cost on the PoYo model page.

Run Checks

make check

On Windows:

./scripts/check.ps1

License

MIT