> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Nano banana 2.1 图像生成

> 支持文生图、参考图编辑、1K / 2K / 4K 输出及 14 种宽高比，提供官方版与 Ext 版。

## 模型选择

| 模型 ID | 计费方式 | 单次出图张数 | 参考图大小 |
| - | - | - | - |
| `gemini-nano-banana-2.1` | 按实际 token 用量 | 1–4 张 | 单张不超过 20MB |
| `gemini-nano-banana-2.1-ext` | 按分辨率档位、按张计费 | 仅 1 张 | 单张不超过 20MB，合计不超过 50MB |

两个模型的出图尺寸和画质一致。需要一次生成多张图片请选择官方版；需要按张估算费用可选择 Ext 版。实际价格以[模型定价](https://apimart.ai/pricing)为准。

> [!NOTE]
>
> 本接口为异步接口。提交成功后返回 `task_id`，请通过 [任务查询](https://docs.apimart.ai/cn/api-reference/tasks/status.md) 获取状态和图片。建议每 3–5 秒轮询一次，整体等待超时设置为至少 3 分钟。

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gemini-nano-banana-2.1",
    "prompt": "一只橘猫坐在木桌上，旁边一杯咖啡，清晨柔光，写实摄影",
    "size": "16:9",
    "resolution": "2K",
    "n": 1
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "gemini-nano-banana-2.1",
        "prompt": "一只橘猫坐在木桌上，旁边一杯咖啡，清晨柔光，写实摄影",
        "size": "16:9",
        "resolution": "2K",
        "n": 1
    }
)
print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gemini-nano-banana-2.1",
    prompt: "一只橘猫坐在木桌上，旁边一杯咖啡，清晨柔光，写实摄影",
    size: "16:9",
    resolution: "2K",
    n: 1
  })
});
console.log(await response.json());
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K..."
    }
  ]
}
```

## 请求头

**Authorization** `string` *required*

Bearer 认证，格式为 `Bearer <token>`，其中 `<token>` 为你的 APIMart API Key。

## 请求参数

**model** `string` *required*

模型 ID：`gemini-nano-banana-2.1` 或 `gemini-nano-banana-2.1-ext`。

**prompt** `string` *required*

图像生成或编辑的文本描述，支持中文和英文。

**size** `string` (default: auto)

输出宽高比。支持 `1:4`、`4:1`、`1:8`、`8:1`、`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`，兼容 `16x9` 形式的写法。

不传或传 `auto` 时由模型决定；图生图会跟随参考图比例。

上述 14 种比例均适用于官方版和 Ext 版，并支持 `1K`、`2K`、`4K` 三个分辨率档位。

**resolution** `string` (default: 1K)

输出分辨率档位：`1K`、`2K` 或 `4K`，兼容小写，同时影响计费。

不支持 `0.5K` 或 `512`，提交时会返回 HTTP 400。其他无法识别的值（如 `3K`）会按 `1K` 生成和计费，建议只使用上述支持的值。

**n** `integer` (default: 1)

生成图片数量：官方版支持 1–4 张，Ext 版仅支持 1 张。

大于 4 时提交直接返回 HTTP 400；Ext 版传入 2–4 时任务会在执行阶段失败并全额退款。需要多张时请分别提交 Ext 任务，或使用官方版。

**image\_urls** `string[]`

参考图列表。不传为文生图，传入则为图生图或图像编辑。每项支持：

* 公网可访问的 HTTP(S) 图片 URL。
* Base64 Data URL，例如 `data:image/png;base64,...`。

建议使用 PNG、JPEG 或 WEBP。官方版单张不超过 20MB；Ext 版单张不超过 20MB，所有参考图合计不超过 50MB。

平台未设置固定的参考图张数上限，但不代表可以无限上传：超出模型支持范围时任务可能失败并退款，参考图越多通常耗时越长。

**official\_fallback** `boolean` (default: false)

仅适用于 `gemini-nano-banana-2.1-ext`。开启后，Ext 版失败时尝试使用官方版完成任务。

**实际使用官方版完成时，改为按官方版的实际 token 用量计费，不再按 Ext 版的按张价格计费。**

**webhook** `string`

任务结束后的回调地址，详见 [任务回调](https://docs.apimart.ai/cn/api-reference/tasks/webhook.md)。

## 输出尺寸参考

| 宽高比 | 1K | 2K | 4K |
| - | - | - | - |
| 1:1 | 1024×1024 | 2048×2048 | 4096×4096 |
| 2:3 | 848×1264 | 1696×2528 | 3392×5056 |
| 3:2 | 1264×848 | 2528×1696 | 5056×3392 |
| 3:4 | 896×1200 | 1792×2400 | 3584×4800 |
| 4:3 | 1200×896 | 2400×1792 | 4800×3584 |
| 4:5 | 928×1152 | 1856×2304 | 3712×4608 |
| 5:4 | 1152×928 | 2304×1856 | 4608×3712 |
| 9:16 | 768×1376 | 1536×2752 | 3072×5504 |
| 16:9 | 1376×768 | 2752×1536 | 5504×3072 |
| 21:9 | 1584×672 | 3168×1344 | 6336×2688 |

上述尺寸包含实测值及系列尺寸参考值，并非所有组合均已实测，实际像素尺寸以返回图片为准。

## 编辑参考图

```json theme={null}
{
  "model": "gemini-nano-banana-2.1-ext",
  "prompt": "给画面里的猫戴上一顶红色毛线帽，其余保持不变",
  "image_urls": ["https://example.com/cat.jpg"],
  "resolution": "1K"
}
```

请将示例 URL 替换为实际可访问的图片地址。不传 `size` 时输出跟随参考图比例。

## 批量生成（仅官方版）

```json theme={null}
{
  "model": "gemini-nano-banana-2.1",
  "prompt": "赛博朋克风格的城市夜景，霓虹灯，雨后街道",
  "size": "16:9",
  "resolution": "2K",
  "n": 4
}
```

## 提交响应

**code** `integer`

响应状态码，成功为 `200`。

**data** `array`

任务提交结果。`status` 为 `submitted`，`task_id` 用于查询任务状态和结果，不是最终图片地址。

## 查询任务结果

```bash theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01K... \
  --header 'Authorization: Bearer <token>'
