Introduction

Welcome to the Puzzle API Reference. Puzzle is an inference provider designed to host and run Google's generative models—including Nano Banana (image generation) and Veo (video & high-definition generation)—at scale, and at pricing structures significantly below standard market rates.

All image and video generation jobs on Puzzle are executed asynchronously. When you request a generation, our cluster receives the task and instantly returns a job_id. You can retrieve results either by polling the job status endpoint or by registering a webhook listener.

Authentication

To authorize requests to the Puzzle API, you must generate an API Key in your web dashboard and pass it as a Bearer token in the Authorization header of every request.

Authorization Header

Authorization: Bearer YOUR_PUZZLE_API_KEY

You can also specify an optional Idempotency-Key header with a unique UUID string. Replaying the same key within 24 hours returns the original job_id without creating a duplicate job or charging your balance again.

Get Balance

Check your account's available credits and balance in USD.

GET/v1/balance

curl -s https://api.puzzle.team/v1/balance \
  -H "Authorization: Bearer $PUZZLE_API_KEY"

Response Example

{
  "available_balance": 42.50,
  "currency": "USD",
  "status": "active"
}

Select Model Tier to Customize Reference Paths

Currently showing endpoint paths and parameters customized for nano-banana-pro.

Generate from Text (nano-banana-pro)

Create an asynchronous text-to-image or text-to-video generation using nano-banana-pro.

POST/v1/text-generations

Parameter	Type	Description
modelrequired	string	The model to use: `nano-banana-pro`.
promptrequired	string	Detailed text prompt describing the desired media to be generated. Minimum length 1.
aspect_ratio	string	Format of the output. Supported options: `1:1`, `16:9`, `9:16`, `4:3`, `21:9`. Default is `1:1`.
resolution	string	Output resolution limit. Currently supported: 1K, 2K, 4K (Images) / 720p, 1080p (Videos).
callback_url	string	Optional. Registered webhook URL to send the terminal job state to. See Webhooks section.
metadata	object	Optional. Object containing custom metadata keys and values to be returned in the webhook payload. Keys starting with `_` are stripped.

curl -X POST "https://api.puzzle.team/v1/text-generations" \
  -H "Authorization: Bearer $PUZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "A glowing holographic puzzle piece floating in digital space, neon cyan light, 3d render",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "metadata": {"order_id":"abc-123"}
  }'

Response Example

{
  "job_id": "0193a7f2-1c4a-7e0b-9b3a-2f1d8c6e4a55",
  "status": "queued",
  "status_url": "/api/v1/jobs/0193a7f2-1c4a-7e0b-9b3a-2f1d8c6e4a55"
}

Image-to-Image (nano-banana-pro)

Generate an output image using 1 to 14 input source image URLs and a modifying text prompt instruction.

POST/v1/url-generations

Parameter	Type	Description
modelrequired	string	The model to use: `nano-banana-pro`.
promptrequired	string	Modifying prompt. Minimum length 1.
input_images_urlsrequired	string[]	Array containing 1 to 14 image URLs. Must start with `http://` or `https://`. Total file size must not exceed 200 MB.
aspect_ratio	string	Supported aspect ratios or `auto` (uses the exact aspect ratio of the first input image). Default is `auto`.
resolution	string	Output resolution limit. Supported: 1K, 2K, 4K (Images) / 720p, 1080p (Videos).

curl -X POST "https://api.puzzle.team/v1/url-generations" \
  -H "Authorization: Bearer $PUZZLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "make it look like a watercolor painting",
    "aspect_ratio": "auto",
    "resolution": "1K",
    "input_images_urls": [
      "https://example.com/photo-1.jpg"
    ],
    "metadata": {"order_id":"abc-123"}
  }'

Retrieve Job Status

Retrieve the status and final assets of an asynchronous request. Poll this endpoint until status is done or failed.

GET/v1/jobs/:id

curl -s https://api.puzzle.team/v1/jobs/0193a7f2-1c4a-7e0b-9b3a-2f1d8c6e4a55 \
  -H "Authorization: Bearer $PUZZLE_API_KEY"

Response Example (Done)

{
  "job_id": "0193a7f2-1c4a-7e0b-9b3a-2f1d8c6e4a55",
  "status": "done",
  "created_at": "2026-06-11T12:00:00Z",
  "started_at": "2026-06-11T12:00:01Z",
  "finished_at": "2026-06-11T12:00:09Z",
  "result": {
    "image_url": "https://api.puzzle.team/results/0193a7f2-1c4a-7e0b-9b3a-2f1d8c6e4a55.webp?sig=..."
  },
  "error": null
}

Webhooks

Instead of continuously polling, you can configure Webhooks in your web panel. When a job reaches a terminal state (done or failed), Puzzle will perform a POST request with JSON body to your registered listener URL.

Every webhook delivery is signed with HMAC-SHA256 signature in the X-Signature header.

Webhook Payload Example

{
  "job_id": "0193a7f2-1c4a-7e0b-9b3a-2f1d8c6e4a55",
  "status": "done",
  "result": {
    "image_url": "https://api.puzzle.team/results/0193a7f2-1c4a-7e0b-9b3a-2f1d8c6e4a55.webp?sig=..."
  },
  "error": null,
  "metadata": {
    "order_id": "abc-123"
  }
}

Verify the Signature

The signature is calculated as HMAC-SHA256("{X-Timestamp}.{body}", secret) where body is the JSON payload serialized with keys sorted alphabetically and all whitespaces removed.

Errors & Statuses

Here are the HTTP status codes returned by the Puzzle API:

HTTP Code	Error Type	Description
`401`	Unauthorized	Missing or invalid `Authorization: Bearer` header API key.
`402`	Payment Required	Available balance is insufficient to create the generation job.
`403`	Forbidden	The requested resource, model, or action is disabled for this key.
`422`	Unprocessable Entity	Validation error (invalid parameters, missing prompt, etc.).
`503`	Service Unavailable	GPU clusters are overloaded. Re-submit request in a few seconds.

Gemini SDK Compatibility

Because Puzzle implements the identical REST interface and schemas as standard Google Gemini API models, you do not need to install any custom libraries or refactor your systems. Just instantiate the official Google Gemini SDK and set the base_url parameter to point to Puzzle.

1. Install and Configure

Install SDK

pip install google-genai

Initialize Client (Python)

from google import genai
from google.genai import types

client = genai.Client(
    api_key="YOUR_PUZZLE_KEY",
    http_options=types.HttpOptions(base_url="https://api.puzzle.team/v1/gemini"),
)

2. Text-to-Image Generation

Text-to-Image (Python)

resp = client.models.generate_content(
    model="gemini-2.5-flash-image",
    contents="a glowing neon puzzle piece floating in digital space",
    config=types.GenerateContentConfig(
        response_modalities=["IMAGE"],
        image_config=types.ImageConfig(aspect_ratio="16:9", image_size="2K"),
    ),
)

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

3. Image-to-Image Editing

Image-to-Image (Python)

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 glowing astronaut helmet",
    ],
    config=types.GenerateContentConfig(response_modalities=["IMAGE"]),
)

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

4. Streaming Media Chunks

Streaming Output (Python)

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", "ab").write(part.inline_data.data)

Interactive Playground

Test our inference pipeline live. Write a prompt below to simulate a request to the Puzzle API and view both the asynchronous response progression and the final generated media.

API Request Sandbox

Model

Prompt

Aspect Ratio

Resolution

Callback URL (Webhook)

Metadata (JSON)

JSON Response

// Enter prompt and click Send Test Request to run a simulation

Generated Result

Awaiting request execution