# PixelBridge 同步图片生成 API 调用说明 > 版本：2026-09-12 > Base URL：`https://nano.own-jarvis.com/v1` > 同步端点：`POST /chat/completions` 该接口兼容 OpenAI Chat Completions 请求格式。客户发起一次 HTTP 请求后保持连接，PixelBridge 在图片生成、上传 OSS 并完成计费后，直接在同一次响应中返回图片链接。不需要再轮询任务状态。 > 计费单位为积分：`1 元充值 = 1 积分到账`。每次请求只生成 1 张图片，以下价格均为每张图片的积分消耗。 ## 1. 鉴权 ```http Authorization: Bearer pbg_YOUR_API_KEY ``` API Key 在 PixelBridge 工作台的“API 接入”页面创建。完整密钥只显示一次，只能保存在客户服务端。 ## 2. 支持的模型 | 模型名 | 清晰度 | 每张消耗积分 | |---|---:|---:| | `gemini-3.1-flash-lite-image` | 1K | 0.0525 积分/张 | | `gemini-3.1-flash-image-preview` | 1K | 0.12 积分/张 | | `gemini-3.1-flash-image-preview-2k` | 2K | 0.135 积分/张 | | `gemini-3.1-flash-image-preview-4k` | 4K | 0.15 积分/张 | | `gemini-3-pro-image-preview` | 1K | 0.15 积分/张 | | `gemini-3-pro-image-preview-2k` | 2K | 0.18 积分/张 | | `gemini-3-pro-image-preview-4k` | 4K | 0.225 积分/张 | | `nano_banana_2`（特价渠道） | 1K | 0.072 积分/张 | | `nano_banana_2-2K`（特价渠道） | 2K | 0.072 积分/张 | | `nano_banana_2-4K`（特价渠道） | 4K | 0.09 积分/张 | | `nano_banana_pro-1K`（特价渠道） | 1K | 0.135 积分/张 | | `nano_banana_pro-2K`（特价渠道） | 2K | 0.135 积分/张 | | `nano_banana_pro-4K`（特价渠道） | 4K | 0.135 积分/张 | 备用模型名：Gemini 3.1 Flash 可使用 `nano-banana-2` / `nano-banana-2-2k` / `nano-banana-2-4k`；Gemini 3.0 Pro 可使用 `nano-banana-pro` / `nano-banana-pro-2k` / `nano-banana-pro-4k`。 支持比例：`16:9`、`9:16`、`1:1`、`4:3`、`3:4`。 特价渠道由独立的第二供应商承载，原渠道仍然保留。调用方式完全相同，只需把 `model` 换成上述 `nano_banana_*` 精确 SKU。特价渠道单次最多 8 张参考图；其他模型最多 10 张。 实际可用模型和当前账号价格可通过以下接口查询： ```bash curl 'https://nano.own-jarvis.com/v1/models' \ -H 'Authorization: Bearer pbg_YOUR_API_KEY' ``` 客户程序也可随时查询当前可用积分，该请求不扣积分： ```bash curl 'https://nano.own-jarvis.com/v1/account/balance' \ -H 'Authorization: Bearer pbg_YOUR_API_KEY' ``` ## 3. 文字生图 ```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: customer-order-20260807-0001' \ -d '{ "model": "gemini-3.1-flash-image-preview-2k", "messages": [{ "role": "user", "content": "高级感产品摄影，白色香水瓶放在浅灰色石材展台上，柔和侧光，洁净背景" }], "extra_body": { "imageConfig": {"aspectRatio": "4:3"} }, "stream": false }' ``` ## 4. 参考图改图 `content` 使用 OpenAI 多模态数组格式。每个请求最多 10 张参考图，支持公网 HTTPS 图片或 `data:image/...;base64,...`。 ```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: customer-edit-20260807-0001' \ -d '{ "model": "gemini-3-pro-image-preview-4k", "messages": [{ "role": "user", "content": [ { "type": "image_url", "image_url": {"url": "https://cdn.example.com/product-front.png"} }, { "type": "image_url", "image_url": {"url": "https://cdn.example.com/product-side.png"} }, { "type": "text", "text": "保持产品外形、材质和 Logo 不变，改成黑色高级感影棚背景" } ] }], "extra_body": { "imageConfig": {"aspectRatio": "3:4"} }, "stream": false }' ``` 参考图要求： - 支持 JPEG、PNG、WebP。 - 单张不超过 10MB。 - 最多 10 张。 - 链接必须是公开 HTTPS 地址，不接受 HTTP、localhost 或内网 IP。 ## 5. 成功响应 生成成功返回 HTTP `200 OK`： ```json { "id": "chatcmpl-2c5b905d-63a0-4bb6-8b54-e39980b30e61", "object": "chat.completion", "created": 1786075200, "model": "gemini-3.1-flash-image-preview-2k", "choices": [{ "index": 0, "message": { "role": "assistant", "content": "![image](https://bucket.example.com/result.png?Signature=...)", "images": [{ "type": "image_url", "image_url": {"url": "https://bucket.example.com/result.png?Signature=..."} }] }, "finish_reason": "stop" }], "task_id": "2c5b905d-63a0-4bb6-8b54-e39980b30e61", "result": { "file_url": "https://bucket.example.com/result.png?Signature=...", "file_ext": "png", "file_size": 1234567, "mime_type": "image/png", "storage": "oss", "expires_at": "2026-08-14T04:00:00+00:00" }, "billing": { "amount": "0.1350", "refunded": false } } ``` 建议优先读取 `result.file_url`。为兼容 OpenAI Chat Completions 客户端，相同图片链接也会出现在 `choices[0].message.content` 和 `choices[0].message.images[0].image_url.url`。 `file_url` 始终是可直接下载的完整 `http/https` 地址。OSS 正常时返回私有 OSS 限时签名链接；OSS 暂时不可用时自动返回平台限时签名地址。两种地址都无需附带 PixelBridge API Key，签名过期后可重新查询原任务刷新。 ## 6. Python 完整示例 ```python import requests BASE_URL = "https://nano.own-jarvis.com" API_KEY = "pbg_YOUR_API_KEY" response = requests.post( f"{BASE_URL}/v1/chat/completions", headers={ "Authorization": f"Bearer {API_KEY}", "Idempotency-Key": "customer-order-20260807-0001", }, json={ "model": "gemini-3.1-flash-lite-image", "messages": [{ "role": "user", "content": "极简风白色陶瓷杯产品摄影，浅灰色背景", }], "extra_body": {"imageConfig": {"aspectRatio": "1:1"}}, "stream": False, }, timeout=650, ) response.raise_for_status() data = response.json() image_url = data["result"]["file_url"] image = requests.get(image_url, timeout=120) image.raise_for_status() with open(f"result.{data['result']['file_ext']}", "wb") as file: file.write(image.content) print("task_id:", data["task_id"]) print("image_url:", image_url) ``` ## 7. OpenAI Python SDK 示例 ```python from openai import OpenAI client = OpenAI( api_key="pbg_YOUR_API_KEY", base_url="https://nano.own-jarvis.com/v1", timeout=650, ) response = client.chat.completions.create( model="gemini-3.1-flash-lite-image", messages=[{ "role": "user", "content": "一架蓝色纸飞机，极简产品摄影", }], stream=False, extra_body={"imageConfig": {"aspectRatio": "1:1"}}, ) print(response.choices[0].message.content) ``` SDK 自定义请求头不方便时，建议使用 `requests` 示例以便明确传递 `Idempotency-Key`。 ## 8. 超时、幂等和重试 - 客户端 HTTP 超时请设为至少 `650` 秒，4K 或多参考图可能需要数分钟。 - `stream` 必须为 `false` 或省略；当前不支持 SSE 流式生图。 - 每次请求只生成 1 张图，`n` 只能省略或传 `1`。 - 每个业务请求都应设置唯一且稳定的 `Idempotency-Key`。 - 客户端超时、连接中断或没有收到完整响应时，必须使用原来的 `Idempotency-Key` 重试，避免重复生成和扣费。 - 如果接口明确提示“系统已自动退回积分；请使用新的 Idempotency-Key”，说明本次任务已确认失败；重新生成时应换一个新 Key。 - 幂等重放成功时，响应头 `Idempotency-Replayed` 为 `true`。 - 同步超时响应如包含 `task_id`，可通过 `GET /v1/tasks/{task_id}` 查询该任务。 ## 9. 计费与退款 - 提交后从客户积分账户预扣本次积分。 - 生成成功后结算。 - 平台确认生成失败时自动退回积分，并在积分流水中留痕。 - 幂等重放不会重复扣积分。 ## 10. 错误处理 ```json { "success": false, "error": { "code": "BAD_REQUEST", "message": "参考图最多 10 张" } } ``` | HTTP | 含义 | 处理建议 | |---:|---|---| | 400 | 参数、模型、比例或图片地址无效 | 修正请求，不要原样重试 | | 401 | API Key 无效 | 检查或轮换密钥 | | 402 | 账户积分不足 | 充值积分或联系管理员 | | 403 | 客户账号已停用 | 联系管理员 | | 429 | 调用频率过高 | 等待后重试 | | 502/503 | 网关或上游异常 | 按错误信息处理；若已自动退回积分，换新幂等 Key 重新生成 | | 504 | 同步等待超时、任务仍在处理 | 复用原 `Idempotency-Key` 重试 | 任务历史、积分消耗和退积分流水均可在 PixelBridge 工作台查看。