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

# 나노 바나나 이미지 API 연동 설명

> Nano Banana Image Generation API guide - Ace Data Cloud

본 문서는 나노 바나나 이미지 API의 연동 및 사용에 대해 설명합니다. 이 인터페이스는 두 가지 기능을 지원합니다: **이미지 생성(generate)** 및 **이미지 편집(edit)**.

## 신청 절차

나노 바나나 이미지 API를 사용하려면 먼저 [에이스 데이터 클라우드 콘솔](https://platform.acedata.cloud/console/applications)에서 API 토큰을 받아야 합니다. 이를 보관해 두세요.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

로그인이나 등록이 되어 있지 않으면 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 요청합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다.

**하나의 API 토큰으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스마다 별도로 신청할 필요가 없습니다.** 처음 신청 시 무료 사용량이 제공되어 무료로 체험할 수 있습니다; 사용량이 부족할 경우 [콘솔](https://platform.acedata.cloud/console/coin)에서 일반 잔액을 충전할 수 있습니다.

> 📘 전체 문서: [나노 바나나 이미지 API →](https://platform.acedata.cloud/documents/nano-banana-images)

## 인터페이스 개요

* **기본 URL**: `https://api.acedata.cloud`
* **엔드포인트**: `POST /nano-banana/images`
* **인증 방식**: HTTP 헤더에 `authorization: Bearer {token}` 포함
* **요청 헤더**:
  * `accept: application/json`
  * `content-type: application/json`
* **동작(action)**:
  * `generate`: 텍스트 프롬프트에 따라 이미지 생성
  * `edit`: 주어진 이미지를 기반으로 편집
* **모델(model)** (선택 사항):
  * `nano-banana` (기본값): Gemini 2.5 Flash Image 기반, 속도 빠르고 비용 저렴
  * `nano-banana-2-lite`: Gemini 3.1 Flash Lite Image 기반, 1K만 지원, 생성 속도 빠름
  * `nano-banana-2`: Gemini 3.1 Flash Image Preview 기반, Pro급 품질 + Flash 속도
  * `nano-banana-pro`: Gemini 3 Pro Image Preview 기반, 최고 품질
  * `nano-banana:official`, `nano-banana-2-lite:official`, `nano-banana-2:official`, `nano-banana-pro:official`: 해당 모델의 공식 채널 버전, 화질 및 안정성이 더 좋으며, 요금이 다름
* **비동기 콜백**: 선택 사항, `callback_url`을 통해 작업 완료 알림 및 결과 수신
* **이미지 수**: 선택 사항, `count`를 통해 1–4장 지정, 기본값 1장; 일부 실패 시 성공한 이미지만 반환 및 요금 청구

## 빠른 시작: 이미지 생성 (`action=generate`)

**최소 필수 매개변수**: `action`, `prompt`
프롬프트에 따라 직접 이미지를 생성하고 싶을 때, `action`을 `generate`로 설정하고 명확한 `prompt`를 제공하면 됩니다.

### 요청 예시 (cURL)

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "model": "nano-banana-pro",
    "prompt": "일본의 노인 도예가의 포토리얼리스틱 클로즈업 초상화. 깊고 햇볕에 새겨진 주름과 따뜻하고 아는 듯한 미소를 지니고 있습니다. 그는 갓 유약을 바른 찻잔을 조심스럽게 검사하고 있습니다. 배경은 그의 소박하고 햇볕이 잘 드는 작업실입니다. 장면은 창문을 통해 부드러운 황금 시간의 빛이 비추어져 점토의 섬세한 질감을 강조합니다. 85mm 초상화 렌즈로 촬영되어 부드럽고 흐릿한 배경(bokeh)이 만들어집니다. 전체적인 분위기는 평화롭고 장인정신이 느껴집니다. 세로 초상화 방향입니다.",
    "count": 1
  }'
```

### 요청 예시 (Python)

```python theme={null}
import requests

url = "https://api.acedata.cloud/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "generate",
    "model": "nano-banana-pro",
    "prompt": (
        "일본의 노인 도예가의 포토리얼리스틱 클로즈업 초상화 "
        "깊고 햇볕에 새겨진 주름과 따뜻하고 아는 듯한 미소를 지니고 있습니다. 그는 조심스럽게 "
        "갓 유약을 바른 찻잔을 검사하고 있습니다. 배경은 그의 소박하고 햇볕이 잘 드는 "
        "작업실입니다. 장면은 창문을 통해 부드러운 황금 시간의 빛이 비추어져 점토의 섬세한 질감을 강조합니다. "
        "85mm 초상화 렌즈로 촬영되어 부드럽고 흐릿한 배경(bokeh)이 만들어집니다. 전체적인 분위기는 "
        "평화롭고 장인정신이 느껴집니다. 세로 초상화 방향입니다."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())
```

### 성공 반환 예시

```json theme={null}
{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "일본의 노인 도예가의 포토리얼리스틱 클로즈업 초상화. 깊고 햇볕에 새겨진 주름과 따뜻하고 아는 듯한 미소를 지니고 있습니다. 그는 조심스럽게 갓 유약을 바른 찻잔을 검사하고 있습니다. 배경은 그의 소박하고 햇볕이 잘 드는 작업실입니다. 장면은 창문을 통해 부드러운 황금 시간의 빛이 비추어져 점토의 섬세한 질감을 강조합니다. 85mm 초상화 렌즈로 촬영되어 부드럽고 흐릿한 배경(bokeh)이 만들어집니다. 전체적인 분위기는 평화롭고 장인정신이 느껴집니다. 세로 초상화 방향입니다.",
      "image_url": "https://platform2.cdn.acedata.cloud/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336.png"
    }
  ]
}
```

### 필드 설명

* `success`: 이번 요청이 성공했는지 여부.
* `task_id`: 작업 ID.
* `trace_id`: 링크 추적 ID, 문제 해결에 용이.
* `count`: 요청한 생성 또는 편집 이미지 수, 1–4 지원, 기본값 1. 일부 실패 시 `data`는 성공한 이미지만 포함.
* `data[]`: 결과 목록.
  * `prompt`: 생성에 사용된 프롬프트(회신).
  * `image_url`: 생성된 이미지의 직링크 URL.

> 주의: `/nano-banana/images`는 `action`과 `prompt`만으로 이미지를 생성할 수 있습니다.

## 이미지 편집 (`action=edit`)

기존 이미지를 기반으로 편집하고 싶을 때, `action`을 `edit`로 설정하고 `image_urls`를 통해 편집할 이미지 링크 목록(1장 또는 여러 장)을 전달하며, 편집 목표를 설명하는 `prompt`를 제공하면 됩니다.

예를 들어, 여기서 인물 사진과 옷 사진을 제공하여 인물이 그 옷을 입도록 할 수 있습니다. 이미지 링크를 동시에 전달하고 `action`을 `edit`로 지정하면 됩니다. URL은 HTTP URL로, `https` 또는 `http` 프로토콜의 공개 접근 가능한 링크일 수 있으며, Base64 인코딩된 이미지일 수도 있습니다. 예: `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....`

### 요청 예시 (cURL)

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "edit",
    "prompt": "이 남자가 이 티셔츠를 입도록 하세요.",
    "image_urls": [
      "https://cdn.acedata.cloud/v8073y.png",
      "https://cdn.acedata.cloud/44xlah.png"
    ],
    "count": 1
  }'
```

