# PixelBridge 图片生成 API 调用说明

> 版本：2026-09-17  
> API 地址：`https://nano.own-jarvis.com`  
> 接口类型：同步 + 异步图片生成 API

PixelBridge 提供文字生图和参考图改图能力。客户可按现有系统选择同步或异步调用：同步接口会等待生成完成并直接返回图片链接；异步接口会立即返回任务 ID，由调用方轮询结果。

> 计费单位为积分：`1 元充值 = 1 积分到账`。每次请求生成 1 张图片，表中价格均表示“每张图片消耗的积分”；只有生成成功才最终扣除，失败或取消会自动退回积分。

## 1. 接入流程

| 方式 | 接口 | 返回 | 适用场景 |
|---|---|---|---|
| Google AI Studio 原生 | `POST /v1beta/models/{model}:generateContent` | HTTP 200 返回 `candidates[].content.parts[].inlineData` | 已使用 Gemini `contents` 格式的客户 |
| 同步（推荐简单接入） | `POST /v1/chat/completions` | HTTP 200 直接返回图片链接 | 客户后端可以等待数分钟 |
| 异步 | `POST /v1/generate` | HTTP 202 返回 `task_id` | 队列、回调或不适合长连接的系统 |

无论选择哪种方式，每个业务请求都应传唯一且稳定的 `Idempotency-Key`，网络超时重试时必须复用原 Key。

## 2. 创建和使用 API Key

登录 PixelBridge，进入“API 接入”，点击“创建 API Key”。完整密钥只显示一次，请立即保存到服务端环境变量或密钥管理系统。

推荐认证方式：

```http
Authorization: Bearer pbg_YOUR_API_KEY
```

也支持：

```http
X-API-Key: pbg_YOUR_API_KEY
```

安全要求：

- 不要把 API Key 写进网页、App 前端或公开代码仓库。
- 不要通过 URL 查询参数传递 API Key。
- API Key 泄露后应立即在“API 接入”页面停用并重新创建。

## 3. 模型和客户积分价格

| `family` | 模型 | 支持清晰度 | 每张消耗积分 |
|---|---|---|---:|
| `nano-banana-lite` | Nano Banana 2 Lite | 1K | 0.0525 积分/张 |
| `gemini-flash` | Gemini 3.1 Flash（备用名 Nano Banana 2） | 1K / 2K / 4K | 0.12 / 0.135 / 0.15 积分/张 |
| `gemini-pro` | Gemini 3.0 Pro（备用名 Nano Banana Pro） | 1K / 2K / 4K | 0.15 / 0.18 / 0.225 积分/张 |
| `zex-flash` | Nano Banana 2 特价渠道 | 1K / 2K / 4K | 0.072 / 0.072 / 0.09 积分/张 |
| `zex-pro` | Nano Banana Pro 特价渠道 | 1K / 2K / 4K | 0.135 / 0.135 / 0.135 积分/张 |

支持的图片比例：

```text
16:9、9:16、1:1、4:3、3:4
```

Nano Banana 2 Lite 仅支持 1K。推荐在调用前请求 `GET /v1/models`，获取当前账号实际可用模型、清晰度和价格。

同步和 Google 原生接口可使用 `nano-banana-2[-2k|-4k]` 代替 Flash 模型名，使用 `nano-banana-pro[-2k|-4k]` 代替 Pro 模型名。

特价渠道使用独立的第二供应商，精确 SKU 为 `nano_banana_2`、`nano_banana_2-2K`、`nano_banana_2-4K`、`nano_banana_pro-1K`、`nano_banana_pro-2K`、`nano_banana_pro-4K`。同步、异步和 Google 原生兼容方式均可使用这些 SKU；该渠道最多支持 8 张参考图。

## 4. 查询模型

```bash
curl 'https://nano.own-jarvis.com/v1/models' \
  -H 'Authorization: Bearer pbg_YOUR_API_KEY'
```

查询不扣积分，会根据当前 API Key 所属账号返回实际售价。成功响应示例：

