나노 바나나 프로 API 사용법: 공식 JSON·YAML 템플릿과 오류 해결

2026년 7월 20일 기준, Google 공식 모델 카드는 Nano Banana Pro를 Gemini 3 Pro Image, 모델 ID **gemini-3-pro-image**로 문서화한다. 새 Google 직접 연동이라면 Interactions API 개요에 따라 POST https://generativelanguage.googleapis.com/v1beta/interactions를 우선 사용한다. generateContent는 계속 문서화되어 있지만 기존 코드와 호환 gateway를 위한 이전 surface로 구분해야 한다.

아래 요청에서 바꿔야 할 것은 text, aspect_ratio, image_size뿐이다. API 키는 코드에 넣지 않고 GEMINI_API_KEY 환경 변수로 관리한다.

bash
curl -sS -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "input": [{
      "type": "text",
      "text": "서울의 독립 커피 브랜드를 위한 16:9 제품 히어로 이미지. 무광 검정 커피백을 중앙에 두고, 라벨의 한글 상품명은 정확히 보존하며, 따뜻한 아침 창가광과 절제된 나무 배경을 사용한다. 사람, 추가 로고, 가격 문구는 넣지 않는다."
    }],
    "response_format": {
      "type": "image",
      "aspect_ratio": "16:9",
      "image_size": "2K"
    }
  }'

이 예제는 2026년 7월 20일 공식 문서의 field owner를 대조하고 JSON 문법을 검사한 예제다. 이 문서 갱신 과정에서는 task 전용 credential이나 결제 승인이 없었으므로 유료 이미지 생성 호출과 품질 benchmark를 실행하지 않았다.

복사하기 전에 여섯 항목부터 맞춘다

Nano Banana Pro 예제가 실패하는 가장 흔한 이유는 prompt가 나빠서가 아니라 서로 다른 계약을 한 요청에 섞었기 때문이다. 다음 여섯 칸이 모두 같은 문서 owner를 가리켜야 한다.

진단 규칙은 간단하다. endpoint를 먼저 고정하고 나머지 다섯 항목을 그 endpoint 문서에서 다시 가져온다. 모델 ID 하나만 바꿔서는 계약이 이동하지 않는다.

하나의 이미지 작업을 세 가지 표현으로 관리하는 법

“Nano Banana Pro JSON template”이라는 말에는 서로 다른 세 객체가 숨어 있다. 첫째는 팀이 작성한 semantic prompt object, 둘째는 Google에 보내는 HTTP JSON, 셋째는 애플리케이션이 보관하는 YAML 설정이다. Google은 공식 이미지 prompt JSON schema를 정의하지 않는다. JSON 구조는 협업과 검증을 돕지만 이미지 품질 향상을 보장하지 않는다.

1. Semantic prompt object: 사람이 검토하는 계약

다음 객체는 API payload가 아니라 기획 의도를 빠뜨리지 않기 위한 애플리케이션 소유 데이터다.

json
{
  "goal": "한국 커피 브랜드의 데스크톱 제품 히어로 이미지",
  "subject": {
    "product": "무광 검정 커피백",
    "must_preserve": ["한글 상품명", "포장 비율", "전면 라벨 위치"]
  },
  "scene": {
    "composition": "중앙 단일 제품, 넉넉한 좌우 여백",
    "lighting": "따뜻한 아침 창가광",
    "background": "절제된 나무 표면"
  },
  "text_policy": {
    "allowed": ["참조 이미지에 있는 한글 상품명"],
    "forbidden": ["새 슬로건", "가격", "추가 로고"]
  },
  "output": {
    "aspect_ratio": "16:9",
    "image_size": "2K"
  }
}

애플리케이션은 이 값을 자연어 prompt로 렌더링하고 output만 API image setting으로 매핑한다. goal, subject, scene 같은 field를 Google endpoint에 그대로 보내면 unknown-field 400이 날 수 있다.

2. Official JSON: 전송 계약으로 변환

변환기는 semantic object에서 문장을 만들고 허용된 설정만 추린다.

javascript
function toGoogleInteraction(spec) {
  const prompt = [
    spec.goal,
    `주 피사체: ${spec.subject.product}.`,
    `반드시 보존: ${spec.subject.must_preserve.join(", ")}.`,
    `구도: ${spec.scene.composition}.`,
    `조명: ${spec.scene.lighting}.`,
    `배경: ${spec.scene.background}.`,
    `금지: ${spec.text_policy.forbidden.join(", ")}.`,
  ].join(" ");

  return {
    model: "gemini-3-pro-image",
    input: [{ type: "text", text: prompt }],
    response_format: {
      type: "image",
      aspect_ratio: spec.output.aspect_ratio,
      image_size: spec.output.image_size,
    },
  };
}

production에서는 aspect_ratio를 아래 열 개 값으로, image_size를 1K, 2K, 4K로 allowlist 검증한다. 소문자 2k나 문서에 없는 극단 비율을 자동 통과시키지 않는다.

3. App YAML: 저장 형식일 뿐 요청 형식이 아니다

