章鱼哥AI接口文档

Nano Banana

异步生成或编辑 Nano Banana 图片,支持多张参考图。

本系列支持的端点
  • 香蕉(异步)POST https://zexapi.com/v1/videos
POSThttps://zexapi.com/v1/videos
鉴权 Authorization: Bearer YOUR_API_KEY

使用 API Key 进行 Bearer 鉴权。JSON 请求设置 Content-Type: application/json;Multipart 请求由客户端自动生成 boundary。

香蕉全系列支持同步与异步。这里使用异步请求格式,参数放在请求体顶层;提交后返回任务 ID,再手动查询结果。

图片生成接口文档

接口地址

POST /v1/videos

功能说明

支持文生图和图生图两种模式的图片生成(与视频生成共用接口,通过 model 参数区分)。

支持的模型

当前在架香蕉系列所有型号均支持同步与异步。同步使用 Gemini 原生 contents / parts 结构,模型名写在 URL;异步使用 /v1/videos,model、aspect_ratio、image_size、images 放在请求体顶层。固定分辨率型号的清晰度跟随型号,不额外传分辨率字段。
model 参数说明
gemini-3-pro-image同步与异步均支持;通过 image_size 选择 1K / 2K / 4K
gemini-3.1-flash-image同步与异步均支持;通过 image_size 选择 1K / 2K / 4K
gemini-nano-banana-2.1Gemini / 香蕉 2.1;同步与异步均支持;通过 image_size 选择 1K / 2K / 4K
nano_banana_2同步与异步均支持;固定 1K,清晰度跟随型号
nano_banana_2-2K同步与异步均支持;固定 2K,清晰度跟随型号
nano_banana_2-4K同步与异步均支持;固定 4K,清晰度跟随型号
nano-banana-2.1同步与异步均支持;固定 1K,清晰度跟随型号
nano-banana-2.1-2K同步与异步均支持;固定 2K,清晰度跟随型号
nano-banana-2.1-4K同步与异步均支持;固定 4K,清晰度跟随型号
nano_banana_pro-1K同步与异步均支持;固定 1K,清晰度跟随型号
nano_banana_pro-2K同步与异步均支持;固定 2K,清晰度跟随型号
nano_banana_pro-4K同步与异步均支持;固定 4K,清晰度跟随型号

请求头

参数名类型必填说明
Authorizationstring是Bearer YOUR_API_KEY
Content-Typestring是application/json

请求参数

参数名类型必填说明
modelstring是模型名称,如 nano_banana_2、nano-banana-2.1、gemini-nano-banana-2.1、nano_banana_pro-1K 等
promptstring是文本提示词,最大长度 10000 字符
aspect_ratiostring否宽高比,可选值:1:1、9:16、16:9、3:4、4:3、3:2、2:3、5:4、4:5、21:9、auto,默认 auto
image_sizestring否输出分辨率档位。参数选档型号支持 1K、2K、4K;不传时使用模型默认值
imagesstring[]否参考图片数组(支持 Base64 或 URL),最多 8 张。传此参数为图生图模式,不传或传空数组为文生图模式

分辨率控制

模型分辨率控制方式
gemini-nano-banana-2.1使用顶层 image_size 字段,可选 1K、2K、4K
nano-banana-2.1 / -2K / -4K分辨率由模型名决定:nano-banana-2.1 为 1K,nano-banana-2.1-2K、nano-banana-2.1-4K 为对应分辨率,不需要传 image_size
nano_banana_pro-1K / -2K / -4K分辨率由模型名后缀决定,不需要传 image_size
nano_banana_2 / -2K / -4Knano_banana_2 使用模型默认分辨率;-2K、-4K 由模型名后缀决定,不需要传 image_size

images 数组元素传法

方式示例
图片 URL"https://example.com/reference.jpg"
Base64"data:image/jpeg;base64,/9j/4AAQSkZJRg..."
注意:传入图片 URL 时,网关会自动将其下载并转为 Base64 后发给上游,请确保 URL 为可公网访问的图片直链。

请求示例

Nano Banana 2.1 文生图(固定分辨率)

nano-banana-2.1 固定输出 1K。需要 2K 或 4K 时,把 model 换成 nano-banana-2.1-2K 或 nano-banana-2.1-4K,不要传 image_size。
curl -X POST https://xxxxx.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2.1-4K",
    "prompt": "高级护肤品广告,透明玻璃瓶放在水面上,柔和棚拍光线",
    "aspect_ratio": "16:9"
  }'

gemini-nano-banana-2.1 文生图(参数选档,4K)

gemini-nano-banana-2.1 用同一个模型名,通过 image_size 选择 1K、2K、4K。
curl -X POST https://xxxxx.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "prompt": "高级护肤品广告,透明玻璃瓶放在水面上,柔和棚拍光线",
    "aspect_ratio": "16:9",
    "image_size": "4K"
  }'
生成 1K 或 2K 图片时,只需将 image_size 改为 "1K" 或 "2K"。

文生图模式

