신청 절차
나노 바나나 이미지 API를 사용하려면 먼저 에이스 데이터 클라우드 콘솔에서 API 토큰을 받아야 합니다. 이를 보관해 두세요.
로그인이나 등록이 되어 있지 않으면 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 요청합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다.
하나의 API 토큰으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스마다 별도로 신청할 필요가 없습니다. 처음 신청 시 무료 사용량이 제공되어 무료로 체험할 수 있습니다; 사용량이 부족할 경우 콘솔에서 일반 잔액을 충전할 수 있습니다.
📘 전체 문서: 나노 바나나 이미지 API →
인터페이스 개요
- 기본 URL:
https://api.acedata.cloud - 엔드포인트:
POST /nano-banana/images - 인증 방식: HTTP 헤더에
authorization: Bearer {token}포함 - 요청 헤더:
accept: application/jsoncontent-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)
요청 예시 (Python)
성공 반환 예시
필드 설명
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)
요청 예시 (Python)
성공 반환 예시
필드 설명
image_urls[]:편집할 이미지 URL 목록(공개 접근 가능해야 함). 여러 장을 전달할 수 있으며, 서비스는 이 자료와prompt를 결합하여 편집을 완료합니다.- 나머지 필드는 “이미지 생성” 반환과 동일합니다.
비동기 콜백(선택 사항, 권장)
생성 또는 편집에는 일정 시간이 필요할 수 있습니다. 장기 연결로 인한 자원 점유를 피하기 위해callback_url을 통해 Webhook 콜백을 사용하는 것이 좋습니다:
- 요청 본문에
callback_url을 추가합니다. 예를 들어, 귀하의 서버 Webhook 주소(공개 접근 가능, POST JSON 지원). - API는 즉시
task_id가 포함된 응답(또는 기본 결과 포함)을 반환합니다. - 작업이 완료되면 플랫폼은
POST방식으로 전체 JSON을callback_url로 전송합니다.task_id를 통해 요청과 결과를 연결할 수 있습니다.
오류 처리
호출 실패 시 표준 오류 형식과 추적 ID가 반환됩니다. 일반적인 오류는 다음과 같습니다:- 400
token_mismatched:요청이 유효하지 않거나 매개변수 오류. - 400
api_not_implemented:인터페이스가 구현되지 않음(지원팀에 문의). - 401
invalid_token:인증 실패 또는 토큰 누락. - 429
too_many_requests:요청 빈도 초과. - 500
api_error:서버 오류.
오류 응답 예시
매개변수 대조 및 주의 사항
- 필수:
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를 보관하여 문제 해결 및 결과 연결에 용이하게 합니다.

