> ## 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 输出及 10 种宽高比，提供官方版与 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)为准。

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

<RequestExample>
  ```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());
  ```
</RequestExample>

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

## 请求头

<ParamField header="Authorization" type="string" required>
  Bearer 认证，格式为 `Bearer <token>`，其中 `<token>` 为你的 APIMart API Key。
</ParamField>

## 请求参数

<ParamField body="model" type="string" required>
  模型 ID：`gemini-nano-banana-2.1` 或 `gemini-nano-banana-2.1-ext`。
</ParamField>

<ParamField body="prompt" type="string" required>
  图像生成或编辑的文本描述，支持中文和英文。
</ParamField>

<ParamField body="size" type="string" default="auto">
  输出宽高比。支持 `1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`，兼容 `16x9` 形式的写法。

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

  不支持 `1:4`、`4:1`、`1:8`、`8:1` 等其他比例，使用不支持的比例会导致任务失败并退款。
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  输出分辨率档位：`1K`、`2K` 或 `4K`，兼容小写，同时影响计费。

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

<ParamField body="n" type="integer" default="1">
  生成图片数量：官方版支持 1–4 张，Ext 版仅支持 1 张。

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

<ParamField body="image_urls" type="string[]">
  参考图列表。不传为文生图，传入则为图生图或图像编辑。每项支持：

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

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

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

<ParamField body="official_fallback" type="boolean" default="false">
  仅适用于 `gemini-nano-banana-2.1-ext`。开启后，Ext 版失败时尝试使用官方版完成任务。

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

<ParamField body="webhook" type="string">
  任务结束后的回调地址，详见 [任务回调](/cn/api-reference/tasks/webhook)。
</ParamField>

## 输出尺寸参考

| 宽高比 | 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
}
```

## 提交响应

<ResponseField name="code" type="integer">
  响应状态码，成功为 `200`。
</ResponseField>

<ResponseField name="data" type="array">
  任务提交结果。`status` 为 `submitted`，`task_id` 用于查询任务状态和结果，不是最终图片地址。
</ResponseField>

## 查询任务结果

```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` 支持的 10 种比例或 `auto` |
| 任务失败：Ext 版请求多张 | 将 `n` 改为 1，或使用官方版 |
| 任务失败：内容安全拦截 | 修改提示词或参考图后重试 |
| 任务失败：参考图下载失败 | 确认图片 URL 可以从公网访问 |

<Warning>
  Nano banana 2.1 与 Gemini 3.1 Flash Image 是不同模型，模型名不能作为别名互换。从后者迁移时，请移除 `0.5K` 分辨率以及 `1:4`、`4:1`、`1:8`、`8:1` 四种极端比例。
</Warning>


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