Nano Banana Pro API를 사용하기 전에 필요한 것
GPT Proto 계정, 최소 1회 생성 가능한 계정 잔액, 그리고 GPT Proto API 키가 필요합니다. 수동 통합을 위해서는 터미널과 Python 3도 필요합니다. 코딩이 익숙하지 않다면, 빈 브라우저 채팅창 대신 실제 프로젝트를 검사하고 수정할 수 있는 코딩 에이전트를 사용하세요.
| 항목 |
이 가이드에서 사용된 값 |
| 제품 |
Nano Banana Pro |
| 공식 모델 제품군 |
Gemini 3 Pro Image |
| GPT Proto 모델 ID |
gemini-3-pro-image-preview |
| 작업 |
텍스트-이미지 변환 |
| 입력 |
텍스트 프롬프트 |
| 출력 |
PNG 또는 JPEG 이미지 |
| 사용 가능한 크기 |
1K, 2K 및 4K |
Google은 현재 Gemini 이미지 생성 문서에서 Nano Banana Pro와 Nano Banana 2를 별도의 모델로 나열하고 있습니다. 코드 내 모델 ID가 gemini-3.1-flash-image라면, 여기에서 다루는 Pro 모델이 아닌 Nano Banana 2를 호출하고 있는 것입니다. 더 새로운 2.1 경로의 경우, 모델 ID를 선택하기 전에 Nano Banana 2.1과 Nano Banana Pro를 비교하세요. 이 Pro 튜토리얼이 변경 없이 적용된다고 가정하지 마십시오.
1단계: Nano Banana Pro 모델 페이지 열기 및 테스트
Nano Banana Pro API 페이지를 열고 로그인합니다. 코드를 작성하기 전에 Playground를 사용하여 간단한 테스트를 실행해 보세요:
작업을 Text To Image(텍스트-이미지 변환)로 설정된 상태로 유지하세요.
짧은 프롬프트를 입력합니다.
1K, 1:1 가로세로 비율, PNG 출력을 선택합니다.
Generate(생성)를 클릭하고 이미지가 반환되는지 확인합니다.
이 과정은 모델 문제와 통합 문제를 분리해 줍니다. Playground 요청이 실패하면 먼저 계정, 잔액, 프롬프트를 확인하세요. Playground는 성공하는데 애플리케이션이 실패한다면, API 키, 요청 헤더, JSON 본문 또는 프로젝트 환경이 문제일 가능성이 높습니다.

2단계: Nano Banana Pro API 키 생성
모델 페이지 오른쪽 상단에 있는 Try this model(이 모델 사용해 보기)을 클릭합니다. 빠른 시작 패널에서 새 API 키를 생성하거나 기존 키를 선택할 수 있습니다.
Create API Key(API 키 생성)를 클릭합니다.
새 키를 복사하여 안전한 곳에 보관하세요.
GPTPROTO_API_KEY라는 이름의 환경 변수에 추가합니다.
소스 코드에 직접 붙여넣지 마십시오.
macOS 또는 Linux에서는 다음 명령어로 현재 터미널 세션에 변수를 설정합니다:
export GPTPROTO_API_KEY="your-api-key"
Windows PowerShell에서는 다음을 사용합니다:
$env:GPTPROTO_API_KEY="your-api-key"
이 키는 반드시 GPT Proto API 키여야 합니다. Google AI Studio 키는 다른 자격 증명이므로 GPT Proto 엔드포인트로 전송되는 요청을 인증할 수 없습니다.
키를 비밀번호처럼 취급하세요. Git, 스크린샷, 브라우저 측 JavaScript 및 공개 AI 채팅에 노출되지 않도록 하세요. Google의 일반적인 API 키 보안 지침에서도 환경 변수 사용을 권장하며 클라이언트 측 애플리케이션에 키를 노출하지 말라고 경고합니다.

