Nano Banana Pro 다중 턴 대화 이미지 생성 API 실전: 3단계로 컨텍스트 이미지 생성 구축하기

작성자 주: Nano Banana Pro (gemini-3-pro-image-preview) 다중 턴 대화형 이미지 생성 API의 필드 구조, contents 배열 구성, thoughtSignature 메커니즘 및 실전 코드에 대해 깊이 있게 분석합니다.

많은 개발자가 Nano Banana Pro를 처음 도입할 때 공통적으로 겪는 혼란이 있습니다. gemini.google.com 웹에서는 "배경을 황혼으로 바꿔줘", "고양이 한 마리 추가해줘"라고 연속해서 질문하면 모델이 이전 이미지를 완벽하게 기억하는데, 공식 API를 호출하면 모델이 마치 기억상실증에 걸린 것처럼 아무것도 기억하지 못한다는 점입니다. 그 이유는 Gemini API 자체가 상태를 가지지 않는(Stateless) 구조이기 때문이며, 다중 턴 컨텍스트는 호출하는 측에서 직접 구성해야 합니다. 이 글에서는 Nano Banana Pro 다중 턴 대화형 이미지 생성 API의 핵심 필드, Python SDK 및 REST 구현 방식, 그리고 중요한 thoughtSignature 메커니즘을 상세히 설명하여, 웹 버전처럼 자연스러운 컨텍스트 기반 이미지 생성 환경을 3단계로 구축하도록 도와드리겠습니다.

핵심 가치: 이 글을 읽고 나면 contents 배열을 올바르게 구성하는 방법, 자신의 애플리케이션에서 "이전 이미지를 기반으로 수정"하는 다중 턴 워크플로우를 구현하는 방법, 그리고 "이미지 망각", "토큰 낭비", "시그니처 유실"이라는 3대 함정을 피하는 방법을 마스터하게 됩니다.

Nano Banana Pro 다중 턴 대화형 이미지 생성 핵심 요점

다중 턴 대화형 이미지 생성과 웹 버전 Agent의 본질적 차이

gemini.google.com은 Google이 공식적으로 구축한 Agent 애플리케이션입니다. 이 서비스는 프론트엔드에서 전체 "대화 상태"(각 턴의 텍스트, 생성된 이미지, 사고 서명 포함)를 유지하며, 사용자가 새로운 메시지를 입력할 때마다 Agent가 모든 기록을 한꺼번에 패키징하여 하위 모델로 전송합니다. 이것이 바로 웹 환경의 경험이 매끄러운 이유입니다. 모든 "기억" 작업을 Agent가 도맡아 처리하기 때문이죠.

반면, generateContent API를 직접 호출하면 "가공되지 않은" 모델 호출 인터페이스를 받게 됩니다. 모든 HTTP 요청은 독립적인 추론이며, 모델은 이전 대화에 대해 전혀 알지 못합니다. 웹 버전의 다중 턴 경험을 재현하려면 본질적으로 코드 내에서 직접 Agent를 구현해야 합니다. 이전 user 메시지, model 응답(이미지 및 서명 포함)을 규격에 맞춰 contents에 채워 넣고 요청을 보내야 하는 것입니다.

Nano Banana Pro 다중 턴 대화형 이미지 생성: 필드 구조 상세 가이드

contents 배열의 핵심 규격

contents는 Gemini API에서 대화 기록을 표현하는 표준 필드입니다. 이는 JSON 배열로 구성되며, 각 요소는 한 턴의 발화를 나타냅니다.

완성된 2턴 대화 요청 본문은 다음과 같습니다:

{
  "contents": [
    {"role": "user", "parts": [{"text": "해변을 달리는 골든 리트리버 한 마리를 생성해 줘"}]},
    {"role": "model", "parts": [
      {"inline_data": {"mime_type": "image/png", "data": "<첫 번째 생성 이미지 base64>"}},
      {"thought_signature": "<암호화 서명>"}
    ]},
    {"role": "user", "parts": [{"text": "배경을 황혼 무렵으로 바꿔 줘"}]}
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
  }
}

이미지 전달 방식 2가지

두 번째 턴 요청 시, 모델은 첫 번째 턴에서 생성된 이미지를 반드시 '확인'할 수 있어야 합니다. Nano Banana Pro는 두 가지 전달 방식을 지원합니다.

# 방식 1: inline_data 내장 base64 (작은 이미지에 적합, 간단하고 직관적임)
{
    "inline_data": {
        "mime_type": "image/png",
        "data": base64.b64encode(image_bytes).decode()
    }
}

# 방식 2: file_data를 통한 Files API 업로드 리소스 참조 (큰 이미지나 재사용 시 적합)
{
    "file_data": {
        "mime_type": "image/png",
        "file_uri": "files/abc123xyz"
    }
}

