# Puzzle — AI 图像生成 API

> 通过一个 API 调用 Nano Banana 2 和 Nano Banana Pro。按使用量计费——加密货币或银行转账。Veo、Omni 和 Gemini 即将上线。

## Puzzle 是什么

Puzzle 通过统一 API（https://api.puzzle-cloud.com）提供 Nano Banana 2（`nano-banana-v2`）和 Nano Banana Pro（`nano-banana-pro`）的访问能力。按每张生成图片计费：任务被接受时预留最高价格，完成时扣费；失败或取消的任务不扣费。以以太坊、波场或 BNB 上的 USDC/USDT 充值，或联系支持进行银行转账。

## 快速开始

1. 在 https://puzzle-cloud.com/login 注册
2. 在控制台创建 API 密钥（`puz_live_…`，仅显示一次，只存储 SHA-256 哈希）
3. 使用 `Authorization: Bearer puz_live_…` 调用 `POST https://api.puzzle-cloud.com/v1/text-generations` → 返回 `202` 与任务对象；轮询 `GET /v1/jobs/{id}` 直到 `status` 为 `completed`，再下载 `result.url`

```
curl -sS -X POST "https://api.puzzle-cloud.com/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"}'
```

## 代理文档

- 完整参考（英文）：https://puzzle-cloud.com/docs.md
- 完整参考（中文）：https://puzzle-cloud.com/docs-zh.md
- OpenAPI 3.1：https://puzzle-cloud.com/openapi.json
- 文档页面：https://puzzle-cloud.com/docs
- 价格：`GET https://api.puzzle-cloud.com/v1/pricing`（公开，无需密钥）或 https://puzzle-cloud.com/pricing——不要凭记忆报价

## 接口（主机 https://api.puzzle-cloud.com）

- `POST /v1/text-generations` — 文生图任务（API 密钥；计入频率上限）
- `POST /v1/url-generations` — 图生图任务，`url` / `image_url` 或 `upload_id`（API 密钥；计入频率上限）
- `POST /v1/uploads` — 存储图生图源图（API 密钥；计入频率上限）。multipart `file`、JSON `data`（base64）或 JSON `url`
- `GET /v1/uploads` — 列出仍有效的上传（API 密钥）
- `GET /v1/uploads/{id}` — 单个上传 + 新签名链接（API 密钥）
- `DELETE /v1/uploads/{id}` — 删除上传（API 密钥）
- `POST /v1/quote` — 询价，不创建任务（API 密钥）
- `GET /v1/jobs` — 任务历史，倒序，游标分页（API 密钥）
- `GET /v1/jobs/{id}` — 任务状态；已完成任务带下载链接（API 密钥）
- `POST /v1/jobs/{id}/cancel` — 取消仍在排队的任务（API 密钥）
- `GET /v1/usage` — 按 UTC 日期的任务、扣费与图片数汇总，可 group_by（API 密钥）
- `GET /v1/balance` — 可用与预留余额（API 密钥）
- `GET /v1/models` — 模型目录，含参数与价格（公开）
- `GET /v1/pricing` — 生效价目表（公开）
- `GET /v1/outputs/{key}?exp&sig` — 通过签名链接下载生成图片（无需密钥；签名即凭证）

## 在线模型

- `nano-banana-v2` — 文本生图和图生图
- `nano-banana-pro` — 文本生图和图生图（更高质量）

参数：`aspect_ratio` 1:1 | 16:9 | 9:16 | 4:3；`resolution` 1K（默认）| 2K | 4K；`prompt` ≤ 4000 字符；可选 `callback_url`（HTTPS 回调）、`user`（你方最终用户 id，≤ 128 字符）、`max_price`（USD 上限，超出返回 409）。

## 即将上线（上线前返回 HTTP 422 `model_unavailable`）

- `omni`
- `veo`
- `gemini` ← Puzzle 模型 ID，非 Gemini 应用

## 关键信息

- 鉴权：`Authorization: Bearer puz_live_…`（或 `X-Api-Key: puz_live_…`）
- 密钥属于工作区；余额、任务、频率上限和用量都按工作区计算
- 余额为零返回 HTTP **402** `insufficient_funds`——这是正常结果，不是接口故障；不扣费
- 密钥仅显示一次，只存 SHA-256 哈希；丢失后需撤销并重新创建；已撤销密钥返回 401
- 幂等：`Idempotency-Key` 头（≤ 128 字符）——同请求体重放任务（`Idempotent-Replayed: true`），不同请求体 → 409 `idempotency_conflict`
- 频率上限：按工作区，生成接口与 `POST /v1/uploads`，默认每 60 秒窗口 60 次；读取 `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset`，429 时读取 `Retry-After`
- 结果：`result.url` 为签名链接，有效至 `result.expires_at`——目前为完成后 7 天；请在此之前下载（之后返回 410 `output_expired`）
- 上传：图生图源图；`POST /v1/url-generations` 传 `upload_id`。运营方可关闭新上传（`503 uploads_disabled`）而不删除已有文件。费用（若有）见 `GET /v1/pricing.uploads`；未付存储费会把 TTL 缩短到 24 小时
- Webhook：`callback_url` 接收 job.queued、job.completed、job.failed、job.cancelled；控制台地址接收 job.completed 与 job.failed；`X-Puzzle-Signature: sha256=<对 "<X-Puzzle-Timestamp>.<body>" 的 HMAC>`；重试间隔 30 秒、2 分、10 分、1 时、6 时、24 时
- 错误：`{ "error": { "status", "code", "message", "request_id" } }`；`request_id` = 响应头 `X-Request-Id`。代码：invalid_json、invalid_request、unauthorized、insufficient_funds、key_spend_limit_exceeded、model_not_allowed、output_forbidden、job_not_found、upload_not_found、output_not_found、method_not_allowed、idempotency_conflict、price_exceeds_max、job_not_cancellable、upload_quota_exceeded、output_expired、upload_too_large、unsupported_media_type、model_unavailable、rate_limited、internal_error、pricing_unavailable、uploads_disabled
- 没有银行卡结账；提示词和输出不用于模型训练
- SLA：仅在签约合同中提供

## 充值方式

加密货币在控制台自助操作：USDC 或 USDT，走以太坊、波场或 BNB。转账后粘贴哈希；我们确认到账后计入余额。不想用加密货币？微信或 Telegram @PUZZLE_Support_AI 联系——我们开票并入同一余额。没有银行卡结账。

## 支持

Telegram：https://t.me/PUZZLE_Support_AI  
微信：通过 Telegram 联系

SKIPPED WECHAT_ID