> 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.

# BeatAPI 图片 API

> 对比 BeatAPI 图片生成模型、参考图数量、分辨率、宽高比和模型专属请求契约。

# 图片 API

通过稳定的 BeatAPI 模型 ID 创建一个异步图片生成任务。

| 模型                                                            | 输入模式   | 必填字段              | 主要控制项                                                |
| ------------------------------------------------------------- | ------ | ----------------- | ---------------------------------------------------- |
| [`qwen-image-2.1`](/image-api/qwen-image-2-1)                 | 文本、参考图 | `model`, `prompt` | 最多 10 张参考图、1K/2K、透明 PNG/WebP、按输入条件默认增强提示词            |
| [`nano-banana`](/image-api/nano-banana)                       | 文本、参考图 | `model`, `prompt` | 最多 3 张参考图、固定 1K、PNG/JPEG                             |
| [`nano-banana-2`](/image-api/nano-banana-2)                   | 文本、参考图 | `model`, `prompt` | 最多 14 张参考图、1K/2K/4K、PNG/JPEG                         |
| [`nano-banana-2.1`](/image-api/nano-banana-2-1)               | 文本、参考图 | `model`, `prompt` | 字段和价格与 Nano Banana 2 相同。最多 14 张参考图、1K/2K/4K、PNG/JPEG |
| [`nano-banana-2-lite`](/image-api/nano-banana-2-lite)         | 文本、参考图 | `model`, `prompt` | 最多 14 张参考图、固定 1K、PNG/JPEG                            |
| [`nano-banana-pro`](/image-api/nano-banana-pro)               | 文本、参考图 | `model`, `prompt` | 最多 14 张参考图、1K/2K/4K、PNG/JPG                          |
| [`gpt-image-2`](/image-api/gpt-image-2)                       | 文本、参考图 | `model`, `prompt` | 最多 16 张参考图、多种宽高比、最高 4K                               |
| [`gpt-image-2.5-flare`](/image-api/gpt-image-2-5-flare)       | 文本、参考图 | `model`, `prompt` | 最多 16 张参考图、16 种宽高比、最高 4K                             |
| [`gpt-image-2.5-sunburst`](/image-api/gpt-image-2-5-sunburst) | 文本、参考图 | `model`, `prompt` | 最多 16 张参考图、16 种宽高比、最高 4K                             |
| [`seedream-5-pro`](/image-api/seedream-5-pro)                 | 文本、参考图 | `model`, `prompt` | 最多 10 张参考图、1K/2K                                     |
| [`grok-imagine-image-2.0`](/image-api/grok-imagine-image-2-0) | 文本、参考图 | `model`, `prompt` | 最多 5 张参考图，自动选择编辑模式                                   |

每个模型页会列出全部字段、默认值、枚举、组合限制、请求示例、响应和错误行为。

## 查询可用模型

`GET /v1/media/models?media_type=image` 无需鉴权。

```bash
curl "https://api.beatapi.io/v1/media/models?media_type=image"
```

```json
{
  "data": {
    "object": "list",
    "data": [{
      "id": "gpt-image-2",
      "object": "generation_model",
      "name": "GPT Image 2",
      "media_type": "image",
      "input_modes": ["text", "image"]
    }, {
      "id": "gpt-image-2.5-flare",
      "object": "generation_model",
      "name": "GPT Image 2.5 Flare",
      "media_type": "image",
      "input_modes": ["text", "image"]
    }, {
      "id": "gpt-image-2.5-sunburst",
      "object": "generation_model",
      "name": "GPT Image 2.5 Sunburst",
      "media_type": "image",
      "input_modes": ["text", "image"]
    }]
  }
}
```

`id` 是稳定公开模型别名；`input_modes` 可能包含 `text`、`image`、`frames` 或 `reference`。内部供应商路由不属于公开契约。

## 通用创建契约

`POST /v1/images/tasks`

| 请求头               | 类型     | 必填     | 规则                         |
| ----------------- | ------ | ------ | -------------------------- |
| `Authorization`   | string | 是      | `Bearer <BEATAPI_API_KEY>` |
| `Content-Type`    | string | 是      | `application/json`         |
| `Idempotency-Key` | string | 否，建议使用 | 最长 255 字符；每个逻辑创建使用一个键      |

请求体必须且只能匹配一个模型参数结构；`model` 是判别字段，未知字段会被拒绝。

```bash
curl https://api.beatapi.io/v1/images/tasks \
  -X POST \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Idempotency-Key: image-gpt-image-2-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "暖色石材展台上的编辑风格产品摄影。",
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }'
```

成功请求返回 `201 Created` 和 `data.id`。每 5–10 秒轮询 `GET /v1/tasks/{task_id}`，成功结果位于 `data.output.media[]` 和 `data.output.r2_url`。相同幂等请求会返回已接受任务；同一键配不同请求体返回 `409 idempotency_conflict`。

## 通用错误

| HTTP  | 常见错误码                                                                                            | 客户端动作                                |
| ----- | ------------------------------------------------------------------------------------------------ | ------------------------------------ |
| `400` | `bad_request`                                                                                    | 修正字段、取值、组合、数量或媒体 URL                 |
| `400` | `content_policy_violation`                                                                       | 修改提示词或素材，不要原样重发                      |
| `401` | `missing_api_key` / `invalid_api_key`                                                            | 补上 Bearer API 密钥，或更换错误、过期、停用、额度用尽的密钥 |
| `402` | `insufficient_credits`                                                                           | 充值后再创建任务                             |
| `403` | `forbidden`                                                                                      | 密钥或账户无权执行，例如免费额度不能调用该模型              |
| `409` | `idempotency_conflict`                                                                           | 仅用完全相同请求体复用该键                        |
| `429` | `rate_limit_exceeded`                                                                            | 遵守 `Retry-After`                     |
| `500` | `internal_error`                                                                                 | 退避后重试一次                              |
| `503` | `processing_unavailable` / `processing_timeout` / `processing_failed` / `result_transfer_failed` | 退避重试，未扣费                             |

错误响应包含 `error.code`、英文的 `error.message`、`error.retryable`、`error.request_id`，`429` 时另带 `error.retry_after_seconds`。任务被接受后才失败的，查询依然返回 `200`，原因见 `data.error_code`；全部错误码与重试规则见[错误码](/errors)。模型页面是最终生产请求契约。