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

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

> Nano Banana Image Generation 集成指南 - XHuoAPI

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

## 신청 절차

사용하기 전에, XHuoAPI 플랫폼에서 [나노 바나나 이미지 API](https://api.xhuoapi.ai/documents/23985a11-d713-41d1-ad84-24b021805b3d)에 들어가서 Acquire를 클릭하여 개통을 신청하세요. 최초 신청 시 일반적으로 무료 할당량이 제공됩니다. 개통이 완료되면, 플랫폼에서 API 호출에 사용할 Bearer Token을 얻을 수 있습니다.

## 인터페이스 개요

* **기본 URL**: `https://api.xhuoapi.ai/v1`
* **엔드포인트**: `POST /nano-banana/images`
* **인증 방식**: HTTP Header에 `authorization: Bearer {token}` 포함
* **요청 헤더**:
  * `accept: application/json`
  * `content-type: application/json`
* **동작(action)**:
  * `generate`: 텍스트 프롬프트에 따라 이미지 생성
  * `edit`: 주어진 이미지를 기반으로 편집
* **모델(model)** (선택 사항):
  * `nano-banana` (기본값): Gemini 2.5 Flash Image 기반, 빠른 속도, 저렴한 비용
  * `nano-banana-2`: Gemini 3.1 Flash Image Preview 기반, Pro급 품질 + Flash 속도
  * `nano-banana-pro`: Gemini 3 Pro Image Preview 기반, 최고 품질
* **비동기 콜백**: 선택 사항, `callback_url`을 통해 작업 완료 알림 및 결과 수신

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

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

### 요청 예시 (cURL)

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "prompt": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
    "count": 1
  }'
```

### 요청 예시 (Python)

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "generate",
    "prompt": (
        "A photorealistic close-up portrait of an elderly Japanese ceramicist "
        "with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully "
        "inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched "
        "workshop. The scene is illuminated by soft, golden hour light streaming through "
        "a window, highlighting the fine texture of the clay. Captured with an 85mm "
        "portrait lens, resulting in a soft, blurred background (bokeh). The overall mood "
        "is serene and masterful. Vertical portrait orientation."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())
```

### 성공 반환 예시

```json theme={null}
{
  "success": true,
  "task_id": "056f0589-a3dd-4ec2-8440-ad61f5038dfa",
  "trace_id": "c48de83f-0077-426e-b02b-ff1d58179064",
  "data": [
    {
      "prompt": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
      "image_url": "https://platform.cdn.xhuoapi.ai/nanobanana/69790adb-c85d-4362-ad9e-0c9ba4352cf4.png"
    }
  ]
}
```

### 필드 설명

* `success`: 이번 요청이 성공했는지 여부.
* `task_id`: 작업 ID.
* `trace_id`: 링크 추적 ID, 문제 해결에 용이.
* `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.xhuoapi.ai/v1/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "edit",
    "prompt": "let this man wear on this T-shirt",
    "image_urls": [
      "https://cdn.xhuoapi.ai/v8073y.png",
      "https://cdn.xhuoapi.ai/44xlah.png"
    ],
    "count": 1
  }'
```

### 요청 예시 (Python)

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "edit",
    "prompt": "let this man wear on this T-shirt",
    "image_urls": [
        "https://cdn.xhuoapi.ai/v8073y.png",
        "https://cdn.xhuoapi.ai/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": "let this man wear on this T-shirt",
      "image_url": "https://platform.cdn.xhuoapi.ai/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.xhuoapi.ai/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` 또는 `nano-banana-pro`), `aspect_ratio`(가로 세로 비율, 예: `1:1`, `16:9`), `resolution`(해상도, 예: `1K`, `2K`, `4K`), `callback_url`(비동기 콜백용)
* **Headers**: `authorization: Bearer {token}`를 반드시 제공해야 하며; `accept`는 `application/json`으로 설정하는 것이 좋습니다.
* **이미지 접근성**: `image_urls`는 공개 접근 가능한 직링크(HTTP/HTTPS)여야 하며, HTTPS 사용을 권장합니다.
* **멱등성과 추적**: `task_id`와 `trace_id`를 보존하여 장애 조사 및 결과 연결에 용이하게 합니다.