```json
{
  "object": "list",
  "total": 5,
  "unit": "points/image",
  "data": [
    {
      "id": "gemini-flash",
      "object": "model_family",
      "name": "Gemini 3.1 Flash",
      "display_alias": "Nano Banana 2",
      "aspect_ratios": ["16:9", "9:16", "1:1", "4:3", "3:4"],
      "image_sizes": ["1K", "2K", "4K"],
      "price_unit": "points/image",
      "prices": {"1K": "0.1200", "2K": "0.1350", "4K": "0.1500"},
      "skus": {
        "1K": "gemini-3.1-flash-image-preview",
        "2K": "gemini-3.1-flash-image-preview-2k",
        "4K": "gemini-3.1-flash-image-preview-4k"
      },
      "supports_reference": true,
      "max_reference_images": 10
    }
  ]
}
```

- `id` 是平台系列名，适用于异步任务的 `family` 参数。
- `skus` 是各清晰度的精确模型名，可直接用于同步、Google 原生和 OpenAI 兼容调用。
- `prices` 是当前账号每张图的积分售价，建议程序展示价格时以此接口为准。

### 4.1 查询余额

客户程序可以在启动时、提交生图前，或收到 `402` 错误后调用这个轻量接口：

```bash
curl 'https://nano.own-jarvis.com/v1/account/balance' \
  -H 'Authorization: Bearer pbg_YOUR_API_KEY'
```

成功返回 HTTP `200 OK`：

```json
{
  "object": "account.balance",
  "account_id": 12,
  "account": "customer_name",
  "status": "active",
  "balance": "18.5000",
  "balance_1e4": 185000,
  "unit": "points",
  "conversion_rate": "1 CNY = 1 point",
  "updated_at": "2026-09-17T02:30:00+00:00"
}
```

- `balance` 是固定 4 位小数的积分字符串，适合直接展示或用 Decimal 处理。
- `balance_1e4` 是最小计量整数，`10000` 表示 `1.0000` 积分，可避免浮点误差。
- 查询余额不会产生任何费用。API Key 无效时返回 HTTP `401`。

## 5. Google AI Studio 原生调用

原生接口使用 Google Gemini REST 的 `contents`、`parts` 和 `generationConfig` 结构，并通过 `x-goog-api-key` 传递 PixelBridge API Key。

```bash
curl -X POST \
  'https://nano.own-jarvis.com/v1beta/models/gemini-3.1-flash-lite-image:generateContent' \
  -H 'x-goog-api-key: pbg_YOUR_API_KEY' \
  -H 'Idempotency-Key: google-order-20260807-0001' \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "A quiet bookstore at dusk, warm cinematic light"}]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "1K"}
    }
  }'
```

生成图片以 Base64 形式返回在 `candidates[0].content.parts[0].inlineData.data`。完整文档：`https://nano.own-jarvis.com/gemini-api-docs.md`。

## 6. OpenAI 兼容同步调用（无需轮询）

同步接口兼容 OpenAI Chat Completions 的请求和响应结构，并在一个 HTTP 请求内等待生图完成。

```bash
curl -X POST 'https://nano.own-jarvis.com/v1/chat/completions' \
  -H 'Authorization: Bearer pbg_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-20260807-0001' \
  -d '{
    "model": "gemini-3.1-flash-image-preview-2k",
    "messages": [{
      "role": "user",
      "content": "A quiet bookstore at dusk, warm cinematic light"
    }],
    "stream": false,
    "extra_body": {
      "imageConfig": {"aspectRatio": "16:9"}
    }
  }'
```

成功返回 HTTP `200 OK`：

```json
{
  "id": "chatcmpl-2c5b905d-63a0-4bb6-8b54-e39980b30e61",
  "object": "chat.completion",
  "model": "gemini-3.1-flash-image-preview-2k",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "![image](https://...signed-oss-url...)",
      "images": [{"type": "image_url", "image_url": {"url": "https://...signed-oss-url..."}}]
    },
    "finish_reason": "stop"
  }],
  "task_id": "2c5b905d-63a0-4bb6-8b54-e39980b30e61",
  "result": {"file_url": "https://...signed-oss-url...", "storage": "oss"},
  "billing": {"amount": "0.1350", "refunded": false}
}
```

