nano banana pro api image config no size parameter ko image 0 图示

Nano Banana Pro 모델 호출 시 주의사항: imageConfig가 해상도를 결정하므로 size 파라미터를 추가하지 마십시오

작성자:

많은 개발자가 Nano Banana Pro API(Google gemini-3-pro-image-preview 모델 대응)를 처음 호출할 때 공통적으로 겪는 실수가 있습니다. 바로 OpenAI/DALL-E 시대의 size: "1024x1024" 파라미터를 그대로 사용하는 것인데요. 이 경우 이미지 해상도가 전혀 바뀌지 않거나, 400 에러가 발생하거나, 서버에서 파라미터가 무시되는 현상이 나타납니다.

이는 Nano Banana Pro API 호출 시 가장 자주 발생하는 "고빈도 버그"입니다. 올바른 방법은 imageConfig.imageSize(선명도 1K/2K/4K)와 imageConfig.aspectRatio(비율 1:1/16:9/…) 두 파라미터를 조합하여 사용하는 것이며, size 필드는 절대 전달하지 마세요. 본 글에서는 600자 분량으로 이 문제를 깔끔하게 정리하고, 바로 복사해서 사용할 수 있는 curl / Python / Node.js 코드를 제공합니다.

nano-banana-pro-api-image-config-no-size-parameter-ko 图示

Nano Banana Pro API 호출 핵심 포인트

코드를 작성하기 전에 다음 세 가지 철칙을 기억하세요. 이 세 가지만 이해하면 본문의 90%는 이미 파악하신 겁니다.

  1. 모델 이름 대응: Nano Banana Pro = gemini-3-pro-image-preview(Gemini 3 Pro Image라고도 함)로, Google Gemini 3 시리즈의 이미지 생성/편집 모델입니다. 시중에서 Nano Banana 2라고 부르기도 하지만 본질적으로 같은 모델입니다.
  2. Gemini 네이티브 프로토콜 사용: OpenAI Chat Completions 호환 프로토콜이 아닙니다. 요청 경로는 :generateContent이며, 요청 본문의 최상위 필드는 contents + generationConfig입니다. messages나 OpenAI 스타일의 size 필드는 존재하지 않습니다.
  3. 해상도 = imageSize × aspectRatio: imageSize는 선명도 단계(512 / 1K / 2K / 4K)를 제어하고, aspectRatio는 화면 비율(1:1 / 16:9 / 9:16 / …)을 제어합니다. 이 두 가지가 결합되어 최종 출력 픽셀이 결정됩니다.

📌 한 줄 요약: Gemini 프로토콜로 Nano Banana Pro를 호출할 때는 OpenAI의 size: "1024x1024" 습관을 완전히 버리세요. APIYI(apiyi.com)의 Nano Banana Pro 엔드포인트는 Gemini 네이티브 프로토콜을 완벽하게 지원하므로, Google 공식 문서의 imageConfig 작성 방식이 APIYI에서도 그대로 적용됩니다.

Nano Banana Pro 핵심 파라미터 요약

파라미터 위치 역할 값 예시
imageSize generationConfig.imageConfig 선명도 단계 "512" / "1K" / "2K" / "4K"
aspectRatio generationConfig.imageConfig 화면 비율 "1:1" / "16:9" / "9:16" / "4:3" 등
responseModalities generationConfig 출력 모달리티 ["IMAGE"] (필수)
contents[].parts[].text contents 텍스트 프롬프트 자유 텍스트
contents[].parts[].inline_data contents 입력 이미지(base64) mime_type 및 data 포함

⚠️ 표에 없는 size 필드: Gemini 프로토콜에서 유효한 파라미터가 아니므로 절대 전달하지 마세요.

왜 size 파라미터를 추가하면 안 될까요? 프로토콜 계층의 이유

이 글에서 가장 중요한 섹션입니다. 세 가지 측면에서 이 문제를 확실하게 짚어보겠습니다.