### 요청 예시 (Python)

```python theme={null}
import requests

url = "https://api.acedata.cloud/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "edit",
    "prompt": "이 남자가 이 티셔츠를 입게 하세요",
    "image_urls": [
        "https://cdn.acedata.cloud/v8073y.png",
        "https://cdn.acedata.cloud/44xlah.png"
    ],
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())
```

### 성공 반환 예시

```json theme={null}
{
  "success": true,
  "task_id": "93f11baf-347b-4bb4-9520-8653cb46d6a3",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "data": [
    {
      "prompt": "이 남자가 이 티셔츠를 입게 하세요",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png"
    }
  ]
}
```

### 필드 설명

* `image_urls[]`：편집할 이미지 URL 목록(공개 접근 가능해야 함). 여러 장을 전달할 수 있으며, 서비스는 이 자료와 `prompt`를 결합하여 편집을 완료합니다.
* 나머지 필드는 "이미지 생성" 반환과 동일합니다.

***

## 비동기 콜백(선택 사항, 권장)

생성 또는 편집에는 일정 시간이 필요할 수 있습니다. 장기 연결로 인한 자원 점유를 피하기 위해 `callback_url`을 통해 **Webhook 콜백**을 사용하는 것이 좋습니다:

1. 요청 본문에 `callback_url`을 추가합니다. 예를 들어, 귀하의 서버 Webhook 주소(공개 접근 가능, POST JSON 지원).
2. API는 **즉시** `task_id`가 포함된 응답(또는 기본 결과 포함)을 반환합니다.
3. 작업이 완료되면 플랫폼은 `POST` 방식으로 전체 JSON을 `callback_url`로 전송합니다. `task_id`를 통해 요청과 결과를 연결할 수 있습니다.

**콜백 페이로드 예시**(필드 구조는 동기 성공 반환과 동일):

```json theme={null}
{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "하얀 색 샴 고양이",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
    }
  ]
}
```

***

## 오류 처리

호출 실패 시 표준 오류 형식과 추적 ID가 반환됩니다. 일반적인 오류는 다음과 같습니다:

* **400 `token_mismatched`**：요청이 유효하지 않거나 매개변수 오류.
* **400 `api_not_implemented`**：인터페이스가 구현되지 않음(지원팀에 문의).
* **401 `invalid_token`**：인증 실패 또는 토큰 누락.
* **429 `too_many_requests`**：요청 빈도 초과.
* **500 `api_error`**：서버 오류.

### 오류 응답 예시

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "내부 서버 오류."
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

***

## 매개변수 대조 및 주의 사항

* **필수**：`action`、`prompt`
* **편집 전용**：`image_urls`（배열, 최소 1 항목）
* **선택 사항**：`model`（기본 `nano-banana`, 선택 `nano-banana-2-lite`, `nano-banana-2`, `nano-banana-pro`, 또는 해당 `:official` 공식 채널 버전）、`aspect_ratio`（가로 세로 비율, 예: `1:1`, `16:9`）、`resolution`（해상도, 예: `1K`, `2K`, `4K`; `nano-banana-2-lite`는 `1K`만 지원）、`callback_url`（비동기 콜백용）
* **Headers**：반드시 `authorization: Bearer {token}`를 제공해야 하며, `accept`는 `application/json`으로 설정하는 것이 좋습니다.
* **이미지 접근성**：`image_urls`는 공개 접근 가능한 직링크(HTTP/HTTPS)여야 하며, HTTPS 사용을 권장합니다.
* **멱등성 및 추적**：`task_id`와 `trace_id`를 보관하여 문제 해결 및 결과 연결에 용이하게 합니다.