- `stream` 必须是 `false` 或不传，每次生成 1 张。
- 建议客户端 HTTP 超时设为 `650` 秒。
- 若收到 504，任务仍可能在处理；使用原 `Idempotency-Key` 重试，不会重复扣费。
- 若接口明确提示已自动退回积分，重新生成时应换一个新的 `Idempotency-Key`。
- 完整同步接入文档（含 Python 和 OpenAI SDK 示例）：`https://nano.own-jarvis.com/sync-api-docs.md`

## 7. 异步文字生图

### 请求

```bash
curl -X POST 'https://nano.own-jarvis.com/v1/generate' \
  -H 'Authorization: Bearer pbg_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-20260805-0001' \
  -d '{
    "family": "gemini-flash",
    "prompt": "A quiet bookstore at dusk, warm cinematic light",
    "aspect_ratio": "16:9",
    "image_size": "2K"
  }'
```

### 参数

| 字段 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `family` | string | 是 | 模型系列，例如 `gemini-flash` |
| `prompt` | string | 是 | 图片描述，最多 8000 个字符 |
| `aspect_ratio` | string | 否 | 默认 `1:1` |
| `image_size` | string | 否 | 默认 `1K`，可选 `1K`、`2K`、`4K` |
| `image_urls` | string[] | 否 | 参考图片，最多 10 张 |
| `webhook_url` | string | 否 | 任务结束后接收回调的公开 HTTPS 地址 |
| `webhook_secret` | string | 使用回调时是 | 用于 HMAC-SHA256 验签，至少 16 个字符 |

### 使用异步回调（可替代轮询）

在异步请求中增加：

```json
{
  "family": "gemini-flash",
  "prompt": "A quiet bookstore at dusk",
  "image_size": "2K",
  "webhook_url": "https://customer.example.com/webhooks/pixelbridge",
  "webhook_secret": "replace-with-a-long-random-secret"
}
```

任务完成、失败或取消后，平台会 `POST`：

```json
{
  "event": "task.completed",
  "task": {
    "task_id": "2c5b905d-63a0-4bb6-8b54-e39980b30e61",
    "status": "completed",
    "result": {"file_url": "https://...signed-oss-url..."}
  }
}
```

回调请求头：

```http
X-PixelBridge-Timestamp: 1786152000
X-PixelBridge-Event: task.completed
X-PixelBridge-Signature: v1=<hex-digest>
```

验签原文是 `timestamp + "." + 原始请求体字节`，签名算法为：

```python
expected = "v1=" + hmac.new(
    WEBHOOK_SECRET.encode(),
    timestamp.encode() + b"." + raw_body,
    hashlib.sha256,
).hexdigest()
assert hmac.compare_digest(expected, signature)
```

- 接收端应先验签，再按 `task.task_id + event` 幂等处理。
- 非 `2xx`、连接失败或超时会自动重试；默认最多 6 次。
- 回调状态和尝试次数也会出现在任务查询响应的 `webhook` 字段中。
- 已接收的异步任务进入持久队列；服务重启后会继续执行，不需要客户重新提交。

## 8. 异步参考图改图

### 使用公网 HTTPS 图片

```bash
curl -X POST 'https://nano.own-jarvis.com/v1/generate' \
  -H 'Authorization: Bearer pbg_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: edit-20260805-0001' \
  -d '{
    "family": "gemini-pro",
    "prompt": "保持产品外形不变，把背景替换为高级感摄影棚",
    "aspect_ratio": "3:4",
    "image_size": "4K",
    "image_urls": [
      "https://cdn.example.com/product.png"
    ]
  }'
```

参考图要求：

- 仅接受公开可访问的 HTTPS 地址，或 `data:image/...;base64,...`。
- 支持 JPEG、PNG、WebP。
- 每个任务最多 10 张参考图（`image_urls`、`upload_ids` 和 `messages` 中的图片合计）。
- 内网地址、localhost 和 HTTP 明文地址会被拒绝。

### 使用 Base64 图片

```json
{
  "family": "gemini-flash",
  "prompt": "保留主体结构，改成蓝色科技风",
  "aspect_ratio": "1:1",
  "image_size": "2K",
  "image_urls": [
    "data:image/png;base64,iVBORw0KGgoAAA..."
  ]
}
```

