> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# Nano Banana 2.1

> Nano Banana 2 的后继型号：通过文字或最多 14 张公网 HTTPS 参考图生成或编辑图片，支持 1K、2K 和 4K 输出。

`POST https://api.beatapi.io/v1/images/tasks`

Nano Banana 2 的后继型号：通过文字或最多 14 张公网 HTTPS 参考图生成或编辑图片，支持 1K、2K 和 4K 输出。

### 支持的生成方式

| 生成方式  | 必填参数                        | 使用规则                                        |
| ----- | --------------------------- | ------------------------------------------- |
| 文生图   | `model`, `prompt`           | 不要传入 `images`。                              |
| 参考图生成 | `model`, `prompt`, `images` | 传入 1–14 个公网 HTTPS 图片 URL，仅支持 PNG、JPEG、WebP。 |

**异步任务流程**

创建任务后保存 `data.id`，每 5–10 秒调用 `GET /v1/tasks/{task_id}` 查询状态。`status` 为 `succeeded` 时读取 `data.output.media`，为 `failed` 时读取 `data.error_code` 和 `data.error_message`，随后按[错误与重试策略](/quick-guide#errors-and-retry-policy)处理。

**使用本地文件**

请先[上传本地输入](/quick-guide#upload-an-input-file)，再将返回的 `data.url` 填入请求。

## 鉴权

`Authorization`   `string`   **必填**

在 `Authorization` 请求头中以 Bearer 令牌发送服务端 API 密钥，可在[控制台](https://beatapi.io/dashboard)创建。

```
Authorization: Bearer <BEATAPI_API_KEY>
```

永久 API 密钥只能保存在可信服务端，不能写入浏览器、移动端、公开脚本、日志或截图。请求体必须使用 `Content-Type: application/json`。建议为每个逻辑创建请求设置唯一的 `Idempotency-Key`，只有完全相同的请求体才能安全复用原键。

## 请求体

字段名、类型和枚举值保留英文原样，用途和限制用中文说明。

`model`   `string`   **必填**

稳定的公开模型 ID，必须使用当前页面列出的值。

**取值与默认值:** 固定值 `nano-banana-2.1`

---

`prompt`   `string`   **必填**

描述生成、编辑或分析目标的提示词。

**取值与默认值:** 长度 1–5000 字符

---

`images`   `string[]`   **选填**

按当前模型或工作流要求排序的公网 HTTPS 图片 URL 列表。

**取值与默认值:** 1–14 项

---

`aspect_ratio`   `enum<string>`   **选填**

输出素材的宽高比。

**取值与默认值:** 可选值 `1:1`、`1:4`、`1:8`、`2:3`、`3:2`、`3:4`、`4:1`、`4:3`、`4:5`、`5:4`、`8:1`、`9:16`、`16:9`、`21:9`、`auto`；默认值 `1:1`

---

`resolution`   `enum<string>`   **选填**

输出素材的分辨率或质量档位。

**取值与默认值:** 可选值 `1K`、`2K`、`4K`；默认值 `1K`

---

`output_format`   `enum<string>`   **选填**

输出图片的文件格式。

**取值与默认值:** 可选值 `png`、`jpeg`；默认值 `png`

## 请求示例

### 文生图

```bash
curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "nano-banana-2.1",
  "prompt": "Editorial campaign image with crisp product typography.",
  "aspect_ratio": "4:5",
  "resolution": "2K",
  "output_format": "png"
}'
```

### 参考图生成

```bash
curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "nano-banana-2.1",
  "prompt": "Keep the product identity and create a polished campaign variation.",
  "images": [
    "https://media.beatapi.io/samples/smart-bottle.png"
  ],
  "aspect_ratio": "4:5",
  "resolution": "2K",
  "output_format": "png"
}'
```

## 响应

成功请求返回 HTTP `201`，响应体如下。

```json
{
  "data": {
    "id": "task_8K2qA",
    "object": "task",
    "task_kind": "image",
    "capability_id": "nano-banana-2.1",
    "capability_version": null,
    "media_type": "image",
    "model": "nano-banana-2.1",
    "status": "queued",
    "stage": "queued",
    "created_at": 1782210000,
    "updated_at": 1782210000,
    "completed_at": null,
    "output": null,
    "usage": {
      "credits_reserved": 0.04,
      "credits_charged": 0.04,
      "credits_settled": 0,
      "credits_refunded": 0
    },
    "request_id": "req_abc123",
    "error_code": null,
    "error_message": null
  }
}
```

## 下一步

保存接受响应中的 `data.id`，每 5–10 秒轮询 `GET /v1/tasks/{task_id}`。任务成功后从 `data.output.media` 读取托管结果。

## 错误

| 状态码   | 含义与处理方式                                                                                                                                                                                                                  |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400` | JSON 格式错误，或字段、取值、参数组合不被接受（`bad_request`，错误信息会点名字段）；输入未通过内容审核时为 `content_policy_violation`。修正后再请求，原样重试仍会失败。                                                                                                               |
| `401` | 未提供 API 密钥（`missing_api_key`），或密钥错误、已过期、已停用或额度已用尽（`invalid_api_key`，错误信息会说明是哪一种）。不要原样重试。                                                                                                                                 |
| `402` | 余额不足（`insufficient_credits`）：账户余额为零或低于本次请求的价格。充值后再请求。                                                                                                                                                                    |
| `403` | 密钥或账户无权执行该调用（`forbidden`），例如免费额度不能使用该模型（充值即可解锁）、请求来源不在密钥的 IP 白名单内，或模型不在密钥的分组里。不要原样重试。                                                                                                                                    |
| `409` | 幂等键已用于其他请求体，或使用该键的首个请求仍在处理中（`idempotency_conflict`）。只对完全相同的请求复用原键。                                                                                                                                                       |
| `429` | 请求过于频繁（`rate_limit_exceeded`，含免费模型限额）或同时处理中的任务过多（`user_concurrency_exceeded`）。按 `Retry-After`（也在 `error.retry_after_seconds`）等待后重试。                                                                                      |
| `500` | 内部异常（`internal_error`），可以重试；持续出现时请保留 `request_id` 联系支持。                                                                                                                                                                  |
| `503` | 请求未能完成（`processing_unavailable`、`processing_timeout`、`processing_failed` 或 `result_transfer_failed`），未扣费，可退避重试；已知等待时间时会返回 `Retry-After`。实时接口未启用时为 `realtime_disabled`（不可重试），容量不足时为 `realtime_capacity_unavailable`（可重试）。 |