```

成功响应示例（图片 URL 为占位示例）：

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": ["https://example.com/generated-image.png"],
          "expires_at": 1791417625
        }
      ]
    }
  }
}
```

| 任务状态 | 含义 |
| - | - |
| `pending` | 排队中 |
| `processing` | 生成中 |
| `completed` | 成功，从 `data.result.images[0].url` 读取图片链接数组 |
| `failed` | 失败，从 `data.error.message` 读取原因；全额退款，`data.cost` 为 0 |

所有成品图片链接均在 `data.result.images[0].url` 数组中，生成 4 张时此数组包含 4 个链接。平台仅返回成品图，`n=1` 对应 1 张成品图。

链接有效期为任务完成后 24 小时，以 `expires_at` 为准，请及时下载转存。输出为 PNG 或 JPEG，以实际文件内容为准。查询结果中的 `data.cost` 为最终扣费金额（美元）。

## 计费说明

* **官方版**：按实际输入和输出 token 用量计费，提示词和参考图计入输入用量。提交时按分辨率档位和 `n` 预扣，完成后按实际用量多退少补。
* **Ext 版**：按分辨率档位单价 × 实际出图张数计费，宽高比不影响档位。开启 `official_fallback` 且实际使用官方版时，改按官方版 token 计费。
* 具体单价以[模型定价](https://apimart.ai/pricing)为准。提交阶段直接拒绝的请求不创建任务、不扣费；任务失败全额退款。

## 常见错误

| 情况 | 处理方式 |
| - | - |
| HTTP 400 | 检查是否传入 `0.5K` / `512`、`n` 大于 4 或参考图超过单张大小上限 |
| HTTP 401 | 检查 API Key |
| HTTP 402 | 检查余额是否足以覆盖预扣费用 |
| HTTP 429 | 触发限流，请退避后重试 |
| 任务失败：不支持的宽高比 | 改用 `size` 支持的 14 种比例或 `auto` |
| 任务失败：Ext 版请求多张 | 将 `n` 改为 1，或使用官方版 |
| 任务失败：内容安全拦截 | 修改提示词或参考图后重试 |
| 任务失败：参考图下载失败 | 确认图片 URL 可以从公网访问 |

> [!WARNING]
>
> Nano banana 2.1 与 Gemini 3.1 Flash Image 是不同模型，模型名不能作为别名互换。从后者迁移时，请移除不支持的 `0.5K` 分辨率。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.