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

신청 절차

나노 바나나 이미지 API를 사용하려면 먼저 에이스 데이터 클라우드 콘솔에서 API 토큰을 받아야 합니다. 이를 보관해 두세요. 로그인이나 등록이 되어 있지 않으면 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 요청합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다. 하나의 API 토큰으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스마다 별도로 신청할 필요가 없습니다. 처음 신청 시 무료 사용량이 제공되어 무료로 체험할 수 있습니다; 사용량이 부족할 경우 콘솔에서 일반 잔액을 충전할 수 있습니다.
📘 전체 문서: 나노 바나나 이미지 API →

인터페이스 개요

  • 기본 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 프롬프트에 따라 직접 이미지를 생성하고 싶을 때, actiongenerate로 설정하고 명확한 prompt를 제공하면 됩니다.

요청 예시 (cURL)

요청 예시 (Python)

성공 반환 예시

필드 설명

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

이미지 편집 (action=edit)

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

요청 예시 (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:인증 실패 또는 토큰 누락.
  • 429 too_many_requests:요청 빈도 초과.
  • 500 api_error:서버 오류.

오류 응답 예시


매개변수 대조 및 주의 사항

  • 필수actionprompt
  • 편집 전용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-lite1K만 지원)、callback_url(비동기 콜백용)
  • Headers:반드시 authorization: Bearer {token}를 제공해야 하며, acceptapplication/json으로 설정하는 것이 좋습니다.
  • 이미지 접근성image_urls는 공개 접근 가능한 직링크(HTTP/HTTPS)여야 하며, HTTPS 사용을 권장합니다.
  • 멱등성 및 추적task_idtrace_id를 보관하여 문제 해결 및 결과 연결에 용이하게 합니다.