AI 图像生成 API
一个平台 API Key,同时支持平台原生任务接口、OpenAI Images 和 Google Gemini / Nano Banana 官方请求格式。可用模型和价格以页面实时列表为准;视觉分析模型不会出现在生图 API 文档中。
/openapi/v1
平台任务接口,提交任务后通过任务状态接口获取结果;模型和积分以“平台原生模型列表”为准。
/v1 /v1beta
沿用 OpenAI Images 或 Gemini 的请求格式;可用名称请分别查看下方对应协议的模型列表。
认证方式
所有 API 请求需在 HTTP Header 中携带 API Key:
Authorization: Bearer sk-nb-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
在 个人中心 的「API 接入」区块创建并管理您的 API Key。Key 只在创建时完整显示一次,请妥善保存。
快速开始
以下示例展示如何生成一张图片并轮询结果:
# 1. 提交生图任务
curl -X POST /openapi/v1/images/generate \
-H "Authorization: Bearer sk-nb-YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "a cute cat sitting on a cloud"}'
# 2. 轮询任务状态(替换 TASK_ID)
curl /openapi/v1/images/TASK_ID \
-H "Authorization: Bearer sk-nb-YOUR_KEY"
官方协议可用模型
下面只列出官方协议请求中可以填写的模型名。选择您使用的协议后,直接复制表格中的模型名即可。
OpenAI Images(/v1)
| 模型名(直接复制) | 积分/张 | 支持清晰度 | 调用接口 |
|---|---|---|---|
| 加载中... | |||
使用模型名调用 /v1/images/generations(文生图)或 /v1/images/edits(图生图)。
Gemini / Nano Banana(/v1beta)
| 模型名(直接复制) | 积分/张 | 支持清晰度 | 调用接口 |
|---|---|---|---|
| 加载中... | |||
使用模型名调用 /v1beta/models/{model}:generateContent。
OpenAI Images 官方协议
把第三方 OpenAI Images SDK 的 Base URL 设置为当前站点的 /v1,使用平台 API Key 即可。
curl -X POST "/v1/images/generations" \
-H "Authorization: Bearer sk-nb-你的平台Key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "一只橘猫坐在窗边,柔和晨光",
"size": "1024x1024",
"quality": "medium",
"response_format": "b64_json"
}'curl -X POST "/v1/images/edits" \ -H "Authorization: Bearer sk-nb-你的平台Key" \ -F "image=@/path/to/reference.png" \ -F "prompt=把这张图片变成水彩插画" \ -F "model=gpt-image-2" \ -F "response_format=url"
响应保持 OpenAI 的 data[0].b64_json 或 data[0].url 结构。
Google Gemini / Nano Banana 官方协议
把 Gemini 客户端 Base URL 设置为当前站点的 /v1beta,在路径中填写模型公开名。
curl -X POST "/v1beta/models/gemini-2.5-flash-image:generateContent" \
-H "x-goog-api-key: sk-nb-你的平台Key" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"role":"user","parts":[{"text":"生成一张夜晚霓虹城市海报"}]}],
"generationConfig": {
"responseModalities": ["IMAGE"],
"imageConfig": {"aspectRatio":"16:9","imageSize":"1K"}
}
}'图生图时,在同一个 contents.parts 中加入 inlineData。响应图片位于 candidates[0].content.parts[].inlineData.data。
/openapi/v1,先提交任务,再查询任务状态。
文生图
提交文生图任务,立即返回 task_id,通过「查询任务状态」接口轮询结果。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
prompt | string | 必填 | 正向提示词,最长 2000 字符 |
model | string | 可选 | 平台原生公开模型名,见下方模型速查表;不传则使用默认模型 |
negative_prompt | string | 可选 | 反向提示词,最长 500 字符 |
aspect_ratio | string | 可选 | 宽高比,如 1:1、16:9、9:16 |
image_size | string | 可选 | 图片尺寸,如 1024x1024 |
style | string | 可选 | 风格标识 |
seed | integer | 可选 | 随机种子,用于复现结果 |
响应示例
{
"success": true,
"task_id": "550e8400-e29b-41d4-a716-446655440000",
"credits_remaining": 42
}
平台原生模型速查表
这是后台已开放给平台原生 API 的模型表。调用 /openapi/v1 时,直接复制“公开模型名(传参用)”这一列;官方协议名称请看后面的兼容名称表。
代码示例
curl -X POST /openapi/v1/images/generate \
-H "Authorization: Bearer sk-nb-YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "a futuristic city at night, neon lights",
"model": "nano-banana-pro",
"aspect_ratio": "16:9"
}'
图生图
以参考图为基础进行图片编辑或风格转换,同样返回 task_id,通过「查询任务状态」接口轮询结果。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
prompt | string | 必填 | 描述目标效果的提示词,最长 2000 字符 |
reference_image_url | string | 必填 | 参考图片的 URL 地址(单张) |
reference_image_urls | array | 可选 | 多张参考图 URL 数组,与 reference_image_url 二选一 |
model | string | 可选 | 平台原生公开模型名,见模型列表;不传则使用默认模型 |
negative_prompt | string | 可选 | 反向提示词,最长 500 字符 |
aspect_ratio | string | 可选 | 输出宽高比,如 1:1、16:9 |
image_size | string | 可选 | 清晰度,Nano Banana 系列传 1K/2K/4K,GPT Image 系列传 low/medium/high |
style | string | 可选 | 风格标识 |
响应示例
{
"success": true,
"task_id": "550e8400-e29b-41d4-a716-446655440000",
"credits_remaining": 36
}
代码示例
curl -X POST /openapi/v1/images/edit \
-H "Authorization: Bearer sk-nb-YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "将图片转换为水彩画风格",
"reference_image_url": "https://example.com/your-image.jpg",
"model": "nano-banana-pro"
}'
查询任务状态
轮询生图任务的状态。建议每 2 秒轮询一次,任务通常在 10-30 秒内完成。
响应示例(生成中)
{ "status": "generating" }
响应示例(完成)
{
"status": "completed",
"image": {
"id": 1234,
"url": "https://example.com/uploads/xxx.png",
"prompt": "a cute cat sitting on a cloud",
"model": "nano-banana-pro"
}
}
响应示例(失败)
{ "status": "failed", "error": "模型调用超时" }
status 枚举值
| 值 | 说明 |
|---|---|
pending | 任务已提交,等待处理 |
generating | 正在生成中 |
completed | 生成完成,image.url 为结果图片地址 |
failed | 生成失败,积分已退还,error 为失败原因 |
模型列表
获取平台原生 API 当前可用的模型列表。不传 model 参数时使用默认模型。官方协议请分别调用 /v1/models 或 /v1beta/models。名称请原样复制,不要自行添加或删除数字后缀。
后台已开放的模型(平台原生调用)
清晰度参数说明
不同系列模型的清晰度参数格式不同,通过 image_size 字段传入:
| 模型系列 | image_size 可选值 | 说明 |
|---|---|---|
| Nano Banana 系列 | 1K 2K 4K |
对应约 1024、2048、4096 像素,不同模型支持的档位见卡片标签 |
| GPT Image 系列 | low medium high |
对应低/中/高画质,影响生成细节和耗时 |
响应格式
{
"success": true,
"models": [
{
"model_id": "nano-banana-pro",
"display_name": "Nano Banana Pro",
"credit_cost": 6,
"supported_sizes": "1K,2K,4K",
"description": "高质量文生图模型"
}
]
}
积分余额
查询当前 API Key 关联账户的积分余额。
响应示例
{ "success": true, "credits": 88 }
错误码
所有错误响应均包含 error(错误描述)和 code(机器可读错误码)字段。
| HTTP 状态码 | code | 说明 |
|---|---|---|
| 401 | MISSING_API_KEY | 未提供 Authorization Header |
| 401 | INVALID_API_KEY_FORMAT | Key 格式不正确,需以 sk-nb- 开头 |
| 401 | INVALID_API_KEY | Key 不存在或已被删除 |
| 403 | API_KEY_DISABLED | Key 已被禁用 |
| 403 | API_KEY_EXPIRED | Key 已过期 |
| 403 | USER_BANNED | 账号已被封禁 |
| 400 | MISSING_PROMPT | 未提供 prompt 参数 |
| 402 | — | 积分不足,请充值后重试 |
| 429 | RATE_LIMIT_EXCEEDED | 请求频率超过限制(默认 60 次/分钟) |
| 429 | CONCURRENT_LIMIT_EXCEEDED | 并发任务数超过上限(最多 3 个) |
| 404 | TASK_NOT_FOUND | 任务不存在或已过期(30 分钟后清除) |
| 500 | SERVER_ERROR | 服务器内部错误 |