메인 콘텐츠로 건너뛰기
본 문서는 Nano Banana Images API의 연동 및 사용 방법을 소개합니다. 이 인터페이스는 두 가지 기능을 지원합니다: 이미지 생성(generate) 및 이미지 편집(edit).

신청 절차

Nano Banana Images API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API Token을 발급받아 예비로 보관하세요. 아직 로그인하거나 등록하지 않은 경우, 로그인 페이지로 자동 이동하여 등록 및 로그인을 안내하며, 완료 후 현재 페이지로 자동 돌아옵니다. 하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 서비스별로 별도 신청할 필요가 없습니다. 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족할 경우 콘솔에서 공용 잔액을 충전할 수 있습니다.
📘 전체 문서: Nano Banana Images API →

인터페이스 개요

  • Base URL:https://api.acedata.cloud
  • Endpoint: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-lite:Gemini 3.1 Flash Lite Image 기반, 1K만 지원, 빠른 생성 속도
    • nano-banana-2:Gemini 3.1 Flash Image Preview 기반, Pro급 품질 + Flash 속도
    • nano-banana-2.1:차세대 고효율 이미지 모델, 1K, 2K, 4K 이미지 생성 및 편집 지원
    • 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)

요청 예시(Python)

성공 반환 예시

필드 설명

  • success:이번 요청의 성공 여부.
  • task_id:작업 ID.
  • trace_id:문제 해결을 위한 추적 ID.
  • count:요청한 생성 또는 편집 이미지 수량으로, 1–4를 지원하며 기본값은 1입니다. data에는 생성에 성공한 이미지만 포함되며 실제 반환 장수에 따라 과금됩니다. 각 생성 호출은 제공업체의 기본 안전 정책을 강제로 사용합니다. 하나의 호출이 거부되어도 다른 성공 호출에는 영향을 주지 않으며, 모든 호출이 거부된 경우 403을 반환합니다.
  • data[]:결과 목록.
    • prompt:생성에 사용된 프롬프트(에코 반환).
    • image_url:생성된 이미지의 직접 URL.
참고: /nano-banana/images는 action과 prompt만으로 이미지를 생성할 수 있습니다

이미지 편집(action=edit)

기존 이미지를 기반으로 편집하고자 할 때는 action을 edit로 설정하고, image_urls를 통해 편집할 이미지 링크 목록(1장 또는 여러 장)을 전달하며, 동시에 편집 목표를 설명하는 prompt를 제공합니다. 예를 들어 여기서는 인물 사진 한 장과 의류 사진 한 장을 제공하여 인물이 해당 옷을 입도록 할 수 있습니다. 이미지 링크를 동시에 전달하고 action을 edit로 지정하면 됩니다. URL은 https 또는 http 프로토콜의 공개적으로 접근 가능한 HTTP URL일 수도 있고, data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....와 같은 Base64 인코딩 이미지일 수도 있습니다.

요청 예시(cURL)

요청 예시(Python)

성공 반환 예시

필드 설명

  • image_urls[]: 편집할 이미지 URL 목록(반드시 공개 인터넷에서 접근 가능해야 함). 여러 장을 전달할 수 있으며, 서비스는 이러한 소재와 prompt를 결합하여 편집을 완료합니다.
  • 나머지 필드는 「이미지 생성」 반환과 동일합니다.

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

생성 또는 편집에는 일정 시간이 필요할 수 있습니다. 리소스를 점유하는 장기 연결을 피하기 위해 callback_url을 통해 Webhook 콜백을 사용하는 것을 권장합니다:
  1. 요청 본문에 callback_url을 추가합니다. 예를 들어, 서버 측 Webhook 주소(공개 인터넷에서 접근 가능해야 하며 POST JSON을 지원해야 함)입니다.
  2. API는 task_id를 포함한 응답(또는 기본 결과를 포함)을 즉시 반환합니다.
  3. 작업이 완료되면 플랫폼은 POST 방식으로 전체 JSON을 callback_url에 전송합니다. task_id를 통해 요청과 결과를 연결할 수 있습니다.
콜백 페이로드 예시(필드 구조는 동기 성공 반환과 동일):

오류 처리

호출에 실패하면 표준 오류 형식과 추적 ID가 반환됩니다. 일반적인 오류는 다음과 같습니다:
  • 400 token_mismatched: 요청이 유효하지 않거나 매개변수 오류입니다.
  • 400 api_not_implemented: 인터페이스가 구현되지 않았습니다(지원팀에 문의하세요).
  • 401 invalid_token: 인증에 실패했거나 Token이 없습니다.
  • 403 forbidden: 제공업체의 기본 보안 정책이 요청 또는 생성 결과를 거부했습니다. 이 호출은 이미지를 반환하지 않으며 과금되지 않습니다. 여러 이미지 요청의 경우 다른 성공한 호출은 여전히 반환되고 과금될 수 있습니다.
  • 429 too_many_requests: 요청 빈도가 한도를 초과했습니다.
  • 500 api_error: 서버 측 예외입니다.

오류 응답 예시


매개변수 대조 및 주의 사항

  • 필수: action, prompt
  • 편집 전용: image_urls(배열, 최소 1개 항목)
  • 선택 사항: model(기본값 nano-banana, 선택 가능: nano-banana-2-lite, nano-banana-2, nano-banana-2.1, nano-banana-pro; nano-banana-2.1을 제외하고 각각에 해당하는 :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를 보관하세요.