프로토콜 계층: Gemini와 OpenAI는 서로 다른 독립적인 규격입니다

OpenAI의 이미지 API(DALL-E 2/3, gpt-image-1)는 최상위 size: "1024x1024" 문자열 파라미터를 사용합니다. 반면, Google Gemini 3 이미지 API는 중첩된 imageConfig 객체를 사용하도록 설계되어 있어 두 규격은 서로 완전히 독립적입니다. Nano Banana Pro는 Gemini 네이티브 프로토콜을 따르므로 다음 사항을 주의해야 합니다.

  • ❌ size: "1024x1024" —— Gemini 프로토콜에는 이 필드가 없습니다.
  • ❌ size: "1K" —— 이 필드도 없습니다.
  • ❌ n: 4 —— OpenAI처럼 "한 번에 N장을 생성"하는 필드가 없습니다.
  • ✅ imageConfig.imageSize: "1K" —— 올바른 방식입니다.
  • ✅ imageConfig.aspectRatio: "16:9" —— 올바른 방식입니다.

동작 계층: size를 추가로 전달하면 어떻게 될까요?

서버 측 처리는 보통 세 가지 경우로 나뉘는데, 어느 것도 여러분이 원하는 결과는 아닐 것입니다.

  1. 조용히 무시됨: 상위 게이트웨이가 알 수 없는 필드로 간주해 버립니다. 여러분은 적용된 줄 알겠지만, 실제로는 기본값인 1K 1:1로 출력됩니다.
  2. 400 에러 발생: 엄격한 스키마 검증을 거치는 게이트웨이의 경우, 알 수 없는 필드가 포함되었다며 요청을 즉시 거부합니다.
  3. 과금/라우팅 영향: 일부 프록시 계층은 size를 라우팅 신호로 오해하여 잘못된 엔드포인트 버전으로 연결할 수 있습니다.

엔지니어링 계층: 유지보수를 어렵게 만드는 코드 부채

많은 팀이 OpenAI, Gemini, Stability 등 여러 API를 하나의 호출 계층으로 묶으면서 습관적으로 "공용 size 필드"를 재사용하곤 합니다. 겉보기엔 깔끔해 보이지만, 실제로는 버그의 온상입니다. Nano Banana Pro와 같은 Gemini 네이티브 인터페이스를 호출할 때는 별도의 변환 경로를 구성하는 것을 권장합니다. 원본 size를 그대로 전달하지 말고, imageConfig.imageSize와 imageConfig.aspectRatio로 명시적으로 매핑하세요.

💡 제안: APIYI(apiyi.com)를 통해 Nano Banana Pro를 호출할 때는 간단한 파라미터 변환 함수를 작성하세요. 팀에서 흔히 쓰는 "1024x1024" 같은 문자열을 imageSize: "1K"와 aspectRatio: "1:1"로 분리하여, 근본적으로 혼용 문제를 방지하는 것이 좋습니다.

imageSize × aspectRatio 전체 대조표

nano-banana-pro-api-image-config-no-size-parameter-ko 图示

imageSize 단계별 구분 및 과금

imageSize 대략적인 해상도 상한 출력 토큰 단가(참고) 추천 상황
"512" 512×512 수준 낮음 가장 저렴 썸네일 / 초안
"1K" 1024×1024 수준 ~1120 ≈ $0.134 기본 추천
"2K" 2048×2048 수준 ~1120 ≈ $0.134 고화질 포스터
"4K" 4096×4096 수준 ~2000 ≈ $0.24 (약 80% 비쌈) 인쇄용

💰 비용 안내: 4K는 1K/2K보다 약 80% 비싸므로, 무조건 4K를 사용하는 것은 지양하세요. 대부분의 웹/앱 환경에서는 1K로 충분하며, 초고화질이 필요한 경우에만 4K를 사용하세요. 정확한 최신 단가는 APIYI(apiyi.com) 공식 홈페이지의 가격표를 기준으로 합니다.

aspectRatio 지원 목록