3단계: 수동 또는 AI 지원 통합 선택
키를 생성한 후, 본인의 경험에 맞는 경로를 선택하세요.
| 경로 |
권장 대상 |
다음 단계 |
| 수동 통합 |
Python, JavaScript 또는 cURL을 읽을 수 있는 경우 |
요청을 복사하여 실행하고, 결과 흐름을 애플리케이션에 추가하세요. |
| AI 지원 통합 |
API 코드를 어디에 넣어야 할지 모르는 경우 |
모델 페이지의 마크다운을 코딩 에이전트에 제공하여 프로젝트를 수정하게 하세요. |
이미 Python을 알고 있다면 수동 경로가 더 빠릅니다. 만약 “이 코드를 어떤 파일에 넣어야 하지?”라는 고민이 든다면 AI 지원 경로를 사용하세요.
경로 A: Python으로 Nano Banana Pro API 호출하기
cURL로 첫 번째 요청 제출하기
이 요청은 비동기 생성 작업을 시작합니다. 일반적으로 완성된 이미지가 아닌 작업 ID를 반환합니다.
curl --request POST "https://gptproto.com/api/v3/google/gemini-3-pro-image-preview/text-to-image" \
--header "Authorization: Bearer $GPTPROTO_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"prompt": "A tiny origami fox sailing a teacup across a moonlit puddle",
"size": "1K",
"aspect_ratio": "1:1",
"output_format": "png",
"enable_sync_mode": false,
"enable_base64_output": false
}'
성공적인 제출에는 data.id, data.status, 그리고 data.urls.get가 포함됩니다. 상태가 created 또는 running인 동안에는 출력 목록이 비어 있을 수 있습니다. 이는 정상적인 현상입니다.
Python 종속성 설치하기
python -m pip install requests
전체 제출 및 폴링 스크립트 실행
다음 스크립트를 nano_banana_pro.py(으)로 저장하세요. 이 스크립트는 프롬프트를 제출하고, 2초마다 작업을 확인하며, 실패 시 중단하고, 최종 이미지 URL을 출력합니다.
import os
import time
import requests
API_KEY = os.environ.get("GPTPROTO_API_KEY")
SUBMIT_URL = (
"https://gptproto.com/api/v3/google/"
"gemini-3-pro-image-preview/text-to-image"
)
if not API_KEY:
raise RuntimeError("이 스크립트를 실행하기 전에 GPTPROTO_API_KEY를 설정하세요.")
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"prompt": "A tiny origami fox sailing a teacup across a moonlit puddle",
"size": "1K",
"aspect_ratio": "1:1",
"output_format": "png",
"enable_sync_mode": False,
"enable_base64_output": False,
}
def read_data(response):
response.raise_for_status()
body = response.json()
if body.get("code") != 200:
raise RuntimeError(body.get("message", "GPT Proto에서 오류를 반환했습니다."))
return body["data"]
submission = requests.post(
SUBMIT_URL,
headers=headers,
json=payload,
timeout=60,
)
task = read_data(submission)
result_id = task["id"]
poll_url = task.get("urls", {}).get("get")
if not poll_url:
poll_url = f"https://gptproto.com/api/v3/predictions/{result_id}/result"
print(f"Created task: {result_id}")
deadline = time.monotonic() + 300
while True:
status = task.get("status")
if status == "completed":
outputs = task.get("outputs", [])
if not outputs:
raise RuntimeError("작업이 완료되었으나 출력 URL이 없습니다.")
print(f"Image URL: {outputs[0]}")
break
if status == "failed":
raise RuntimeError(task.get("error") or "이미지 생성에 실패했습니다.")
if time.monotonic() >= deadline:
raise TimeoutError("5분 이내에 생성이 완료되지 않았습니다.")
time.sleep(2)
result = requests.get(
poll_url,
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
task = read_data(result)
환경 변수를 설정한 동일한 터미널에서 실행하세요:
python nano_banana_pro.py
첫 번째 성공적인 POST 요청을 생성 완료로 간주하지 마세요. 상태가 completed(으)로 변경되고 data.outputs에 파일 URL이 포함되어야 요청이 완전히 성공한 것입니다.
경로 B: 코딩 에이전트가 API를 통합하도록 하기
AI 어시스턴트를 위해 API 문서를 다시 입력할 필요가 없습니다. Nano Banana Pro 모델 페이지에서 현재 엔드포인트, 스키마, 인증 방식, 응답 필드 및 코드 예제를 전송할 수 있습니다.
이 모델 사용해 보기를 열고 AI용 마크다운 복사를 선택하세요. 또한 LLM 메뉴를 열고 다음 중 하나를 선택할 수도 있습니다:
마크다운 콘텐츠 복사
마크다운 파일 열기
URL과 함께 프롬프트 복사
ChatGPT에서 열기
Claude에서 열기
Gemini에서 열기
Grok에서 열기
기계 판독 가능한 버전은 모델 페이지의 Nano Banana Pro 마크다운 가이드에서도 확인할 수 있습니다.

단순한 빈 채팅이 아닌 프로젝트를 에이전트에 제공하세요
브라우저 챗봇은 코드를 설명할 수는 있지만, 사용자의 폴더, 프레임워크, 서버 진입점 또는 배포 설정을 알지 못할 수 있습니다. Codex, Claude Code 또는 Cursor와 같은 코딩 에이전트는 해당 파일을 검사하여 프로젝트의 올바른 위치에 통합 코드를 배치할 수 있습니다.
에이전트에게는 여전히 다음이 필요합니다:
이것은 노코드 API가 아닌 AI 지원 코딩입니다. 에이전트가 코드를 작성하고 연결하는 동안, 사용자는 변경 사항을 승인하고 런타임 및 자격 증명을 제공합니다.
코딩 에이전트에 프롬프트 입력하기
복사한 마크다운을 에이전트에 붙여넣고 다음 지침을 추가하세요:
첨부된 마크다운 문서를 사용하여 이 프로젝트에 GPT Proto Nano Banana Pro 텍스트-이미지 변환 API를 통합하세요. 먼저 기존 스택을 검사하여 올바른 서버 측 파일을 식별하세요. API 키는 GPTPROTO_API_KEY라는 환경 변수에 저장하고, 절대 하드코딩하거나 브라우저 측 코드에 노출하지 마세요. 요청 제출, 비동기 상태 폴링, 작업 실패 처리, 반환된 이미지 URL 표시 기능을 구현하세요. 이 통합에 필요한 파일만 추가하세요. 최소한의 테스트를 실행한 다음, 변경한 파일, 프로젝트 시작 방법, 그리고 제가 수동으로 완료해야 할 단계를 보고하세요.
실제 키를 지침에 붙여넣지 마세요. 터미널, Git에서 제외된 로컬 .env 파일 또는 배포 플랫폼의 보안 설정에 키를 설정하세요.
에이전트의 작업을 수락하기 전에 검토하기
유용한 검토를 수행하기 위해 모든 줄을 이해할 필요는 없습니다. 다음 여덟 가지 항목을 확인하세요:
키는 GPTPROTO_API_KEY에서 읽어옵니다.
키가 브라우저 코드나 커밋된 파일에 포함되어 있지 않습니다.
모델 ID는 gemini-3-pro-image-preview입니다.
코드가 이 가이드에 표시된 텍스트-이미지 변환 엔드포인트를 호출합니다.
제출 후 data.id 또는 data.urls.get을 읽습니다.
completed 상태를 기다리고 failed 상태를 처리합니다.
최종 URL을 data.outputs에서 읽습니다.
에이전트가 단순히 코드가 올바르게 보인다고 말하는 대신, 실제 최소 테스트를 실행했습니다.
전체 애플리케이션을 연결하기 전에 시도해보세요: Nano Banana Pro Playground를 열고 1K에서 프롬프트를 검증한 다음, 동일한 설정을 코딩 에이전트에 제공하세요.
Nano Banana Pro API 매개변수 및 요금
기본 텍스트-이미지 변환 요청에는 프롬프트만 있으면 됩니다. 다른 필드는 출력 및 응답 형식을 제어합니다.
| 매개변수 |
필수 여부 |
기본값 |
허용되는 값 또는 목적 |
prompt |
예 |
— |
생성할 이미지에 대한 설명 |
size |
아니요 |
1K |
1K, 2K, 또는 4K |
aspect_ratio |
아니요 |
1:1 |
1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 또는 21:9 |
output_format |
아니요 |
png |
png 또는 jpeg |
enable_sync_mode |
아니요 |
false |
결과를 반환하기 전에 업로드 완료까지 대기 |
enable_base64_output |
아니요 |
false |
URL 대신 Base64 데이터 반환 |
이 가이드가 작성된 2026년 9월 기준, 실시간 GPT Proto 모델 페이지에 나열된 요금은 다음과 같습니다:
| 해상도 |
생성당 가격 |
| 1K |
$0.0804 |
| 2K |
$0.0804 |
| 4K |
$0.144 |
키를 생성한다고 해서 이미지 호출이 무료가 되는 것은 아닙니다. 성공적인 생성마다 계정 잔액이 차감됩니다. 가용성과 요금은 변경될 수 있으므로 대규모 배치를 시작하기 전에 실시간 모델 페이지를 확인하세요.
초기 프롬프트 작업 시에는 1K에서 시작하세요. 구성, 문구, 가로세로 비율이 올바른지 확인한 후에 4K로 이동하세요. 절충안은 간단합니다. 4K는 더 큰 에셋을 생성하지만 시도당 비용이 더 많이 듭니다.
일반적인 Nano Banana Pro API 오류
| 문제 |
주요 원인 |
해결 방법 |
400 Bad Request |
잘못된 JSON, 필드 이름, 값 또는 차단된 입력 |
요청을 현재 모델 페이지 스키마와 비교하세요 |
401 Unauthorized |
키 누락 또는 잘못된 키 |
GPTPROTO_API_KEY 및 Authorization 헤더를 확인하세요 |
403 Forbidden |
잔액 부족 또는 권한 누락 |
계정 잔액 및 키 상태를 확인하세요 |
413 Request Entity Too Large |
요청 본문이 너무 큼 |
업로드된 콘텐츠 또는 Base64 콘텐츠를 줄이세요 |
429 Too Many Requests |
호출이 너무 빠르게 들어옴 |
지연 시간을 늘려가며 재시도하고 시도 횟수를 제한하세요 |
500, 502, 또는 504 |
일시적인 플랫폼 또는 업스트림 오류 |
제한된 횟수만큼 재시도하세요. 무한 루프를 생성하지 마세요 |
| 응답에 이미지가 없음 |
작업이 여전히 생성됨 또는 실행 중 |
완료될 때까지 data.urls.get을 폴링하세요 |
상태가 실패로 변경됨 |
생성이 완료되지 않음 |
재시도하기 전에 data.error를 읽어보세요 |
| 에이전트는 완료되었다고 하지만 아무것도 실행되지 않음 |
코드를 작성했지만 실행하지 않음 |
정확한 테스트 명령과 반환된 상태를 요청하세요 |
일시적인 오류의 경우, 지연 없이 동일한 요청을 반복해서 보내는 대신 지수 백오프(exponential backoff)를 사용하세요. 또한 결과 ID를 기록해 두면 모호한 “생성 실패” 보고 대신 검사할 특정 작업을 파악할 수 있습니다.
검증된 생성 하나로 시작하기
코드를 작성하는 경우, cURL 요청으로 시작한 다음 전체 Python 스크립트를 사용하여 작업을 제출하고 폴링하세요. 코드를 작성하지 않는 경우, 모델 페이지의 마크다운을 코딩 에이전트에 복사하여 프로젝트 내에서 동일한 흐름을 통합하도록 요청하세요.
두 경우 모두 더 큰 워크플로를 구축하기 전에 1K 이미지 하나를 먼저 검증하세요. Nano Banana Pro API 페이지를 열어 프롬프트를 테스트하고, Try this model을 사용하여 키를 생성하거나 현재 통합 지침을 코딩 에이전트에 전달하세요.