신청 절차
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/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-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 콜백을 사용하는 것을 권장합니다:
- 요청 본문에
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: 인증에 실패했거나 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를 보관하세요.