비율 용도
"1:1" 프로필 사진 / 소셜 미디어 정사각형
"16:9" 가로형 영상 썸네일 / 데스크탑 배경화면
"9:16" 세로형 숏폼 영상 / 모바일 배경화면
"4:3" 일반 가로 사진
"3:4" 일반 세로 사진
"3:2" / "2:3" DSLR 표준 비율
"4:5" / "5:4" 인스타그램 게시물
"21:9" 울트라 와이드 영화 느낌
"1:4" / "4:1" 긴 배너
"1:8" / "8:1" 극단적인 긴 배너 특수 용도

일반적인 조합 → 최종 픽셀 매핑

imageSize aspectRatio 대략적인 출력 픽셀
1K 1:1 1024 × 1024
1K 16:9 1024 × 576
1K 9:16 576 × 1024
2K 1:1 2048 × 2048
2K 16:9 2048 × 1152
4K 1:1 4096 × 4096
4K 9:16 2304 × 4096
4K 21:9 4096 × 1728

참고: 실제 픽셀은 모델 내부의 정렬 규칙에 따라 ±N 픽셀 정도 미세 조정될 수 있으나, 시각적인 해상도 품질에는 영향을 주지 않습니다.

Nano Banana Pro API 올바른 호출 코드

세 가지 프로그래밍 언어로 작성된 최소 실행 가능 예제를 준비했습니다. 모든 예제는 동일한 작업을 수행합니다: 원본 이미지 1장 + 프롬프트 입력 → 1K 해상도, 1:1 비율로 이미지 1장 출력.

curl 버전 (가장 직관적이며 디버깅에 용이함)

curl -X POST \
  "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer 당신의-APIYI-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {
          "inline_data": {
            "mime_type": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAA...(원본 이미지 base64)"
          }
        },
        {
          "text": "이 이미지를 사이버펑크 스타일로 변경하고 인물의 자세를 유지해줘"
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "1K"
      }
    }
  }'

Python 버전 (SDK 의존 없이 requests 사용 권장)

import base64
import requests

# 이미지 파일을 읽어 base64로 인코딩
with open("input.png", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode()

resp = requests.post(
    "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
    headers={
        "Authorization": "Bearer 당신의-APIYI-KEY",
        "Content-Type": "application/json",
    },
    json={
        "contents": [{
            "parts": [
                {"inline_data": {"mime_type": "image/png", "data": img_b64}},
                {"text": "이 이미지를 사이버펑크 스타일로 변경하고 인물의 자세를 유지해줘"},
            ]
        }],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {
                "aspectRatio": "1:1",
                "imageSize": "1K",
            },
        },
    },
    timeout=120,
)

data = resp.json()
out_b64 = data["candidates"][0]["content"]["parts"][0]["inline_data"]["data"]
with open("output.png", "wb") as f:
    f.write(base64.b64decode(out_b64))

Node.js 버전 (네이티브 fetch 사용, SDK의 imageConfig 누락 방지)

import fs from "node:fs";

const imgB64 = fs.readFileSync("input.png").toString("base64");

const resp = await fetch(
  "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer 당신의-APIYI-KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      contents: [{
        parts: [
          { inline_data: { mime_type: "image/png", data: imgB64 } },
          { text: "이 이미지를 사이버펑크 스타일로 변경하고 인물의 자세를 유지해줘" },
        ],
      }],
      generationConfig: {
        responseModalities: ["IMAGE"],
        imageConfig: {
          aspectRatio: "1:1",
          imageSize: "1K",
        },
      },
    }),
  },
);

const data = await resp.json();
const outB64 = data.candidates[0].content.parts[0].inline_data.data;
fs.writeFileSync("output.png", Buffer.from(outB64, "base64"));

