图片生成 API 对接文档
一个 API Key 统一调用 Nano Banana Pro、GPT Image 2 All、GPT Image 2 VIP。三个模型统一按成功请求计费，每次消耗 1 个调用额度。
OpenAI 风格鉴权文生图图生图 / 编辑对话式改图失败自动退回额度统一参数网关
1. 快速开始
基础地址：
https://image.alibbbb.com/v1
最简文生图：
curl https://image.alibbbb.com/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: demo_20260614_0001" \
-d '{
"model": "gpt-image-2-vip",
"prompt": "黑金色智能手表商业海报，深蓝宇宙背景",
"size": "2048x1152",
"response_format": "url",
"output_format": "png"
}'
2. 鉴权与幂等
推荐请求头：
Authorization: Bearer YOUR_API_KEY
也支持：
X-API-Key: YOUR_API_KEY
生产环境建议为每次业务请求增加幂等键，避免客户端超时重试导致重复提交：
Idempotency-Key: order_20260614_000001
幂等键长度 8-128 位，仅允许字母、数字、点、下划线、冒号和短横线。同一 API Key 重复使用同一幂等键会返回 409，并且不会重复扣费。
3. 可用模型
| 模型 ID | 能力 | 尺寸处理方式 | 计费 |
|---|---|---|---|
nano-banana-pro | 文生图、图生图、多图融合 | 精确尺寸自动映射为最接近的清晰度和比例 | 1 次/成功请求 |
gpt-image-2-all | 文生图、图片编辑、对话式改图 | 网关接收尺寸参数，并自动转换进提示词 | 1 次/成功请求 |
gpt-image-2-vip | 精准尺寸、1K/2K/4K、图片编辑 | 网关向上游传递精确像素 size | 1 次/成功请求 |
查询模型：
GET /v1/models
4. 价格
| 套餐 | 折扣 | 实付 | 折后单价 |
|---|---|---|---|
| 200 次 | 标准价 | ¥100.00 | ¥0.5000/次 |
| 500 次 | 95 折 | ¥237.50 | ¥0.4750/次 |
| 1000 次 | 93 折 | ¥465.00 | ¥0.4650/次 |
| 5000 次 | 9 折 | ¥2250.00 | ¥0.4500/次 |
| 10000 次 | 88 折 | ¥4400.00 | ¥0.4400/次 |
支付成功后自动创建 API 账户、增加额度，并在支付结果页下发完整 API Key。
5. 参数规则与兼容性
重要：表格中的“可选”表示参数可以不传，系统会使用默认值；不表示模型不支持。三个模型都可以接收统一网关参数。
尺寸优先级：具体 size 优先于 image_size + aspect_ratio。
| 参数 | Nano Banana Pro | GPT Image 2 All | GPT Image 2 VIP | 说明 |
|---|---|---|---|---|
size | 支持，自动映射 | 支持，写入提示词 | 支持，原生精确尺寸 | 支持 1K/2K/4K、auto 或 WIDTHxHEIGHT |
image_size | 支持 | 支持 | 支持 | 1K、2K、4K |
aspect_ratio | 支持 | 支持 | 支持 | 1:1、16:9、9:16、4:3、3:4、3:2、2:3、21:9、4:5、5:4 |
response_format | 支持 | 支持 | 支持 | url 或 b64_json |
output_format | 支持 | 支持 | 支持 | png、jpg、webp；由网关统一转换 |
n | 支持，固定 1 | 支持，固定 1 | 支持，固定 1 | 当前仅支持 n=1 |
6. 文生图
POST /v1/images/generations
| 参数 | 类型 | 是否必填 | 支持模型 | 默认值 | 说明 |
|---|---|---|---|---|---|
| model | string | 必填 | 全部 | — | 三种模型 ID 之一 |
| prompt | string | 必填 | 全部 | — | 图片描述 |
| size | string | 可选 | 全部 | auto | 如 2048x1152；也可传 1K/2K/4K |
| image_size | string | 可选 | 全部 | 2K | 1K、2K、4K |
| aspect_ratio | string | 可选 | 全部 | 1:1 | 支持 10 种常用比例 |
| response_format | string | 可选 | 全部 | url | url 或 b64_json |
| output_format | string | 可选 | 全部 | png | png、jpg、webp |
| n | integer | 可选 | 全部 | 1 | 当前仅支持 1 |
Python：
import requests
r = requests.post(
"https://image.alibbbb.com/v1/images/generations",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"model": "nano-banana-pro",
"prompt": "中国仙侠人物电影海报，蓝紫色灵气",
"image_size": "4K",
"aspect_ratio": "9:16",
"response_format": "url",
"output_format": "png",
"n": 1
},
timeout=360
)
r.raise_for_status()
print(r.json())
7. 图片编辑 / 图生图
POST /v1/images/edits，请求类型为 multipart/form-data。
curl https://image.alibbbb.com/v1/images/edits \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "model=gpt-image-2-vip" \
-F "prompt=保持人物脸部不变，换成高端黑色西装" \
-F "image=@person.png" \
-F "size=1536x2048" \
-F "response_format=url" \
-F "output_format=png" \
-F "n=1"
可重复提交多个 image 字段，最多读取 6 张图片；单张不超过 12MB。
8. 对话式改图
POST /v1/chat/completions
{
"model": "gpt-image-2-all",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "把图片改成高级电商海报风"},
{"type": "image_url", "image_url": {"url": "data:image/png;base64,BASE64_DATA"}}
]
}
],
"image_size": "2K",
"aspect_ratio": "16:9",
"response_format": "url",
"output_format": "png",
"n": 1
}
9. 模型、账户、用量与健康检查
GET /v1/models：模型、参数支持情况和尺寸处理方式，需要 API Key。GET /v1/account：累计额度、剩余额度、已使用额度，需要 API Key。GET /v1/usage?limit=20：最近调用记录、成功与退款统计，需要 API Key。GET /v1/health：数据库、图片目录和上游配置健康状态，无需 API Key。
成功响应会返回 request_config，用于确认网关最终采用的尺寸、比例和输出格式。
{
"created": 1781370000,
"data": [{"url": "https://image.alibbbb.com/assets/media/apiimages/api_xxx.png"}],
"model": "gpt-image-2-vip",
"request_config": {
"normalized_size": "2048x1152",
"normalized_image_size": "2K",
"normalized_aspect_ratio": "16:9",
"response_format": "url",
"output_format": "png",
"n": 1
},
"usage": {"credits": 1, "remaining_credits": 499}
}
10. 响应头与限制
X-Request-ID：本次请求编号。X-Credits-Remaining：请求完成后的剩余额度。X-RateLimit-Limit：每分钟请求上限，默认 60。X-API-Version：公开 API 版本。
默认限制：JSON 请求体 2MB；提示词 20000 字符；单张图片 12MB；最多 6 张参考图；全部参考图合计 36MB；支持 PNG/JPG/WEBP。
11. 常见错误
| HTTP | 错误码 | 说明 |
|---|---|---|
| 400 | invalid_size / invalid_image_size / invalid_aspect_ratio | 尺寸参数不合法 |
| 400 | invalid_response_format / invalid_output_format / invalid_n | 输出参数不合法 |
| 401 | invalid_api_key | API Key 无效 |
| 402 | api_credits_not_enough | 调用额度不足 |
| 409 | idempotency_in_progress / idempotency_reused | 幂等键正在处理或已使用，未重复扣费 |
| 413 | image_too_large / images_total_too_large | 单张或全部参考图超过限制 |
| 429 | rate_limit_exceeded | 请求频率过高 |
| 502 | model_high_demand / upstream_error | 上游失败，额度自动退回 |
12. 安全建议
- API Key 只保存在服务器环境变量中。
- 不要写入前端 JavaScript、公开仓库或 App 安装包。
- Key 泄露后立即在 API 控制台重新生成。
- 客服微信：MarsXone。