핵심 팁: inline_data는 직접 호출 시 가장 많이 쓰이는 방식으로 일회성 작업에 적합합니다. file_data 참조 방식은 여러 턴에서 동일한 대용량 이미지를 재사용해야 할 때 요청 본문 크기와 업로드 비용을 크게 줄여줍니다.

Nano Banana Pro 다중 턴 대화형 이미지 생성: 빠른 시작

초간단 예제 (Python SDK 자동 관리)

공식 Python SDK를 사용하면 단 10줄의 코드로 구현할 수 있습니다.

from google import genai

client = genai.Client(api_key="YOUR_API_KEY")
chat = client.chats.create(model="gemini-3-pro-image-preview")

# 1턴: 초기 이미지 생성
r1 = chat.send_message("해변을 달리는 골든 리트리버 한 마리를 생성해 줘")

# 2턴: 첫 번째 이미지를 기반으로 편집 (chat 객체가 자동으로 기록을 유지함)
r2 = chat.send_message("배경을 황혼 무렵으로 바꾸고, 날아다니는 갈매기 한 마리를 추가해 줘")

# 3턴: 추가 수정
r3 = chat.send_message("강아지 색깔을 짙은 갈색으로 바꿔 줘")

chat 객체는 전체 contents 목록(각 턴의 thoughtSignature 포함)을 내부적으로 관리하므로, 개발자가 필드 세부 사항을 일일이 신경 쓸 필요가 없습니다. send_message를 호출할 때마다 이전 기록이 자동으로 포함되어 전송됩니다.

import openai
import base64

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

# 로컬 messages 목록 유지 (contents 개념과 동일)
messages = [
    {"role": "user", "content": "해변을 달리는 골든 리트리버 한 마리를 생성해 줘"}
]

# 1턴
response1 = client.chat.completions.create(
    model="gemini-3-pro-image-preview",
    messages=messages
)
img1_url = response1.choices[0].message.content  # 이미지 URL 또는 base64 추출

# 모델 응답을 기록에 추가
messages.append({"role": "assistant", "content": img1_url})

# 2턴: 새로운 지시사항 추가
messages.append({"role": "user", "content": "배경을 황혼 무렵으로 바꿔 줘"})
response2 = client.chat.completions.create(
    model="gemini-3-pro-image-preview",
    messages=messages
)

# 3턴 추가...
messages.append({"role": "assistant", "content": response2.choices[0].message.content})
messages.append({"role": "user", "content": "날아다니는 갈매기 한 마리를 추가해 줘"})
response3 = client.chat.completions.create(
    model="gemini-3-pro-image-preview",
    messages=messages
)

제안: 다중 턴 편집 시에는 SDK의 chat 객체를 사용하거나 로컬 messages 목록을 유지하여 매번 수동으로 contents를 조합하는 번거로움을 피하세요. APIYI(apiyi.com)에서 무료 크레딧을 등록해 SDK로 먼저 테스트해 본 뒤, REST API 최적화를 고려해 보시기 바랍니다.

Nano Banana Pro 다중 대화 이미지 생성 REST 수동 구성

SDK를 사용하지 않는 순수 REST 구현

서버 중계, ComfyUI 노드, 로우코드 플랫폼 등 특정 환경에서는 공식 SDK를 사용할 수 없어 REST 요청을 직접 구성해야 할 때가 있습니다. 다음은 전체 curl 호출 예시입니다.

# 1단계: 텍스트 명령으로 이미지 생성
curl -X POST \
  "https://vip.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "해변을 달리는 골든 리트리버를 생성해줘"}]}
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"]
    }
  }'

# 응답에는 parts[0].inline_data.data (base64 이미지)
# 및 parts[0].thought_signature가 포함됩니다.

두 번째 요청 시에는 첫 번째 모델 응답 전체(이미지 및 서명 포함)를 contents에 그대로 다시 넣어야 합니다:

curl -X POST \
  "https://vip.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "해변을 달리는 골든 리트리버를 생성해줘"}]},
      {"role": "model", "parts": [
        {"inline_data": {"mime_type": "image/png", "data": "<첫 번째 응답의 base64>"}},
        {"thought_signature": "<첫 번째 응답의 signature>"}
      ]},
      {"role": "user", "parts": [{"text": "배경을 황혼 무렵으로 바꿔줘"}]}
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"]
    }
  }'

세 가지 호출 방식 비교

데이터 설명: 위 그림은 에이전트 자동 관리와 API 수동 관리의 핵심 차이를 보여줍니다. APIYI(apiyi.com) 플랫폼을 통해 두 가지 호출 방식의 실제 성능 차이를 직접 비교해 보세요.

