# Puzzle — complete API reference for agents

# Puzzle API reference

> Host: `https://api.puzzle.team`  Auth: `Authorization: Bearer puz_live_…`

## Authentication

All v1 endpoints (except `GET /v1/models`) require an API key:

```
Authorization: Bearer puz_live_<32-hex>
```

Keys are created in the console at https://puzzle-cloud.com/dashboard, shown once, stored as SHA-256. If lost, revoke and create a new one.

---

## Models

**Live** (accepted by API):

- `nano-banana-v2`
- `nano-banana-pro`

**Coming soon** (return HTTP 422 `model_unavailable` until live):

- `omni`
- `veo`
- `gemini`

---

## Endpoints

### POST /v1/text-generations

Create a text-to-image generation job.

**Request body** (JSON):

| Field | Type | Required | Notes |
|---|---|---|---|
| `model` | string | ✓ | `nano-banana-v2` or `nano-banana-pro` |
| `prompt` | string | ✓ | Up to 4 000 characters |
| `aspect_ratio` | string | | `1:1`, `16:9`, `9:16`, `4:3` |
| `resolution` | string | | `1K`, `2K`, `4K` |
| `callback_url` | string | | HTTPS webhook signed when job is accepted |

**Response** `202`:
```json
{ "id": "job_…", "status": "queued", "model": "nano-banana-pro" }
```

```bash
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 cyan puzzle piece, studio light","aspect_ratio":"1:1","resolution":"1K"}'
```

---

### POST /v1/url-generations

Image-to-image generation. Same fields as text-generations plus:

| Field | Type | Required | Notes |
|---|---|---|---|
| `url` | string | ✓ | HTTPS source image. Alias: `image_url` |

---

### GET /v1/jobs/{id}

Poll job status.

```bash
curl https://api.puzzle.team/v1/jobs/job_… -H "Authorization: Bearer $PUZZLE_API_KEY"
```

**Response** `200`:
```json
{ "id": "job_…", "status": "queued", "model": "nano-banana-pro", "kind": "text", "created_at": "…" }
```

---

### GET /v1/balance

Return current confirmed balance in USD.

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

**Response** `200`:
```json
{ "balance": 10.00, "currency": "USD", "status": "credited" }
```

---

### GET /v1/models

Public. List live and coming-soon models.

```json
{ "live": ["nano-banana-v2","nano-banana-pro"], "coming_soon": ["omni","veo","gemini"] }
```

---

## Error codes

| HTTP | code | When |
|---|---|---|
| 400 | `invalid_json` | Body is not JSON |
| 400 | `invalid_request` | Missing model, prompt, or url |
| 401 | `unauthorized` | Missing or unknown API key |
| 402 | `insufficient_funds` | Balance is $0.00 — fund and retry |
| 404 | `job_not_found` | No accepted job with that id |
| 405 | `method_not_allowed` | Wrong HTTP method |
| 422 | `model_unavailable` | Omni / Veo / Gemini — not served yet |
| 429 | `rate_limited` | Account RPM exceeded |
| 500 | `internal_error` | Unexpected server failure |

### 402 `insufficient_funds`

Your key is valid but confirmed credit is $0.00. Fund your balance in the console (USDC/USDT on Ethereum, Tron, or BNB), wait for confirmation, then retry. 402 is expected — not a down endpoint.

---

## Funding

Crypto is self-serve in the console: USDC or USDT on Ethereum, Tron, or BNB. Log the tx hash after sending; balance is updated when Puzzle confirms the received amount.

Prefer bank transfer? Reach out on Telegram: https://t.me/PUZZLE_Support_AI. No card checkout.

---

## Webhooks

Pass `callback_url` (HTTPS) in the request body. When the job is accepted (`queued`), Puzzle POSTs JSON to that URL with header `X-Puzzle-Signature: sha256=<hex>` using your workspace signing secret.

---

## FAQ

**How do I get started?**  
Sign up, create a key, POST /v1 with a Bearer token. Keep your prompts — pointing an official Google SDK at our host will not work.

**What does 402 mean?**  
The key is valid and confirmed credit is $0.00. Fund, wait for confirmation, then retry. 402 is expected — not a down endpoint.

**Are my prompts used for training?**  
No. Puzzle does not use your prompts or outputs to train Google models or ours.

**Can I see an API key again?**  
No. Puzzle stores a SHA-256 hash. Copy the key when it is created. If you lose it, revoke it and make a new one.

**Do you guarantee uptime?**  
Only in a signed contract. Per-account rate limits exist and are unpublished. Telegram https://t.me/PUZZLE_Support_AI if you need either.

**Which models are available?**  
Nano Banana 2 and Nano Banana Pro are live. Omni, Veo, and Gemini return 422 until they ship.

---

*Source: https://puzzle-cloud.com/docs — canonical reference*


---

## Error reference (machine-readable)

- HTTP 400 `invalid_json`: Body is not JSON
- HTTP 400 `invalid_request`: Missing model, prompt, or url
- HTTP 401 `unauthorized`: Missing or unknown API key
- HTTP 402 `insufficient_funds`: Balance is $0.00 — fund and retry
- HTTP 404 `job_not_found`: No accepted job with that id
- HTTP 405 `method_not_allowed`: Wrong HTTP method
- HTTP 422 `model_unavailable`: Omni / Veo / Gemini — not served yet
- HTTP 429 `rate_limited`: Account RPM exceeded
- HTTP 500 `internal_error`: Unexpected server failure

## Canonical

- Marketing: https://puzzle-cloud.com
- API host: https://api.puzzle.team
- Docs: https://puzzle-cloud.com/docs
- OpenAPI: https://puzzle-cloud.com/openapi.json
- Telegram support: https://t.me/PUZZLE_Support_AI

SKIPPED WECHAT_ID
SKIPPED WHATSAPP_E164