## 9. 异步提交成功响应

接口正常返回 HTTP `202 Accepted`：

```json
{
  "task_id": "2c5b905d-63a0-4bb6-8b54-e39980b30e61",
  "model": "gemini-3.1-flash-image-preview-2k",
  "family": "gemini-flash",
  "task_type": "t2i",
  "aspect_ratio": "16:9",
  "image_size": "2K",
  "status": "submitting",
  "stage": "正在提交",
  "progress": 4,
  "amount": "0.1350",
  "refunded": false,
  "created_at": "2026-08-05T01:00:00+00:00"
}
```

`task_type`：

- `t2i`：文字生图。
- `r2i`：参考图改图。

`amount` 是本次消耗的积分数。提交时会从积分账户预扣；任务成功后结算，确认失败或取消后自动退回并生成积分流水。

## 10. 查询任务状态

```bash
curl 'https://nano.own-jarvis.com/v1/tasks/TASK_ID' \
  -H 'Authorization: Bearer pbg_YOUR_API_KEY'
```

| 状态 | 含义 | 是否继续轮询 |
|---|---|---:|
| `submitting` | 已进入平台后台队列 | 是 |
| `queued` | 上游已接受任务 | 是 |
| `processing` | 正在生成 | 是 |
| `completed` | 已完成，可以下载 | 否 |
| `failed` | 生成失败，通常已退款 | 否 |
| `cancelled` | 已取消，已退款 | 否 |

生成 4K 图片可能需要数分钟。只要状态仍是 `submitting`、`queued` 或 `processing`，就不要重复提交新任务。

### 完成响应

```json
{
  "task_id": "2c5b905d-63a0-4bb6-8b54-e39980b30e61",
  "status": "completed",
  "progress": 100,
  "amount": "0.1350",
  "result": {
    "file_url": "https://nano.own-jarvis.com/v1/tasks/2c5b905d-63a0-4bb6-8b54-e39980b30e61/file?expires=...&signature=...",
    "preview_url": "https://nano.own-jarvis.com/api/tasks/2c5b905d-63a0-4bb6-8b54-e39980b30e61/preview",
    "storage": "local",
    "fallback_file_url": "https://nano.own-jarvis.com/v1/tasks/2c5b905d-63a0-4bb6-8b54-e39980b30e61/file",
    "fallback_preview_url": "https://nano.own-jarvis.com/api/tasks/2c5b905d-63a0-4bb6-8b54-e39980b30e61/preview",
    "url_expires_at": "2026-08-05T13:02:03+00:00",
    "file_ext": "png",
    "file_size": 1234567,
    "mime_type": "image/png",
    "expires_at": "2026-08-12T01:02:03+00:00",
    "type": "t2i"
  }
}
```

## 11. 下载图片

`result.file_url` 始终返回完整的 `http/https` 地址。OSS 正常时返回私有 OSS 限时签名链接；OSS 暂时不可用时会自动改用平台限时签名地址。两种地址都可直接下载，无需附带 PixelBridge API Key。签名过期后，重新查询任务即可获取新链接。

`result.fallback_file_url` 是稳定的平台鉴权回退地址，使用时必须携带 API Key：

```bash
curl -L \
  -H 'Authorization: Bearer pbg_YOUR_API_KEY' \
  -o result.png \
  'https://nano.own-jarvis.com/v1/tasks/TASK_ID/file'
```

结果默认保存 7 天，请在 `expires_at` 之前下载并转存到自己的对象存储。

## 12. 幂等与重试：避免重复扣费

每次业务请求必须生成一个稳定且唯一的 `Idempotency-Key`，例如订单号：

```http
Idempotency-Key: customer-order-20260805-0001
```

规则：

1. 同一业务请求重试时，必须复用原来的 `Idempotency-Key`。
2. 不要因为网络断开、504 或客户端超时就换新 Key 重新提交。
3. 只有接口明确提示“已自动退回积分；请使用新的 Idempotency-Key”时，重新生成才换新 Key。
4. 使用相同 Key 重试时，平台会返回原任务，不会重复建任务或重复扣客户积分。
5. 也可以先调用 `GET /v1/tasks` 检查最近任务，再决定是否重试。