🔧 왜 네이티브 fetch / requests 사용을 강력히 권장하나요?: 일부 SDK(초기 LiteLLM, Google Node SDK 일부 버전 포함)는 imageConfig를 알 수 없는 필드로 간주하여 필터링해버리며, 이로 인해 imageSize/aspectRatio 설정이 무시됩니다. JSON 요청 본문을 직접 구성하면 이러한 문제를 100% 피할 수 있습니다. SDK를 꼭 써야 한다면, 최신 버전으로 업데이트하고 요청 인터셉터에서 최종 body를 출력해 확인하세요.

호출 시 주의사항: 6가지 흔한 실수

nano-banana-pro-api-image-config-no-size-parameter-ko 图示

실수 1: OpenAI 스타일의 size 파라미터 추가

// ❌ 잘못된 예: size는 Gemini 프로토콜의 유효한 필드가 아닙니다.
{
  "contents": [...],
  "size": "1024x1024",
  "generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" } }
}

// ✅ 올바른 예: size를 삭제하고 imageConfig만 유지하세요.
{
  "contents": [...],
  "generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" }, "responseModalities": ["IMAGE"] }
}

실수 2: 필드명에 밑줄(snake_case) 사용

Gemini 3 이미지 인터페이스의 imageConfig 필드명은 **카멜 케이스(camelCase)**입니다: imageSize, aspectRatio, responseModalities. 흔한 오타:

  • ❌ image_size / aspect_ratio / response_modalities
  • ✅ imageSize / aspectRatio / responseModalities

실수 3: SDK가 imageConfig를 소리 없이 삭제함

앞서 언급했듯, 일부 SDK 버전은 알 수 없는 필드를 필터링합니다. 확인 방법:

  1. SDK 호출 전후로 실제 HTTP body를 출력해보기
  2. mitmproxy / Charles를 사용하여 실제 나가는 요청을 캡처하기
  3. imageConfig가 사라졌다면, 네이티브 fetch / requests로 전환하기

실수 4: responseModalities 누락

// ❌ responseModalities를 설정하지 않으면 이미지가 아닌 텍스트만 반환될 수 있습니다.
{ "generationConfig": { "imageConfig": {...} } }

// ✅ 반환 모달리티에 IMAGE가 포함됨을 명시해야 합니다.
{ "generationConfig": { "imageConfig": {...}, "responseModalities": ["IMAGE"] } }

실수 5: 429 제한 발생 시 지수 백오프(Exponential Backoff) 미적용

상위 서버 부하가 높을 때 다음과 같은 에러가 발생합니다:

{ "error": { "message": "현재 그룹의 상위 서버 부하가 포화 상태입니다. 잠시 후 다시 시도해주세요.", "type": "upstream_error", "code": 429 } }

이때는 즉시 재시도하지 말고 지수 백오프 재시도(3초 → 6초 → 12초)를 수행해야 합니다. 그렇지 않으면 혼잡이 가중됩니다:

import time

for attempt in range(3):
    resp = requests.post(url, json=body, headers=headers, timeout=120)
    if resp.status_code != 429:
        break
    time.sleep(3 * (2 ** attempt))   # 3초, 6초, 12초

실수 6: 여러 참조 이미지의 위치 오류

Nano Banana Pro는 다중 이미지 입력(원본 이미지 + 다수의 참조 이미지)을 지원합니다. 모든 이미지는 parts 배열 내의 여러 inline_data 항목으로 들어가야 하며, 텍스트 프롬프트는 배열의 마지막에 위치해야 합니다:

// ✅ 올바른 예: 이미지는 앞쪽에, 텍스트는 마지막에
"parts": [
  { "inline_data": { "mime_type": "image/png", "data": "원본 이미지 base64" } },
  { "inline_data": { "mime_type": "image/png", "data": "참조 이미지1 base64" } },
  { "inline_data": { "mime_type": "image/png", "data": "참조 이미지2 base64" } },
  { "text": "원본 이미지의 스타일을 참조 이미지1의 색감으로 변경하고, 구도는 참조 이미지2를 참고해줘" }
]