curl -X POST https://xxxxx.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano_banana_2",
    "prompt": "美丽的日出风景,金色的阳光洒在宁静的湖面上,远处是连绵的山脉",
    "aspect_ratio": "16:9"
  }'
请求体(JSON):
{
  "model": "nano_banana_2",
  "prompt": "美丽的日出风景,金色的阳光洒在宁静的湖面上,远处是连绵的山脉",
  "aspect_ratio": "16:9"
}

图生图模式(URL 格式)

curl -X POST https://xxxxx.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano_banana_2",
    "prompt": "将这张图片转换成油画风格",
    "aspect_ratio": "16:9",
    "images": [
      "https://example.com/images/reference1.jpg",
      "https://example.com/images/reference2.png"
    ]
  }'
请求体(JSON):
{
  "model": "nano_banana_2",
  "prompt": "美丽的日出风景,金色的阳光洒在宁静的湖面上,远处是连绵的山脉",
  "aspect_ratio": "16:9",
  "images": [
    "https://xxxxxxxx.jpg",
    "https://xxxxxxxx.png"
  ]
}

图生图模式(Base64 格式)

curl -X POST https://xxxxx.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano_banana_2",
    "prompt": "将这张图片转换成油画风格",
    "aspect_ratio": "16:9",
    "images": [
      "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
      "data:image/png;base64,iVBORw0KGgoAAAANSU..."
    ]
  }'

响应参数

图片任务也走 /v1/videos,object 固定为 "video"。完成态图片地址位于顶层 url 和 image_url,两者值相同。
参数名类型说明
idstring任务 ID,格式:task_nano_xxx 或 task_xxx
objectstring固定值:video(图片任务也是,类型看 model)
modelstring使用的模型名称
statusstring任务状态:queued(排队中)、in_progress(处理中)、completed(已完成)、failed(失败)
progressnumber任务进度,0–100
created_atnumber创建时间戳(秒)
completed_atnumber完成时间戳(秒),仅在 failed 或 completed 状态返回
urlstring生成的图片 URL(仅 completed)
image_urlstring与 url 同值(仅 completed)
errorobject错误信息(仅在 failed 状态返回)
error.messagestring失败原因描述
error.codestring错误码,如 upstream_error

响应示例

任务处理中

{
  "id": "task_xxxxxxxxxxxxx",
  "object": "video",
  "model": "nano_banana_2",
  "status": "in_progress",
  "progress": 10,
  "created_at": 1709876543
}

提交成功(排队中)

{
  "id": "task_xxxxxxxxxxxxx",
  "object": "video",
  "model": "nano_banana_2",
  "status": "queued",
  "progress": 0,
  "created_at": 1709876543
}

任务完成

{
  "id": "task_xxxxxxxxxxxxx",
  "object": "video",
  "model": "nano_banana_2",
  "status": "completed",
  "progress": 100,
  "created_at": 1709876543,
  "completed_at": 1709876600,
  "url": "https://example.com/images/xxx.jpg",
  "image_url": "https://example.com/images/xxx.jpg"
}

任务失败

{
  "id": "task_xxxx",
  "object": "video",
  "model": "nano_banana_2",
  "status": "failed",
  "created_at": 1718123456,
  "completed_at": 1718123456,
  "progress": 100,
  "error": {
    "message": "上游任务失败原因",
    "code": "upstream_error"
  }
}

注意事项

1.
接口复用:图片生成使用 /v1/videos 接口,与视频生成共用;通过 model 参数区分(nano_banana 或 nano-banana 开头为图片生成)。
2.
参数位置:aspect_ratio、image_size、images 均为顶层字段,直接放在请求体根对象中。
3.
参考图片格式:支持 JPEG、PNG、WEBP,单张图片最大 10MB。
4.
参考图片数量:最多 8 张。
5.
参考图片来源:
Base64:需包含完整的 Data URL 前缀(如 data:image/jpeg;base64,)
URL:直接传入可公网访问的图片地址
6.
任务模式:
不传 images 或传空数组 = 文生图
images 含图片(URL 或 Base64)= 图生图
7.
异步处理:接口返回任务 ID 后,轮询 GET /v1/videos/{task_id}。queued / in_progress 继续等;completed 读取顶层 url 或 image_url;failed 读 error.message。
8.
分辨率档位:gemini-nano-banana-2.1 使用 image_size 控制分辨率,支持 1K、2K、4K。nano-banana-2.1 固定为 1K,nano-banana-2.1-2K、nano-banana-2.1-4K 以及 Pro 版(如 nano_banana_pro-2K)由 model 名称决定分辨率,无需额外传尺寸参数。

图生图表单上传

图生图支持 JSON 和表单。JSON 使用 images 数组;表单使用 input_reference,上传多张图片时重复提交同名字段。

图生图(表单格式 — 本地文件)

curl --request POST 'https://zexapi.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --form-string 'model=nano_banana_2' \
  --form-string 'prompt=将这张图片转换成油画风格' \
  --form-string 'aspect_ratio=16:9' \
  --form 'input_reference=@/path/to/reference.png'