YAML은 사람이 수정하기 편한 설정 파일이다. 공식 Nano Banana Pro endpoint에 application/yaml로 보내는 형식이 아니다.

yaml
route:
  owner: google
  surface: interactions
  model: gemini-3-pro-image

prompt:
  goal: 한국 커피 브랜드의 데스크톱 제품 히어로 이미지
  subject:
    product: 무광 검정 커피백
    must_preserve:
      - 한글 상품명
      - 포장 비율
      - 전면 라벨 위치
  scene:
    composition: 중앙 단일 제품, 넉넉한 좌우 여백
    lighting: 따뜻한 아침 창가광
    background: 절제된 나무 표면
  text_policy:
    forbidden:
      - 새 슬로건
      - 가격
      - 추가 로고

output:
  aspect_ratio: "16:9"
  image_size: 2K

YAML을 읽은 뒤 schema/type 검증, secret 제거, semantic prompt 렌더링, route별 JSON mapping을 거친다. 키를 YAML에 저장하지 말고 환경 변수나 secret manager에서 주입한다.

Interactions 응답을 저장하고 실패를 보존한다

SDK의 단일 이미지 응답은 interaction.output_image shortcut으로 저장할 수 있다. 텍스트와 이미지가 섞인 응답이나 향후 복잡한 output은 steps의 model_output content도 확인해야 한다.

python
from google import genai
import base64

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3-pro-image",
    input="한글 라벨을 보존한 검정 커피백 제품 사진",
    response_format={
        "type": "image",
        "aspect_ratio": "16:9",
        "image_size": "2K",
    },
)

saved = 0
if getattr(interaction, "output_image", None):
    with open("coffee-hero.png", "wb") as f:
        f.write(base64.b64decode(interaction.output_image.data))
    saved += 1

else:
    for step in getattr(interaction, "steps", []) or []:
        if getattr(step, "type", None) != "model_output":
            continue
        for block in getattr(step, "content", []) or []:
            if getattr(block, "type", None) == "image":
                with open(f"coffee-hero-{saved + 1}.png", "wb") as f:
                    f.write(base64.b64decode(block.data))
                saved += 1

if saved == 0:
    raise RuntimeError("이미지 output 없음: 응답 원문, safety 상태, request ID를 보존하세요")

REST를 쓸 때도 먼저 원본 interaction JSON을 안전한 log에 남기고, Google 응답 schema를 기준으로 parser를 만든다. provider의 url, data[0], task_id parser를 재사용하지 않는다. base64 decode 전에 MIME/type을 확인하고, 성공 HTTP status만으로 이미지 생성 성공을 판정하지 않는다.

generateContent는 기존 통합용 호환 surface다

기존 codebase가 contents[].parts[]와 generationConfig를 사용한다면 즉시 버릴 필요는 없다. 다만 새 Google 직접 통합의 기본 설명은 Interactions로 두고, 아래 요청은 migration/compatibility로 라벨링한다.

bash
curl -sS -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{"text": "한글 라벨을 보존한 검정 커피백 제품 사진"}]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "2K"
      }
    }
  }'

Interactions의 response_format.image_size는 snake_case이고, generateContent의 generationConfig.imageConfig.imageSize는 camelCase다. endpoint를 바꾸면서 body와 response parser를 그대로 두는 것이 migration 실패의 전형이다.

PDF와 문서는 두 단계로 처리한다

gemini-3-pro-image의 현재 model card는 입력 modality를 Text/Image로 표시한다. Gemini의 일반 문서 처리 가이드가 PDF를 지원한다고 해서 그 기능이 Pro 이미지 모델에 자동 상속되는 것은 아니다. 따라서 PDF를 Pro 요청의 input에 직접 넣는 예제를 만들면 안 된다.

안전한 흐름은 다음 두 단계다.

1. 문서 이해 단계: document-capable Gemini 모델로 PDF를 분석한다. 일반 문서 경로의 현재 한도는 최대 50 MB 또는 1,000페이지지만, 실제 선택 모델의 region·quota·파일 조건을 다시 확인한다. 필요한 표, 문구, 페이지 번호, 브랜드 규칙을 JSON으로 추출하고 사람이 검증한다.
2. 이미지 생성 단계: 검증된 텍스트와 실제로 필요한 페이지만 PNG/JPEG로 렌더링해 Nano Banana Pro에 Text/Image input으로 전달한다. 페이지 순서, DPI, crop, 색상 프로필을 기록한다.

예를 들어 80페이지 카탈로그를 모두 이미지로 넣지 않는다. 1단계에서 “표지의 로고 규칙, 12페이지의 제품 사진, 37페이지의 컬러 팔레트”를 선택하고 2단계에는 검증된 세 자산만 보낸다. 한글 OCR 오류, 표 셀 순서, PDF의 개인정보를 확인하지 못하면 생성 단계에서 멈춘다. DOCX나 HTML을 단순 text로 바꾸면 layout과 visual context가 사라질 수 있다는 점도 별도로 기록한다.