🧰 요약: 위의 6가지 항목을 내부 "Nano Banana Pro 체크리스트"로 만들어 새로운 호출을 구현할 때마다 확인하세요. 90% 이상의 사소한 버그를 방지할 수 있습니다. APIYI(apiyi.com)의 Nano Banana Pro 엔드포인트는 Gemini 프로토콜을 완전히 따르므로 모든 팁이 동일하게 적용됩니다.

사용자 호출 프로세스 분해: 어디서 가장 많이 오류가 발생할까?

nano-banana-pro-api-image-config-no-size-parameter-ko 图示

많은 독자분들이 공유해주신 호출 로그를 보면 여러분의 프로세스와 거의 일치합니다:

프론트엔드 POST /api/generate
  → server.js 파라미터 추출
  → modelKey.startsWith('nano-banana') 확인
  → _generateViaGemini() 요청 본문 구성
  → POST https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent
  → 반환 / 재시도

가장 오류가 발생하기 쉬운 지점들을 단계별로 짚어보겠습니다:

단계 흔한 문제 제안
프론트엔드 파라미터 습관적으로 size: "1024x1024" 전달 imageSize + aspectRatio 두 필드로 분리하여 전달
server.js 본문 구성 Gemini에 size 필드를 그대로 전달하는 실수 구성 함수에서 명시적으로 size 필드 삭제
모델 라우팅 nano-banana를 3 Pro가 아닌 1.5로 라우팅 모델명을 gemini-3-pro-image-preview로 정확히 기재
요청 전송 스키마 검증이 포함된 SDK 버전 사용 네이티브 fetch 사용 또는 최신 SDK로 업데이트
오류 처리 429 에러 발생 시 즉시 사용자에게 반환 지수 백오프(Exponential Backoff)로 3회 재시도
응답 파싱 기본 text로 추출 시도(이미지 결과인 경우) 올바른 경로 candidates[0].content.parts[0].inline_data.data 사용

📋 한 줄 요약: 공유해주신 프로세스 구조는 정확합니다. "파라미터 추출" 단계에서 불필요한 size 필드를 제거하고, server.js에서 이를 다시 generationConfig 외부에 포함하지 않는지만 확인하면 전체 경로가 깔끔해집니다.

FAQ 자주 묻는 질문

Q1: Nano Banana Pro와 Nano Banana 2는 같은 것인가요?
네, 같습니다. 커뮤니티에서는 Gemini 3 Pro Image (gemini-3-pro-image-preview)를 Nano Banana 2 또는 Nano Banana Pro라고 부르기도 하는데, 세 가지 명칭 모두 동일한 모델을 의미합니다. APIYI(apiyi.com)에서 사용하는 모델명은 공식 문서를 기준으로 합니다.

Q2: imageConfig를 전달하지 않으면 어떻게 되나요?
모델 내부 기본값(보통 1K + 1:1)으로 출력됩니다. 해상도에 크게 신경 쓰지 않는다면 생략해도 되지만, 화면 비율에 요구사항이 있다면 반드시 imageConfig를 명시적으로 전달해야 합니다.

Q3: Gemini 프로토콜을 사용하면서 OpenAI처럼 size를 전달할 수 있나요?
안정적으로 작동하지 않습니다. Gemini 프로토콜에는 size 필드가 없으므로, 혼용할 경우 예상치 못한 동작이 발생합니다. imageConfig.imageSize + imageConfig.aspectRatio를 사용하는 것이 가장 안전합니다.

Q4: imageSize를 4K로 설정하면 화질이 무조건 더 좋은가요?
화질 디테일은 풍부해지지만 비용이 거의 두 배(~$0.24 vs $0.134)로 늘어나며, 생성 시간도 길어집니다. 웹/앱용 이미지는 보통 1K나 2K로도 충분합니다. 실제 비즈니스 이미지를 테스트해보고 육안으로 비교한 뒤 결정하는 것을 추천합니다.

