Nano Banana 2 1

根据文字生成图片，或使用最多 14 张参考图进行图片编辑。支持 1K、2K、4K 分辨率和 JPG、PNG 输出格式。

模型

模型名称	输出	宽高比
`nano-banana-2-1`	图片 (JPG/PNG)	auto, 1:1, 2:3, 3:2, 1:4, 4:1, 3:4, 4:3, 4:5, 5:4, 1:8, 8:1, 9:16, 16:9, 21:9

定价

按输出分辨率计费，每次生成一张图片：

分辨率	积分	价格
1K（默认）	6 积分	$0.03
2K	10 积分	$0.05
4K	16 积分	$0.08

如账户配置了价格倍率，实际扣费将应用该倍率，积分四舍五入保留两位小数。参考图不额外收费。

创建任务

curl -X POST https://api.aivideoapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2-1",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "一只戴着太阳镜的可爱猫咪坐在沙滩上，数字艺术风格",
      "resolution": "1K",
      "aspect_ratio": "auto",
      "output_format": "jpg"
    }
  }'

请求体

字段	类型	必填	说明
`model`	string	是	固定为 `nano-banana-2-1`
`input`	object	是	生成参数，见下表
`callback_url`	string	否	接收任务完成或失败通知的回调地址

Input 参数

字段	类型	必填	说明
`prompt`	string	是	图片描述或编辑指令，最多 20,000 个字符
`image_urls`	string[]	否	最多 14 张可公开访问的图片 URL；支持 JPEG、PNG、WebP，每张不超过 30 MB
`aspect_ratio`	string	否	上表列出的任一宽高比，默认 `auto`
`resolution`	string	否	`1K`（默认）、`2K` 或 `4K`
`output_format`	string	否	`jpg`（默认）或 `png`

Playground 本地文件上传限制为每张 10 MB。通过 API 提交公开图片 URL 时，单张图片上限为上述 30 MB。

图片编辑示例

{
  "model": "nano-banana-2-1",
  "input": {
    "prompt": "将外套替换为黄色雨衣。保留人物身份、姿势、构图和光线。",
    "image_urls": ["https://example.com/portrait.jpg"],
    "resolution": "2K",
    "aspect_ratio": "auto",
    "output_format": "png"
  }
}

响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "397ce9f2-c04e-4244-ac33-3af19a7cc297"
  }
}

查询任务

curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk-your-api-key"

状态流转：pending → processing → completed 或 failed。轮询直到任务进入最终状态，也可以使用 callback_url 接收结果。

任务完成

{
  "id": "397ce9f2-c04e-4244-ac33-3af19a7cc297",
  "status": "completed",
  "model": "nano-banana-2-1",
  "created_at": 1791421200,
  "completed_at": 1791421220,
  "output": {
    "urls": ["https://file.aivideoapi.ai/images/example.png"]
  }
}

从 output.urls 中读取生成图片。

任务失败

{
  "id": "57c8772c-f834-46f3-9b7d-81f92e104050",
  "status": "failed",
  "model": "nano-banana-2-1",
  "created_at": 1791421200,
  "error": {
    "code": "upstream_error",
    "message": "Image generation failed"
  }
}

任务失败时退还预扣积分，已完成任务保留正常扣费。重复通知不会导致重复扣费或重复退款。

回调

创建任务时传入 callback_url，任务完成或失败后将向该地址发送 POST 通知，通知格式与查询任务的响应一致。

常见错误码

请求失败时，API 返回 JSON 格式的错误响应：

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

错误码一览

HTTP 状态码	错误码	类型	说明
400	`invalid_request`	invalid_request_error	缺少必填参数或参数无效
401	`invalid_api_key`	authentication_error	API Key 无效、已禁用或已删除
402	`insufficient_credits`	billing_error	积分余额不足，请充值
403	`ip_not_allowed`	permission_error	请求 IP 不在 Key 的白名单中
404	`model_not_found`	invalid_request_error	模型不存在或已停用
404	`task_not_found`	invalid_request_error	任务 ID 不存在
429	`rate_limit_exceeded`	rate_limit_error	请求过于频繁，请降低频率
429	`spend_limit_exceeded`	billing_error	达到 Key 的消费限额（每小时/每天/总量）
500	`internal_error`	api_error	服务器内部错误
503	`upstream_error`	upstream_error	上游 AI 服务返回错误

常见场景

invalid_request (400)

缺少必填字段或参数格式错误时返回。

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

积分不足。可通过 GET /v1/credits 查询余额，前往 Dashboard > Billing 充值。

invalid_api_key (401)

可能原因：

Key 不以 sk- 开头
Key 已被禁用或删除
用户账户已被封禁

upstream_error (503)

上游 AI 服务返回错误，可能原因：

输入内容包含敏感或违规信息
上游服务暂时不可用
请求参数不被上游支持

因上游错误导致任务失败时，预扣积分会自动退还。