gemini-3-pro-image)는 텍스트 지시만으로 세부를 고치거나 사진 스타일을 바꾸고, 여러 이미지를 합쳐 새 이미지를 만듭니다. 이 페이지는 LaoZhang API의 두 요청 형식을 모두 다루며, 편집은 크기와 관계없이 호출마다 고정 가격 하나로 과금됩니다.
텍스트만으로 이미지를 만들려면 Nano Banana Pro 이미지 생성 가이드를 참고하세요.
시작하기 전에
1
API 키 발급
토큰 관리에서 토큰 생성(创建令牌) 창을 열고, 과금 방식(计费模式)을 사용량 우선(按量优先, 권장) 또는 건당 과금(按次计费)으로 설정한 뒤 생성(创建)을 클릭합니다. Nano Banana Pro에는 호출당 가격만 있어 사용량 과금(按量计费) 키로는 호출할 수 없습니다. 요청이 언제 과금되는지는 Nano Banana 개요의 과금 절에서 설명합니다.

2
키 설정과 의존성 설치
3
cURL용 저장 함수 추가
cURL 예제에는 응답에 이미지가 없으면 이 함수는 대신
jq가 필요합니다. 아래 셸 함수를 정의해 두면 Gemini 네이티브 응답의 마지막 이미지(중간 이미지가 함께 오더라도 최종 결과)를 mimeType에 맞는 확장자로 저장합니다.error, promptFeedback, finishReason 필드를 출력합니다.로컬 이미지 편집
요청은POST https://api.laozhang.ai/v1beta/models/gemini-3-pro-image:generateContent로 보냅니다. parts에 지시문을 먼저, 이미지를 그 뒤에 넣고, 로컬 파일은 파일과 일치하는 mimeType을 붙인 inlineData 파트로 보냅니다.
- Python
- cURL
아래 스크립트를 고양이 사진에 모자를 씌워 2K로 저장합니다.
nano_banana_pro_edit.py로 저장하세요. 지시문과 함께 로컬 이미지 1~14장을 보내고, 응답에 들어 있는 이미지를 모두 저장합니다.aspectRatio를 생략했으므로, 결과는 Google 기본 동작대로 입력 이미지 크기에 맞춰집니다. 모양을 바꾸려면 aspectRatio(또는 --ratio)를 추가하세요. 종횡비와 크기별 픽셀 수는 Nano Banana Pro 페이지의 출력 크기 절에 있습니다.
4K 편집은 1K보다 오래 걸리므로 클라이언트 타임아웃을 넉넉하게 잡으세요. 예제는 300초까지 기다립니다.
참조 이미지 합성
지시문 뒤에 프롬프트에서 언급하는 순서대로 파일을 최대 14장 나열하고, 프롬프트에서 각 이미지의 역할을 밝히세요.- 객체 이미지 6장: 제품이나 소품처럼 결과에 충실하게 나타나야 하는 대상
- 캐릭터 이미지 5장: 연작에서 인물을 일관되게 유지
- 스타일 이미지 3장: 색감이나 붓 터치 같은 전체적인 느낌 지정
공개 URL 이미지 편집
Gemini 네이티브 경로에서는 Base64 대신fileData 파트에 URL을 넣어 이미지를 보낼 수도 있습니다.
fileUri를 실제 이미지의 공개 HTTPS 주소로 바꾸고, mimeType을 이미지 형식에 맞추세요. 이미지는 요청 중에 해당 주소에서 내려받으므로 로그인, 쿠키, 봇 검사 없이 열려야 합니다. 내려받을 수 없다면 파일을 받아 inlineData로 보내세요.
- 요청이 20MB를 넘을 것 같으면 URL을 쓰세요. 요청 본문 전체를 20MB 이내로 유지하고,
inlineData로 보내는 이미지는 합계 약 15MB 이하로 맞추세요. 그보다 큰 이미지는fileData로 넘기거나 먼저 줄이세요. - 사이트의
robots.txt가 이미지 경로에 대한 크롤러 접근을 막지 않아야 합니다. 서명된 URL은 대기열과 재시도 시간을 감안해 최소 30분 동안 유효해야 합니다. fileData파트와inlineData파트는 참조 순서대로 같은parts배열에 함께 쓸 수 있습니다. 전체 조건은 Nano Banana 개요의 큰 이미지와 이미지 URL 절에 있습니다.
OpenAI 호환 경로 사용
앱이 이미 OpenAI SDK를 쓴다면 chat completions로 편집을 보낼 수 있습니다. 지시문과 이미지를 한 사용자 메시지에image_url 파트로 넣으며, 로컬 파일은 데이터 URL로, 원격 이미지는 공개 HTTPS URL로 보냅니다.
이 경로에는 종횡비와 크기 설정이 없으므로, 2K·4K나 고정 종횡비가 필요하면 Gemini 네이티브 경로를 쓰세요. 이미지는 message.content 안에 Base64 데이터 URL로 들어옵니다. 아래 스크립트를 nano_banana_pro_chat_edit.py로 저장하세요.
응답 처리
- Gemini 네이티브: 각 이미지는
candidates[].content.parts[]의inlineData파트이며mimeType과 Base64data를 가집니다.thought: true로 표시된 파트는 건너뛰세요. Pro는 렌더링 전에 사고하며, 복잡한 편집에서는 결과와 함께 중간 이미지가 올 수 있습니다. 마지막 이미지가 최종 결과입니다.- 파일은
mimeType에 맞는 확장자로 저장하세요.
- chat completions: 이미지는
choices[0].message.content텍스트 안에data:image/png;base64,...같은 데이터 URL로 들어 있습니다. 접두사에서 형식을 읽고 접두사를 떼어 낸 뒤, 길이가 4의 배수가 아니면=패딩을 붙여 디코딩하세요. - 이미지 없음: 네이티브 응답이면 각 후보의
finishReason(있으면promptFeedback도)을, chat 응답이면 답변 텍스트를 확인하세요. 안전 차단이나, 모델이 지시에 텍스트로만 답한 경우가 흔한 원인입니다.
편집 프롬프트 팁
- 얼굴, 제품 라벨, 레이아웃처럼 그대로 남아야 할 것을 적으세요. 마스크 파라미터가 없으므로 바꿀 영역은 말로 설명합니다.
- “두 번째 이미지의 재킷”처럼 순서와 역할로 각 이미지를 가리키세요.
- 얼굴이나 로고를 그대로 지키려면 자세히 묘사하고 바꾸지 말라고 적으세요.
- 이미지 안에 넣을 텍스트는 정확한 문구를 따옴표로 감싸고 글꼴 스타일을 지정하세요.
- 복잡한 편집은 단계로 나누고, 저장한 결과를 다음 요청의 입력으로 보내세요.
오류와 과금
Pro가 받는 값을 보내세요.- 안전 검사가 출력을 차단한 경우처럼, 이미지 없이 HTTP 200이 반환될 수 있습니다. 편집도 생성과 똑같이 과금되므로 이 호출은 과금됩니다.
finishReason(있으면promptFeedback도)을 확인하고 지시문이나 참조 이미지를 바꾼 뒤 다시 보내세요. Nano Banana 개요의 빈 응답 과금 피하기 절을 참고하세요. - HTTP 401은 키나
Authorization: Bearer헤더가 잘못되었다는 뜻입니다. Gemini 네이티브 경로는x-goog-api-key헤더로도 키를 받습니다. 429와 5xx는 백오프를 두고 재시도하고, 타임아웃이 난 요청은 다시 보내기 전에 호출 로그를 확인하세요. fileDataURL을 내려받지 못하면 로그인 없이 열리는지,robots.txt가 허용하는지 확인하거나 이미지를inlineData로 보내세요.- HTTP 413은 요청 본문이 너무 크다는 뜻입니다. 큰 이미지는 URL로 넘기거나, 요청 전체가 20MB 이내가 되도록 줄이세요.
- Base64는 파일 크기를 약 3분의 1 늘리므로, 아주 큰 사진은 인코딩하기 전에 줄이세요.
자주 묻는 질문
/v1/images/edits로 편집할 수 있나요?
아니요. Nano Banana Pro 편집은 Gemini 네이티브 generateContent 엔드포인트나 OpenAI 호환 /v1/chat/completions로 보내며, Images API의 편집 엔드포인트는 쓰지 않습니다.
이미지의 한 영역만 편집할 수 있나요?
네, 말로 설명하면 됩니다. 마스크 필드는 없습니다. Google은 이 방식을 시맨틱 마스킹이라고 부르며, 바꿀 요소를 지목하고 나머지는 그대로 두라고 적으면 됩니다. 예: “파란 소파만 갈색 가죽 소파로 바꿔 주세요. 방의 나머지 부분, 배치, 조명은 그대로 유지하세요.” 더 많은 팁은 위 편집 프롬프트 팁 절에 있습니다.aspectRatio를 생략하면 결과는 어떤 모양인가요?
Google의 기본 동작은 출력을 입력 이미지 크기에 맞추는 것이므로, aspectRatio를 생략하면 원래 모양이 유지됩니다. 위 로컬 이미지 편집 절의 예제가 이렇게 동작합니다. 다른 모양이 필요할 때만 aspectRatio를 지정하고, 1K·2K·4K 선택에는 imageSize를 쓰세요.
관련 페이지와 출처
- Nano Banana Pro — 텍스트→이미지, 종횡비별 출력 크기, Google 검색 그라운딩
- Nano Banana 2 — 더 저렴한 4K까지의 생성과 편집
- Nano Banana 개요 — 5종 모델, 두 요청 형식, 과금 규칙 비교
- Standard 편집 —
gemini-2.5-flash-image편집과 이전 방법 - 호출 로그 — 요청별 상태와 청구 금액 확인
- Google: Nano Banana image generation — 편집 프롬프트, 참조 이미지 제한, 사고
- Google: generateContent 레퍼런스 —
imageConfig필드 - Google: 파일 입력 방법 — 인라인 데이터와 공개 URL 입력