Q5: APIYI(apiyi.com)를 통해 Nano Banana Pro를 호출하는 것과 Google 공식 API를 직접 호출하는 것의 차이는 무엇인가요?
APIYI는 OpenAI 스타일의 통합 인증(Bearer Token) + 국내 접속 가능 엔드포인트 + 통합 과금 기능을 제공하며, 호출 프로토콜 자체는 Gemini 네이티브 형식을 그대로 따릅니다. 즉, Google 공식 문서에서 확인한 imageConfig / aspectRatio / responseModalities 설정은 APIYI(apiyi.com)에서도 동일하게 적용됩니다.

Q6: imageSize를 "2K"로 설정했는데 왜 1K로 출력되나요?
가장 흔한 원인 3가지: (1) 알 수 없는 필드를 필터링하는 SDK를 사용 중임, (2) 필드명을 image_size로 잘못 기재함, (3) generationConfig 중첩 구조를 잘못 작성함. 네트워크 패킷을 캡처하여 본문이 규격에 맞는지 먼저 확인한 후 서버 측을 점검하세요.

Q7: 상위 429 제한이 걸리면 어떻게 하나요?
지수 백오프 재시도(3초/6초/12초)를 구현하세요. 비즈니스상 지연 시간에 민감하다면 APIYI(apiyi.com) 워크스페이스에서 그룹을 전환하거나 독립적인 할당량을 신청하는 것을 고려하세요. 무한 루프를 돌며 즉시 재시도하는 것은 절대 금물입니다. 제한 정책에 의해 계속 차단될 수 있습니다.

Q8: 다중 이미지 입력에 개수 제한이 있나요?
Gemini 3 image 인터페이스는 단일 요청의 총 이미지 크기에 제한이 있습니다(보통 MB 단위, 구체적인 수치는 공식 문서 참고). 참조 이미지는 4~5장 이내로 제한하고, 각 이미지는 적절한 크기로 조절(resize 후 base64 변환)하는 것이 좋습니다. 그렇지 않으면 413 에러나 타임아웃이 발생할 수 있습니다.

요약: "해상도 2파라미터 방식"을 근육 기억에 새기세요

딱 한 문장만 기억해야 한다면 바로 이것입니다:

Nano Banana Pro의 최종 출력 해상도 = imageConfig.imageSize × imageConfig.aspectRatio입니다. 더 이상 OpenAI 스타일의 size 필드를 전달하지 마세요.

전체 체크리스트:

  • ✅ 모델명: gemini-3-pro-image-preview
  • ✅ 엔드포인트: /v1beta/models/.../generateContent
  • ✅ generationConfig.imageConfig.imageSize ∈ 512 / 1K / 2K / 4K
  • ✅ generationConfig.imageConfig.aspectRatio ∈ 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 21:9 / …
  • ✅ generationConfig.responseModalities에 반드시 "IMAGE"가 포함되어야 함
  • ✅ 다중 이미지 입력은 parts 배열에 넣고, 텍스트 프롬프트는 마지막에 배치
  • ✅ 429 제한 발생 시 지수 백오프(3초/6초/12초) 적용
  • ❌ size: "1024x1024"를 전달하지 마세요
  • ❌ image_size / aspect_ratio라고 쓰지 마세요 (snake_case는 틀린 방식입니다)
  • ❌ 알 수 없는 필드를 필터링해 줄 것이라는 구형 SDK를 믿지 마세요. 먼저 패킷을 캡처하여 확인하세요.

📢 마지막 한 마디: APIYI(apiyi.com)를 통해 Nano Banana Pro를 연동 중이라면, 본문에 제공된 curl / Python / Node.js 코드 템플릿을 그대로 복사해서 사용하세요. 모든 파라미터는 Gemini 네이티브 프로토콜을 완벽히 준수하므로, 복사 붙여넣기 → 키 변경 → 실행 순서로 바로 해결됩니다.

작성자: APIYI Team · AI 대규모 언어 모델 API 호출 베스트 프랙티스 정리 · apiyi.com

댓글 남기기