Nano Banana Pro 다중 턴 대화 이미지 생성 thoughtSignature 메커니즘

thoughtSignature란 무엇인가?

thoughtSignature는 Gemini 3 시리즈에 도입된 '암호화된 사고 서명(Encrypted Thought Signature)'입니다. 이는 모델이 자신의 내부 추론 상태를 압축하여 인코딩한 데이터로, 사람이 직접 읽을 수는 없지만 모델이 다음 턴에서 이를 통해 컨텍스트를 빠르게 복구할 수 있게 해줍니다. 주요 역할은 다음과 같습니다.

• 세부 결정 사항 유지: 예를 들어 첫 번째 턴에서 모델이 '밝은 톤'을 사용하기로 결정했다면, 두 번째 턴에서 서명을 통해 이 스타일을 그대로 계승합니다.
• 일관성 향상: 다중 턴 편집 과정에서 캐릭터, 장면, 구도가 안정적으로 유지됩니다.
• 토큰 절약: 프롬프트에 "기존 스타일 유지"와 같은 문구를 반복해서 입력할 필요가 없습니다.

서명(signature)을 반드시 포함해야 하는 경우

실전: 서명을 수동으로 관리하는 코드 패턴

import requests
import base64
import json

API_BASE = "https://vip.apiyi.com/v1beta"
MODEL = "gemini-3-pro-image-preview"
HEADERS = {
    "x-goog-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

class NanoBananaChat:
    """contents + signature를 수동으로 관리하는 초간단 채팅 클라이언트"""
    def __init__(self):
        self.contents = []

    def send(self, text: str, attach_image_b64: str = None) -> dict:
        # 이번 턴의 사용자 메시지 구성
        user_parts = [{"text": text}]
        if attach_image_b64:
            user_parts.append({
                "inline_data": {"mime_type": "image/png", "data": attach_image_b64}
            })
        self.contents.append({"role": "user", "parts": user_parts})

        # 요청 전송
        resp = requests.post(
            f"{API_BASE}/models/{MODEL}:generateContent",
            headers=HEADERS,
            json={
                "contents": self.contents,
                "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
            }
        ).json()

        # 모델 응답(서명 포함)을 그대로 contents에 추가
        model_parts = resp["candidates"][0]["content"]["parts"]
        self.contents.append({"role": "model", "parts": model_parts})
        return model_parts

# 사용 예시
chat = NanoBananaChat()
parts1 = chat.send("해변을 달리는 골든 리트리버 생성")
parts2 = chat.send("장면을 황혼 무렵으로 변경")  # 자동으로 기록과 서명 포함
parts3 = chat.send("날아다니는 갈매기 한 마리 추가")

최적화 팁: APIYI(apiyi.com)를 통해 연동할 경우, 플랫폼 레이어에서 thought_signature 필드를 그대로 전달하므로 개발자는 "전체 모델 parts 배열을 contents에 추가"하는 작업만 신경 쓰면 되며, 서명의 구체적인 내용을 알 필요는 없습니다.

Nano Banana Pro 다중 턴 대화 이미지 생성 실전 시나리오

시나리오 1: 점진적 브랜드 이미지 디자인

마케팅 팀의 흔한 요구사항입니다. 제품 컨셉 이미지 하나를 바탕으로 문구, 색상, 레이아웃을 단계별로 조정합니다. 다중 턴 대화 이미지 생성 API의 장점은 매번 "증분 변화"만 설명하면 되므로, 이미지 전체를 처음부터 다시 설명할 필요가 없다는 점입니다.

chat = client.chats.create(model="gemini-3-pro-image-preview")

chat.send_message("진한 파란색 그라데이션 배경의 커피 브랜드 포스터 디자인, 왼쪽에 제품 배치")
chat.send_message("제목 문구를 'Awaken Your Morning'으로 변경")
chat.send_message("오른쪽 하단에 QR 코드 자리 추가")
chat.send_message("전체적인 스타일을 좀 더 현대적으로, 장식용 꽃무늬 제거")

시나리오 2: 참조 이미지를 활용한 다중 편집

Nano Banana Pro는 한 번에 최대 14장의 참조 이미지를 지원합니다. 다중 턴 대화와 결합하면 강력한 이미지 융합 워크플로우를 구축할 수 있습니다.

# 인물 사진 1장 + 의상 참조 이미지 1장 업로드
chat.send_message([
    "첫 번째 사진 속 인물에게 두 번째 사진의 의상을 입혀줘",
    {"inline_data": {"mime_type": "image/png", "data": person_b64}},
    {"inline_data": {"mime_type": "image/png", "data": outfit_b64}}
])

# 후속 미세 조정
chat.send_message("넥라인을 V넥으로 변경")
chat.send_message("배경을 깔끔한 회색으로 교체")

시나리오 3: 세션 간 기록 복구

사용자가 프론트엔드에서 페이지를 닫았다가 다시 열었을 때 이전 대화를 이어가고 싶다면, contents 배열을 데이터베이스에 영구 저장해야 합니다.

import json

# 저장
with open(f"sessions/{user_id}.json", "w") as f:
    json.dump(chat.get_history(), f)

# 복구
with open(f"sessions/{user_id}.json") as f:
    history = json.load(f)
restored_chat = client.chats.create(
    model="gemini-3-pro-image-preview",
    history=history
)
restored_chat.send_message("아까 하던 거 이어서, 배경을 조금 더 밝게 해줘")

컨텍스트 윈도우 제한

운영 제언: 대화가 8-10 턴을 넘어가면 이전 기록을 능동적으로 '절단(truncate)'하거나 LLM 요약으로 대체하는 것이 좋습니다. 그렇지 않으면 토큰이 빠르게 64K 제한에 도달합니다. 프로덕션 환경에서는 반드시 토큰 카운터를 도입하여 클라이언트 측에서 미리 절단 여부를 결정하도록 하세요.

자주 묻는 질문(FAQ)

요약

Nano Banana Pro 다회차 대화 및 이미지 생성 API의 핵심 포인트:

1. 무상태성(Stateless): API는 어떠한 기록도 기억하지 않으므로, 호출자가 contents 배열을 직접 관리해야 합니다.
2. 역할 교대: user와 model이 엄격하게 교대하며, 각 라운드의 parts는 텍스트/이미지/signature를 혼합할 수 있습니다.
3. 이미지 재전송: 이전 라운드에서 생성된 이미지는 반드시 inline_data 형식으로 다시 포함해야 하며, 그렇지 않으면 모델이 이미지를 '볼 수' 없습니다.
4. 서명 메커니즘: thought_signature는 다회차 일관성의 핵심이며, REST 모드에서는 수동으로 전달해야 합니다.
5. SDK를 통한 간소화: 공식 Python SDK의 chat 객체를 사용하면 위 모든 세부 사항을 자동으로 관리할 수 있습니다.

웹 버전과 같은 경험을 빠르게 구현하고 싶은 개발자라면, SDK의 chat 객체나 OpenAI 호환 인터페이스의 messages 모드를 사용하는 것이 수동으로 REST를 구성하는 복잡함을 피할 수 있는 최선의 방법입니다.

Nano Banana Pro의 다회차 대화 및 이미지 생성 기능을 사용하려면 APIYI(apiyi.com)를 통해 연동하는 것을 추천합니다. 이 플랫폼은 Gemini 네이티브 필드와 OpenAI 호환 모드를 모두 지원하며, 무료 테스트 크레딧을 제공하여 다회차 편집 효과를 빠르게 검증하고 기존 프로젝트를 원활하게 마이그레이션할 수 있도록 돕습니다.

📚 참고 자료

1. Gemini API 이미지 생성 공식 문서: 다중 턴 대화를 통한 이미지 생성에 대한 권위 있는 가이드

   • 링크: ai.google.dev/gemini-api/docs/image-generation
   • 설명: contents 필드 규격, Python SDK 및 REST API 전체 예제 포함

2. Gemini 3 Pro Image Preview 모델 카드: 모델 성능 및 제한 사항 안내

   • 링크: ai.google.dev/gemini-api/docs/models/gemini-3-pro-image-preview
   • 설명: 컨텍스트 윈도우, 해상도, 참조 이미지 개수 등 핵심 파라미터 정보

3. Google AI Developers Forum – Multi-turn Nano Banana: 커뮤니티 실전 예제

   • 링크: discuss.ai.google.dev/t/multi-turn-nano-banana-example
   • 설명: 실제 개발자들이 논의한 다중 턴 대화 모범 사례

4. Vertex AI Gemini 3 Pro Image 문서: 엔터프라이즈급 배포 참고 자료

   • 링크: docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-pro-image
   • 설명: thought_signature 및 file_data 참조를 활용한 고급 사용법 포함

5. APIYI Nano Banana Pro 연동 문서: 국내 개발자를 위한 빠른 시작 가이드

   • 링크: help.apiyi.com
   • 설명: OpenAI 호환 인터페이스 및 네이티브 Gemini 인터페이스 듀얼 모드 예제 포함

작성자: APIYI 기술팀
기술 교류: 다중 턴 대화 이미지 생성 과정에서 겪은 실전 문제들을 댓글로 공유해 주세요. 더 많은 Nano Banana Pro 설정 팁은 APIYI docs.apiyi.com 문서 센터에서 확인하실 수 있습니다.