Nano Banana 2 개발 문서 완전 공략: 공식 API와 APIYI 연동 2가지 방안 비교

저자 주: Nano Banana 2(gemini-3.1-flash-image-preview) 개발 문서 상세 분석. 구글 공식 API와 APIYI 플랫폼의 2가지 연동 방식을 비교하며, 전체 코드 예시, 파라미터 설정 및 비용 절감 전략을 포함합니다.

Nano Banana 2를 도입하려는 개발자분들을 위해 현재 참고할 수 있는 두 가지 개발 문서가 있습니다. 바로 구글 공식 문서(ai.google.dev/gemini-api/docs/image-generation)와 APIYI 플랫폼 문서(docs.apiyi.com/api-capabilities/nano-banana-2-image)입니다.

두 방식 모두 각기 다른 장점이 있습니다. 공식 문서는 기능이 가장 포괄적이며, APIYI 문서는 연동이 매우 간편하고 가격이 회당 $0.03 수준으로 저렴합니다. 이 글에서는 두 문서의 핵심 내용을 통합 비교하여 여러분에게 가장 적합한 연동 방식을 선택할 수 있도록 도와드릴게요.

핵심 가치: 이 글을 읽고 나면 Nano Banana 2의 전체 API 파라미터, 두 가지 연동 방식의 코드 예시, 그리고 상황별 최적의 선택지를 완벽히 파악하실 수 있습니다.

Nano Banana 2 개발 문서 핵심 파라미터 퀵 체크

가장 중요한 파라미터 설정부터 살펴볼까요? 어떤 방식을 선택하든 이 파라미터들은 공통으로 적용됩니다.

Nano Banana 2가 지원하는 14가지 가로세로 비율

🎯 개발 팁: 1:4, 4:1, 1:8, 8:1은 Nano Banana 2만의 새로운 비율로, Nano Banana Pro에서는 지원하지 않습니다. 앱에서 긴 배너나 인포그래픽 형태의 이미지가 필요하다면 반드시 gemini-3.1-flash-image-preview를 사용해야 합니다.

Nano Banana 2 연동 방법 A: 구글 공식 API

공식 API 기본 호출

구글 공식 API는 Google Gen AI SDK를 사용하며 Python, JavaScript, Go, Java 및 REST를 지원합니다.

from google import genai
from google.genai import types

client = genai.Client()

# 기본 텍스트-이미지 변환
response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents="가을 낙엽 속에서 뒹굴고 있는 치즈 고양이, 따뜻한 색감",
    config=types.GenerateContentConfig(
        response_modalities=['TEXT', 'IMAGE']
    )
)

# 생성된 이미지 추출
for part in response.candidates[0].content.parts:
    if part.inline_data:
        with open("output.png", "wb") as f:
            f.write(part.inline_data.data)

from google import genai
from google.genai import types

client = genai.Client()

# 전체 파라미터 설정: 2K 해상도 + 16:9 와이드 + High 생각 모드
response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents="테크 기업 연간 보고서 표지, 제목 'AI Vision 2026', 딥 블루 톤, 미니멀 스타일",
    config=types.GenerateContentConfig(
        response_modalities=['TEXT', 'IMAGE'],
        image_config=types.ImageConfig(
            aspect_ratio="16:9",
            image_size="2K"
        ),
        thinking_config=types.ThinkingConfig(
            thinking_level="High",
            include_thoughts=True
        )
    )
)

# 응답 분석 (생각 과정 포함)
for part in response.parts:
    if part.thought and part.text:
        print(f"[생각 과정] {part.text}")
    elif part.inline_data:
        with open("report_cover.png", "wb") as f:
            f.write(part.inline_data.data)
        print("이미지가 저장되었습니다.")

공식 API의 Image Search 인터넷 연결 생성

이것은 Nano Banana 2만의 독보적인 기능으로, 생성 전 구글 이미지 검색을 통해 실제 시각적 참고 자료를 가져옵니다.

response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents="2026년형 최신 테슬라 모델 Y, 실버 색상, 도시 거리에 주차된 모습",
    config=types.GenerateContentConfig(
        response_modalities=['TEXT', 'IMAGE'],
        tools=[
            types.Tool(google_search=types.GoogleSearch(
                search_types=types.SearchTypes(
                    web_search=types.WebSearch(),
                    image_search=types.ImageSearch()
                )
            ))
        ]
    )
)

🎯 주의: 이미지 검색(Image Search) 연동 생성에는 표시 요구 사항이 있습니다. 원본 이미지 웹페이지로 연결되는 클릭 가능한 링크를 반드시 제공해야 합니다. 생각(Thinking) 토큰은 추론 과정의 반환 여부와 상관없이 비용이 청구됩니다.

Nano Banana 2 연동 방법 B: APIYI 플랫폼

APIYI 플랫폼 연동 장점

APIYI OpenAI 호환 형식 호출

이미 OpenAI SDK 기반의 코드가 있다면, 단 두 줄만 수정하여 Nano Banana 2를 연동할 수 있습니다.

import openai

client = openai.OpenAI(
    api_key="YOUR_APIYI_KEY",
    base_url="https://vip.apiyi.com/v1"
)

response = client.chat.completions.create(
    model="gemini-3.1-flash-image-preview",
    messages=[{"role": "user", "content": "수묵 산수화, 여백의 미를 살린 구도, 멀리 구름에 둘러싸인 산"}]
)

import requests
import base64

API_KEY = "YOUR_APIYI_KEY"

response = requests.post(
    "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "contents": [{"parts": [{"text": "이커머스 프로모션 포스터, '봄맞이 특가'라는 큰 제목, 레드 테마"}]}],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {
                "aspectRatio": "9:16",
                "imageSize": "2K"
            }
        }
    },
    timeout=300
).json()