비율·해상도·참조 이미지 경계를 코드로 고정한다

공식 Pro 전용 표에서 확인된 비율은 열 개다.

1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9

해상도 label은 1K, 2K, 4K이며 K가 대문자다. 4K는 모든 비율에서 4096×4096을 뜻하지 않는다. 예를 들어 공식 16:9 4K 표시는 5504×3072다. generic ImageConfig 문서에 보이는 추가 비율을 Pro 지원으로 확대 해석하지 않는다.

참조 이미지는 최대 14개라는 상한과 category별 안내를 함께 봐야 한다. 현재 가이드는 Pro에서 object 6개, character 5개, style 3개 같은 세부 한도를 제시하면서 다른 문맥에서는 high-fidelity 이미지 5개 제한도 언급한다. “14개면 무엇이든 동일 fidelity”라고 약속하지 말고, 적은 수로 시작해 category와 fidelity를 검증한다.

400·401·404·429·5xx를 route owner별로 푼다

오류 packet에는 timestamp, endpoint, model, project, size, status, request ID, 응답 body, retry 횟수를 남긴다. prompt와 reference image에는 민감 정보가 있을 수 있으므로 support용 log에서는 redaction 정책을 적용한다.

가격, Free Tier, key, quota는 서로 다른 질문이다

2026년 7월 20일 Google 공식 가격표의 Nano Banana Pro 행은 Free Tier를 제공하지 않는다. Standard 이미지 출력은 1K/2K US$0.134, 4K US$0.24이고, Batch/Flex는 각각 US$0.067, US$0.12다. 입력 이미지·텍스트, thinking/text output, grounding, retry는 별도 비용을 만들 수 있다. 공식 billing 문서에 따르면 일부 신규 결제 계정에는 최소 US$10 선결제가 필요할 수 있다.

API key 공식 문서에 따라 key를 무료로 만들 수 있다는 말은 Pro 이미지 출력이 무료라는 뜻이 아니다. AI Studio UI 사용, 소비자 Gemini allowance, provider credit도 각각 다른 계약이다. Google rate limit은 key가 아니라 project 단위로 적용되므로 같은 project에 key를 더 만들어도 quota가 곱해지지 않는다. 실제 RPM/TPM/RPD/IPM은 rate-limit 문서와 AI Studio/project의 현재 limit을 확인한다. quota 증액 판단은 Nano Banana Pro API quota 가이드에서 이어서 볼 수 있다.

laozhang.ai를 선택할 수 있는 조건

공식 Google 직접 연결이 기준 route다. 다만 여러 모델을 한 계정에서 바꾸거나 pay-as-you-go 결제, provider-side logs, 다른 onboarding이 운영상 더 중요하면 laozhang.ai 같은 developer gateway를 검토할 수 있다.

2026년 7월 20일 확인한 laozhang.ai 공개 문서는 provider alias gemini-3-pro-image와 US$0.09/call을 표시했다. OpenAI-compatible chat route는 1:1/1K로 문서화되어 있고, custom ratio와 2K/4K는 provider의 generateContent-compatible route에 속한다. 이것은 Google 공식 endpoint나 가격이 아니라 laozhang.ai 계약이다. provider 문서와 Google Pro 표 사이에는 비율 수·일부 pixel row 충돌도 있으므로 공식 능력 주장은 Google의 열 개 비율을 사용하고, provider 사용자는 live console을 다시 확인해야 한다.

사용 전에는 provider 이미지 문서, console alias, 실제 단가, failed-call 처리, retention/data boundary, 응답 형식을 함께 확인한다. 이 조건 중 하나라도 업무 요구에 맞지 않거나 source owner가 불명확하면 Google 직접 연결을 유지한다. “무제한”, “항상 성공”, “실패 시 무조건 미과금”은 현재 근거가 없으며, 제한 우회 문제는 unrestricted API 주장의 검증 기준으로 분리한다.

배포 전 9분 점검

1. Google 직접 호출인지 provider 호출인지 한 줄로 적는다.
2. endpoint, 인증 header, model ID가 같은 owner인지 확인한다.
3. semantic prompt object를 API allowlist field로 변환한다.
4. JSON과 YAML을 parser로 검사하고 key가 들어 있지 않은지 확인한다.
5. 1K/2K/4K와 열 개 비율만 허용한다.
6. image output과 “이미지 없음” 분기를 모두 처리한다.
7. 429 backoff와 5xx bounded retry에 중복 생성·과금 방지 조건을 둔다.
8. PDF는 문서 분석과 이미지 생성의 두 단계로 나눈다.
9. 가격, project quota, provider console 계약을 launch 당일 다시 확인한다.

핵심 순서는 route 선택 → 여섯 필드 일치 → prompt 변환 → 응답 저장 → 비용·quota 검증이다. 이 순서를 지키면 “공식 문서의 JSON을 복사했는데 왜 안 되지?”라는 문제를 prompt 수정이 아니라 계약 불일치에서 빠르게 찾아낼 수 있다.