> 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로 비동기 이미지 생성 작업을 하나 만듭니다.

모델 이름으로 과금 방식을 알 수 있습니다. `-beta`는 이미지당 고정 가격의 저가 라인입니다. 공식 버전은 토큰 단위로 과금되며, GPT Image 2.6은 접미사 없는 이름(예: `gpt-image-2.6-flare`), 이전 계열은 `-std`(예: `gpt-image-2-std`)를 씁니다. `quality` 옵션은 공식 GPT Image 버전에서만 받습니다.

| 모델                                                                      | 입력 모드       | 필수 필드             | 주요 설정                                                                       |
| ----------------------------------------------------------------------- | ----------- | ----------------- | --------------------------------------------------------------------------- |
| [`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-std`](/image-api/nano-banana-2-std)                     | 텍스트, 참조 이미지 | `model`, `prompt` | `nano-banana-2` 토큰 단위 과금, 비동기 전용                                            |
| [`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-2-lite-std`](/image-api/nano-banana-2-lite-std)           | 텍스트, 참조 이미지 | `model`, `prompt` | `nano-banana-2-lite` 토큰 단위 과금, 비동기 전용                                       |
| [`nano-banana-pro`](/image-api/nano-banana-pro)                         | 텍스트, 참조 이미지 | `model`, `prompt` | 참조 이미지 최대 14장, 1K/2K/4K, PNG/JPG 출력                                         |
| [`nano-banana-pro-std`](/image-api/nano-banana-pro-std)                 | 텍스트, 참조 이미지 | `model`, `prompt` | `nano-banana-pro` 토큰 단위 과금, 비동기 전용                                          |
| [`gpt-image-2`](/image-api/gpt-image-2)                                 | 텍스트, 참조 이미지 | `model`, `prompt` | 참조 이미지 최대 16장, 다양한 화면비, 최대 4K                                               |
| [`gpt-image-2-std`](/image-api/gpt-image-2-std)                         | 텍스트, 참조 이미지 | `model`, `prompt` | `gpt-image-2` 토큰 단위 과금, `quality` 지원, 비동기 전용                                |
| [`gpt-image-2.5-flare`](/image-api/gpt-image-2-5-flare)                 | 텍스트, 참조 이미지 | `model`, `prompt` | 참조 이미지 최대 16장, 화면비 16종, 최대 4K                                               |
| [`gpt-image-2.5-flare-std`](/image-api/gpt-image-2-5-flare-std)         | 텍스트, 참조 이미지 | `model`, `prompt` | `gpt-image-2.5-flare` 토큰 단위 과금, `quality` 지원, 비동기 전용                        |
| [`gpt-image-2.5-sunburst`](/image-api/gpt-image-2-5-sunburst)           | 텍스트, 참조 이미지 | `model`, `prompt` | 참조 이미지 최대 16장, 화면비 16종, 최대 4K                                               |
| [`gpt-image-2.5-sunburst-std`](/image-api/gpt-image-2-5-sunburst-std)   | 텍스트, 참조 이미지 | `model`, `prompt` | `gpt-image-2.5-sunburst` 토큰 단위 과금, `quality` 지원, 비동기 전용                     |
| [`gpt-image-2.6-flare`](/image-api/gpt-image-2-6-flare)                 | 텍스트, 참조 이미지 | `model`, `prompt` | 토큰 단위 과금, `quality` 지원. 참조 이미지 최대 16장, 최대 4K. 프레임 `size`를 고를 수 있는 GIF 애니메이션 |
| [`gpt-image-2.6-sunburst`](/image-api/gpt-image-2-6-sunburst)           | 텍스트, 참조 이미지 | `model`, `prompt` | 토큰 단위 과금, `quality` 지원. 참조 이미지 최대 16장, 최대 4K. 프레임 `size`를 고를 수 있는 GIF 애니메이션 |
| [`gpt-image-2.6-flare-beta`](/image-api/gpt-image-2-6-flare-beta)       | 텍스트, 참조 이미지 | `model`, `prompt` | 고정 가격. 참조 이미지 최대 16장, 화면비 16종, 최대 4K. 프롬프트로 만드는 GIF 애니메이션                   |
| [`gpt-image-2.6-sunburst-beta`](/image-api/gpt-image-2-6-sunburst-beta) | 텍스트, 참조 이미지 | `model`, `prompt` | 고정 가격. 참조 이미지 최대 16장, 화면비 16종, 최대 4K. 프롬프트로 만드는 GIF 애니메이션                   |
| [`seedream-5-pro`](/image-api/seedream-5-pro)                           | 텍스트, 참조 이미지 | `model`, `prompt` | 참조 이미지 최대 10장, 1K/2K                                                        |
| [`seedream-5-lite`](/image-api/seedream-5-lite)                         | 텍스트, 참조 이미지 | `model`, `prompt` | 참조 이미지 최대 6장, 2K/4K 동일 가격                                                   |
| [`seedream-5.5`](/image-api/seedream-5-5)                               | 텍스트, 참조 이미지 | `model`, `prompt` | 참조 최대 6장, 2K만                                                               |
| [`grok-imagine-image-2.0`](/image-api/grok-imagine-image-2-0)           | 텍스트, 참조 이미지 | `model`, `prompt` | 참조 이미지 최대 5장, 편집 모드 자동 선택                                                   |

필드, 기본값, 열거값, 조합 규칙, 요청 예시, 응답, 오류 동작은 각 모델 페이지에서 확인하세요.

## 사용 가능한 모델 목록

`GET /v1/media/models`

| 파라미터         | 위치 | 타입     | 필수  | 허용 값             |
| ------------ | -- | ------ | --- | ---------------- |
| `media_type` | 쿼리 | string | 아니요 | `image`, `video` |

이 공개 엔드포인트는 인증이 필요하지 않습니다.

```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`          | string    | 고정된 공개 모델 별칭                                   |
| `object`      | string    | `generation_model`                             |
| `name`        | string    | 표시 이름                                          |
| `media_type`  | string    | `image` 또는 `video`                             |
| `input_modes` | string\[] | `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": "Editorial product photograph on a warm stone pedestal.",
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }'
```

올바른 요청은 `data.id`, `task_kind="image"`, 선택된 `model`, `status="queued"`, 사용량 지표, `request_id`와 함께 `201 Created`를 반환합니다. `succeeded` 또는 `failed`가 될 때까지 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 키를 보내거나, 잘못되었거나 만료·비활성화·소진된 키를 교체하세요 |
| `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)를 참고하세요. 실제로 적용되는 요청 계약은 아래 각 모델 페이지에 있습니다.