## 13. Python 异步完整示例

安装依赖：

```bash
pip install requests
```

```python
import time
import requests

BASE_URL = "https://nano.own-jarvis.com"
API_KEY = "pbg_YOUR_API_KEY"
IDEMPOTENCY_KEY = "order-20260805-0001"

headers = {
    "Authorization": f"Bearer {API_KEY}",
}

create_response = requests.post(
    f"{BASE_URL}/v1/generate",
    headers={
        **headers,
        "Idempotency-Key": IDEMPOTENCY_KEY,
    },
    json={
        "family": "gemini-flash",
        "prompt": "A premium product photo on a clean stone pedestal",
        "aspect_ratio": "1:1",
        "image_size": "2K",
    },
    timeout=30,
)
create_response.raise_for_status()
task = create_response.json()
task_id = task["task_id"]

while True:
    query_response = requests.get(
        f"{BASE_URL}/v1/tasks/{task_id}",
        headers=headers,
        timeout=30,
    )
    query_response.raise_for_status()
    task = query_response.json()

    if task["status"] == "completed":
        break
    if task["status"] in {"failed", "cancelled"}:
        raise RuntimeError(task.get("error") or "图片生成失败")

    time.sleep(6)

file_url = task["result"]["file_url"]
file_response = requests.get(file_url, timeout=120)
file_response.raise_for_status()

filename = f"result.{task['result']['file_ext']}"
with open(filename, "wb") as file:
    file.write(file_response.content)

print(f"图片已保存：{filename}")
```

## 14. 其他接口

| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/v1/models` | 可用模型、规格与当前账号价格 |
| `GET` | `/v1/account/balance` | 查询当前可用积分（推荐程序监控使用） |
| `POST` | `/v1beta/models/{model}:generateContent` | Google Gemini 原生格式同步生图 |
| `POST` | `/v1/chat/completions` | 同步生图，直接返回图片链接 |
| `POST` | `/v1/generate` | 提交图片任务 |
| `GET` | `/v1/tasks/{task_id}` | 查询单个任务 |
| `GET` | `/v1/tasks?status=completed&limit=50` | 查询任务列表 |
| `GET` | `/v1/tasks/{task_id}/file` | 下载生成结果 |
| `DELETE` | `/v1/tasks/{task_id}` | 取消仍可取消的任务 |
| `GET` | `/v1/account` | 查询积分余额和调用统计 |
| `GET` | `/me` | 查询积分余额和调用统计 |

## 15. 错误码

错误响应：

```json
{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Nano Banana 2 Lite 仅支持 1K"
  }
}
```

| HTTP | 含义 | 处理建议 |
|---:|---|---|
| 400 | 参数、比例、图片或模型无效 | 修改请求，不要原样重试 |
| 401 | API Key 无效 | 检查、重新创建或轮换密钥 |
| 402 | 账户积分不足 | 充值积分或联系管理员 |
| 403 | 客户账号已停用 | 联系管理员 |
| 404 | 任务不存在或不属于当前账号 | 检查任务 ID |
| 409 | 当前任务状态不能执行该操作 | 重新查询任务状态 |
| 429 | 调用频率过高 | 等待后指数退避重试 |
| 502/503 | 网关或上游异常 | 按错误信息处理；若已自动退回积分，换新幂等 Key |
| 504 | 同步等待超时、任务仍在处理 | 使用同一个幂等 Key 重试 |

## 16. 接入检查清单

- [ ] API Key 只保存在服务端。
- [ ] 每次业务请求都有稳定的 `Idempotency-Key`。
- [ ] 已选择 Google 原生、OpenAI 兼容同步或异步调用方式。
- [ ] 同步调用的 HTTP 超时不小于 650 秒。
- [ ] 异步调用在 HTTP 202 后保存 `task_id`，每 5～8 秒轮询一次。
- [ ] 只在 `completed` 后下载图片。
- [ ] `failed` 或 `cancelled` 时记录错误和退款状态。
- [ ] 结果在过期前转存到自己的存储。
- [ ] 网络错误重试时复用原幂等 Key。

如需创建账号、充值或处理 API Key，请联系 PixelBridge 管理员。