메인 콘텐츠로 건너뛰기

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의 연동 및 사용에 대해 설명합니다. 이 인터페이스는 두 가지 기능을 지원합니다: 이미지 생성(generate) 및 이미지 편집(edit).

​
신청 절차

사용하기 전에, XHuoAPI 플랫폼에서 나노 바나나 이미지 API에 들어가서 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)

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)

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())

​
성공 반환 예시

{
  "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)

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)

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())

​
성공 반환 예시

{
  "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를 통해 요청과 결과를 연결할 수 있습니다.
콜백 페이로드 예시(필드 구조는 동기 성공 반환과 일치): 
{
  "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: 서버 오류입니다.

​
오류 응답 예시

{
  "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를 보존하여 장애 조사 및 결과 연결에 용이하게 합니다.