# 이미지 디코딩 및 저장
img_data = response["candidates"][0]["content"]["parts"][0]["inlineData"]["data"]
with open("poster.png", "wb") as f:
    f.write(base64.b64decode(img_data))
print("이미지 생성 성공, 비용 약 $0.03")

권장 사항: APIYI(apiyi.com)에서 회원가입 후 API 키를 발급받으면 바로 호출을 시작할 수 있습니다. 플랫폼은 OpenAI 호환 형식과 구글 네이티브 형식의 두 가지 호출 방식을 모두 지원하며, 키 하나로 모든 모델을 전환하여 사용할 수 있습니다.

Nano Banana 2 두 가지 플랜 가격 비교

Nano Banana 2 월간 비용 비교 (일일 1,000장 기준)

APIYI의 회당 $0.03라는 가격은 공식 표준가보다 55% 저렴할 뿐만 아니라, 공식 Batch 반값($0.034)보다도 더 낮습니다. 게다가 실시간으로 결과를 반환하므로 24시간을 기다려야 하는 비동기 처리가 필요 없다는 장점이 있어요.

🎯 비용 절감 팁: APIYI(apiyi.com)를 통해 Nano Banana 2를 호출하면 하루 1,000장 기준 단돈 $30, 월 비용 $900로 이용할 수 있어요. 가입 즉시 무료 테스트 크레딧을 제공하며, API 키 하나로 Nano Banana 2, Pro 및 기타 주요 모델을 모두 지원합니다.

Nano Banana 2 고급 기능 개발 가이드

다회차 대화 이미지 편집

Nano Banana 2는 대화를 통해 동일한 이미지를 지속적으로 수정할 수 있는 기능을 지원해요.

# APIYI + OpenAI 형식의 다회차 편집
messages = [
    {"role": "user", "content": "심플한 스타일의 브랜드 로고 생성, 블루 계열"},
    # 첫 번째 결과 반환 후 계속 편집
    {"role": "assistant", "content": "[첫 번째 생성 결과]"},
    {"role": "user", "content": "색상을 보라색 그라데이션으로 바꾸고, 회사 이름 'TechFlow'를 추가해줘"}
]

response = client.chat.completions.create(
    model="gemini-3.1-flash-image-preview",
    messages=messages
)

Nano Banana 2 참조 이미지 생성

Nano Banana 2 Thinking 모드 선택

🎯 개발 팁: Thinking 토큰은 includeThoughts=true 설정 여부와 관계없이 비용이 발생해요. 추론 과정을 굳이 확인할 필요가 없다면 기본값인 false로 유지하세요. 생성 품질에는 영향을 주지 않으며, 중간 추론 텍스트만 반환되지 않을 뿐입니다.

Nano Banana 2 생성 속도 참고

권장 사항: Nano Banana 2를 호출할 때는 네트워크나 구글의 연산 능력 변동으로 인한 타임아웃 오류를 방지하기 위해 timeout=300(300초) 설정을 권장해요. APIYI(apiyi.com)를 통해 호출하면 더 안정적인 연결을 확보할 수 있습니다.

자주 묻는 질문

요약

Nano Banana 2 개발 문서의 핵심 요점은 다음과 같습니다.

1. 두 가지 솔루션의 각기 다른 장점: 구글 공식 API는 기능이 가장 강력하며(이미지 검색, Thinking, 14장의 참조 이미지), APIYI는 가격이 가장 저렴하고($0.03/회) 연동이 매우 간편합니다.
2. APIYI $0.03 = 공식 가격의 45%: 실시간 응답을 제공하면서도 공식 배치(Batch) 반값($0.034)보다 저렴하며, 24시간을 기다릴 필요가 없습니다.
3. 핵심 파라미터 호환: 4단계 해상도, 14가지 화면 비율, Thinking 모드 등의 파라미터는 두 솔루션 모두에서 공통으로 사용할 수 있습니다.

대부분의 개발자에게는 **APIYI(apiyi.com)**를 통해 Nano Banana 2를 빠르게 연동하는 것을 추천합니다. $0.03/회의 저렴한 가격, OpenAI 호환 형식, 가입 시 제공되는 무료 크레딧을 통해 5분 안에 첫 번째 이미지를 생성할 수 있습니다.

📚 참고 자료

1. 구글 공식 Gemini 이미지 생성 문서: Nano Banana 2 전체 API 참조

   • 링크: ai.google.dev/gemini-api/docs/image-generation
   • 설명: 모든 파라미터, 기능 및 고급 기능에 대한 공식 문서입니다.

2. APIYI Nano Banana 2 문서: 빠른 연동 및 코드 예시

   • 링크: docs.apiyi.com/api-capabilities/nano-banana-2-image
   • 설명: APIYI 플랫폼 연동 가이드로, 가격 정책과 호출 예시를 포함하고 있습니다.

3. Gemini API 공식 가격 정책: 해상도별 상세 가격

   • 링크: ai.google.dev/gemini-api/docs/pricing#gemini-3.1-flash-image-preview
   • 설명: 0.5K/1K/2K/4K 표준가 및 배치(Batch) 가격을 확인할 수 있습니다.

4. Gemini API 속도 제한: Preview 모델 호출 제한

   • 링크: ai.google.dev/gemini-api/docs/rate-limits
   • 설명: Preview 모델의 할당량 제한에 대해 알아봅니다.

작성자: APIYI 기술 팀
기술 교류: 댓글을 통해 여러분의 Nano Banana 2 개발 경험을 공유해 주세요! 더 많은 AI 모델 자료는 APIYI docs.apiyi.com 문서 센터에서 확인하실 수 있습니다.