Skip to main content
Tilnote
T
tilnote
책에 포함된 노트나노바나나 프롬프트 설계 — 외우지 말고 짜라

6. 개발자를 위한 Gemini API 활용

Views 10약 7분생성형 AI 활용

개발자를 위한 Gemini API 활용

이 장은 버튼을 누르는 사람에서, 흐름을 설계하는 사람으로 넘어가는 입구다. 앱에서 한 장씩 만들 때는 감으로도 어느 정도 버틸 수 있다. 하지만 썸네일을 매일 만들고, 제품 이미지를 여러 각도로 돌리고, 같은 캐릭터를 매주 유지하려면 이야기가 달라진다. 그때부터는 좋은 프롬프트 하나보다 재현 가능한 파이프라인이 더 중요해진다.

다행히 시작은 생각보다 어렵지 않다. API 키 하나 만들고, 텍스트 한 줄을 보내고, 돌아온 이미지를 저장해 보면 된다. 그다음부터는 "같은 스타일 유지", "이번엔 배경만 변경", "초안은 싸게 여러 장, 마감은 더 정밀하게" 같은 개발자의 무기가 붙는다.

개발자를 위한 Gemini API 활용

6.1 API 키 발급과 첫 호출

Gemini API의 출발점은 보통 Google AI Studio다. 여기서 API 키를 만들고, 모델을 직접 시험해 보고, 프롬프트 감을 잡을 수 있다.1 앱에서 이미지가 잘 나왔다고 해서 바로 자동화 코드가 되는 것은 아니므로, 개발자는 가능한 한 빨리 AI Studio와 API 환경으로 넘어와 보는 편이 좋다.

이미지 생성·편집은 Gemini API에서 텍스트와 이미지를 함께 다루는 멀티모달 요청으로 처리된다.2 즉,

  • 텍스트만 넣고 새 이미지를 만들 수 있고

  • 텍스트와 기존 이미지를 함께 넣어 편집할 수 있고

  • 응답으로 텍스트와 이미지를 함께 받을 수도 있다

출간 시점 기준으로 실무에서 많이 쓰는 모델 이름은 다음처럼 기억하면 편하다.

  • gemini-3.1-flash-image-preview: Nano Banana 2 계열. 빠르고 반복 작업에 유리하다.

  • gemini-3-pro-image-preview: Nano Banana Pro 계열. 더 정밀한 결과와 복잡한 요청 해석에 유리하다.

처음에는 Flash 계열 하나로 시작하는 것이 좋다. 개발용 기본값으로 두기 편하고, 실패해도 비용 부담이 덜하다. 아래는 Python 예시다.

from google import genai
from PIL import Image
from io import BytesIO

client = genai.Client(api_key="YOUR_API_KEY")

prompt = "Create an editorial-style product image of a matte black coffee grinder on a clean white background."

response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=prompt,
)

for part in response.candidates[0].content.parts:
    if part.text is not None:
        print(part.text)
    elif part.inline_data is not None:
        image = Image.open(BytesIO(part.inline_data.data))
        image.save("grinder.png")

핵심은 문법보다 흐름이다. 모델 지정 → 입력 전달 → 응답 파트 순회 → 이미지 저장. 이 네 단계만 이해하면 그다음부터는 거의 다 응용이다.

6.2 Python·JavaScript 코드 예시 — Flash와 Pro를 어떻게 나눠 쓸까

처음부터 거대한 자동화 파이프라인을 만들 필요는 없다. 같은 요청을 Flash와 Pro에 각각 보내 보고, 체감 차이를 보는 것부터 시작하면 된다.

Python 예시

from google import genai
from google.genai import types

client = genai.Client(api_key="YOUR_API_KEY")

prompt = "Create a Korean cafe poster with a clear headline area, warm morning light, realistic pastry display, and space for copy at the top."

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=prompt,
    config=types.GenerateContentConfig(
        response_modalities=["Text", "Image"],
        image_config=types.ImageConfig(aspect_ratio="4:5")
    )
)

JavaScript 예시

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const response = await ai.models.generateContent({
  model: "gemini-3.1-flash-image-preview",
  contents: "Create a clean 16:9 blog thumbnail showing a laptop, coffee, and notebook on a wooden desk, with space for a title.",
  config: {
    responseModalities: ["Text", "Image"],
    imageConfig: {
      aspectRatio: "16:9"
    }
  }
});

여기서 중요한 것은 코드 길이가 아니다. 왜 이 요청을 Flash에 보내는지, 왜 저 요청을 Pro에 보내는지가 더 중요하다.

  • Flash: 빠른 시안, 여러 버전 탐색, 대량 생성, 반복 편집

  • Pro: 포스터, 광고, 텍스트 정확도, 최종본, 복잡한 다단 지시

초보 개발자는 종종 가장 좋은 모델 하나만 고정해 모든 요청을 보내려 한다. 하지만 실제 운영에서는 이 방식이 비싸고 둔하다. 더 나은 방식은 요청을 분류하는 것이다.

6.3 thinking level 조절 — 언제 더 생각하게 할 것인가

이 부분은 문서가 자주 바뀌어서 헷갈리기 쉽다. 정리하면 이렇다.

  • Gemini 3 계열 모델은 thinking_level을 지원한다.3

  • Gemini 2.5 계열 모델은 thinking_level 대신 thinkingBudget 또는 사고 예산 방식으로 제어한다.3

이 장에서 다루는 Nano Banana 2와 Nano Banana Pro는 Gemini 3 계열 축에 가까우므로, 실무에서는 thinking_level을 주로 보게 된다. Google 문서에서는 기본적으로 동적 사고가 켜져 있거나, 모델이 상황에 따라 적절한 사고량을 선택하도록 설계돼 있다고 설명한다.34

개발자가 체감적으로 이해하려면 이렇게 보면 된다.

  • Minimal: 빠르게 초안 확인할 때

  • Low / Medium: 일반적인 생성 작업, 속도와 품질의 균형이 필요할 때

  • High / Dynamic: 복잡한 지시, 텍스트 정확도, 여러 제약을 동시에 맞춰야 할 때

예를 들어 "커피잔 사진 만들어 줘" 정도는 많이 생각할 필요가 없다. 하지만 "세로형 광고 배너, 상단 제목 공간 확보, 제품 로고 유지, 한국어 문구 삽입, 조명은 아침 느낌, 브랜드 색은 무너뜨리지 말 것" 같은 요청은 이야기가 다르다. 이런 경우에는 모델이 더 많이 생각할수록 지시 이행과 결과 안정성이 좋아질 수 있다.5

다만 여기에도 원칙이 있다. 생각을 많이 시킨다고 항상 더 좋은 건 아니다. 초안 단계에서 High를 남발하면 느리고 비싸다. 그래서 보통은 이렇게 쓴다.

  1. Flash + 낮은 사고량으로 넓게 탐색한다.

  2. 살아남은 안만 추린다.

  3. 최종본 후보를 Pro + 더 높은 사고량으로 마감한다.

이 배치는 단순하지만 아주 강하다.

6.4 멀티턴 편집 — 한 번에 끝내지 말고 대화로 다듬기

이미지 작업은 한 번에 끝내려 할수록 오히려 흔들린다. 개발자도 이 점은 디자이너와 같다. 좋은 흐름은 대개 기준 이미지 생성 → 한 축만 수정 → 최종 마감 순서로 간다.

Gemini SDK는 chat 형태로 여러 턴의 대화를 관리하는 기능을 제공한다. 다만 내부적으로는 여전히 generateContent 계열 호출을 기반으로 하고, 문맥 관리는 SDK가 도와주는 쪽에 가깝다.6 다시 말해, 대화형 인터페이스가 있다고 해서 "모든 상태를 서버가 영구히 기억해 준다"고 생각하면 안 된다. 특히 직접 요청을 조립할 때는 필요한 맥락을 다시 전달하는 습관이 중요하다.

이미지 편집에서 멀티턴이 강한 이유는 명확하다.

  • 처음부터 모든 요구를 한 프롬프트에 몰아넣지 않아도 된다.

  • 유지할 것과 바꿀 것을 분리하기 쉽다.

  • 실패 원인을 더 좁게 진단할 수 있다.

예를 들어 이런 식이다.

  • 1턴: 기준 인물 이미지를 만든다.

  • 2턴: 표정만 바꾼다.

  • 3턴: 배경만 교체한다.

  • 4턴: 최종 포스터 비율로 재구성한다.

이 방식은 3장에서 배운 유지 먼저, 변경 나중 원칙과 정확히 연결된다. 개발자가 코드로 구현할 때도 마찬가지다. "이번 요청은 무엇을 유지하고, 무엇만 바꾸는가"를 구조로 남기면 디버깅이 쉬워진다.

또 하나 중요한 점은 thought signatures다. 특히 Gemini 3 Pro Image를 사용한 멀티턴 이미지 편집에서는 공식 문서가 생각 서명을 다시 전달해 추론 문맥을 유지하는 방식을 권장한다.2 이건 눈에 잘 보이지 않는 내부 연결고리 같지만, 복잡한 편집에서는 체감 차이가 꽤 난다.

6.5 비용 최적화 — Pro와 Flash를 워크플로 어디에 배치할 것인가

비용 최적화는 "싼 모델만 쓰기"가 아니다. 비싼 모델을 꼭 필요한 순간에만 쓰는 것이다.

보통 이미지 자동화에서 비용이 새는 순간은 세 군데다.

  • 초안 생성부터 고급 모델을 태우는 경우

  • 수정 한 번마다 전체를 다시 생성하는 경우

  • 실패한 요청을 구조 없이 반복 호출하는 경우

실무에서는 다음 구조가 가장 무난하다.

1단계: Flash로 탐색

여러 비율, 여러 구도, 여러 스타일을 빠르게 시험한다. 여기서는 속도가 중요하다. 아직 정답을 모르는 단계이기 때문이다.

2단계: Flash 또는 동일 모델로 대화형 편집

살아남은 한두 장을 기준으로 배경, 조명, 카메라, 텍스트 공간을 다듬는다. 전체를 다시 뽑기보다 유지·변경 축을 나누는 쪽이 낭비가 적다.

3단계: Pro로 최종 마감

정확한 텍스트, 더 높은 충실도, 광고나 인포그래픽처럼 실수가 비싼 결과물은 마지막에 Pro로 보낸다.

이 방식은 단순히 비용을 아끼는 전략이 아니다. 품질도 함께 올린다. 왜냐하면 최종 모델이 고민해야 할 변수를 앞단에서 이미 많이 줄여 놨기 때문이다.

6.6 자동화 사례 — 블로그 썸네일 자동 생성 파이프라인

가장 단순하지만 강력한 자동화 예시는 블로그 썸네일이다. 글이 발행될 때마다 사람이 매번 새로 만들지 않아도 되기 때문이다.

흐름은 대략 이렇다.

  1. CMS에서 글 제목, 카테고리, 요약을 읽는다.

  2. 이 정보를 6블록 프레임으로 변환한다.

  3. Flash 모델로 2~4개의 썸네일 초안을 생성한다.

  4. 간단한 규칙으로 1차 필터링한다.

    • 비율이 맞는가

    • 제목 영역이 비어 있는가

    • 주제가 글 내용과 크게 어긋나지 않는가

  5. 필요하면 Pro로 최종 1장을 다시 생성하거나 미세 수정한다.

  6. 결과물을 CMS에 저장하고, 편집자가 마지막으로 확인한다.

중요한 것은 "AI가 다 한다"가 아니다. 오히려 반대다. AI는 반복 구간을 자동화하고, 사람은 마지막 판단을 맡는다. 이 배치가 가장 오래 간다.

예를 들어 블로그 글이 "봄철 홈카페 촬영 팁"이라면 내부 프롬프트 템플릿은 이런 식으로 구성할 수 있다.

  • 주제: 홈카페 테이블, 커피잔, 디저트, 자연광

  • 동작: 막 커피를 내려 놓은 순간

  • 배경: 아침, 창가, 따뜻한 분위기

  • 스타일: 라이프스타일 에디토리얼 포토그래피

  • 카메라: 16:9, eye-level 또는 slight top-down

  • 제약: 상단 제목 공간 확보, 텍스트 삽입 금지, 과도한 소품 금지

이렇게 하면 블로그 주제가 바뀌어도 구조는 유지된다. 결국 개발자가 자동화해야 하는 것은 "문장"이 아니라 결정 순서다.

개발자는 프롬프트보다 파이프라인을 설계한다

이 장의 핵심은 코드 문법이 아니다. 더 중요한 것은 세 가지다.

  • 어떤 모델을 어떤 단계에 배치할지

  • 무엇을 유지하고 무엇을 바꿀지 어떻게 기록할지

  • 실패했을 때 어떤 변수를 먼저 의심할지

프롬프트 한 줄이 잘 먹는 날도 있다. 하지만 운영은 한 줄의 기적 위에 세우는 것이 아니다. 좋은 자동화는 대부분, 반복 가능한 구조와 비용 감각과 수정 규칙 위에 올라간다. 개발자에게 필요한 것은 더 화려한 주문이 아니라, 다시 돌려도 비슷하게 작동하는 설계다.

참고

1Gemini API Quickstart

2Gemini API Image Generation Docs

3Gemini thinking | Gemini API

4Thinking | Vertex AI Documentation

5Build with Nano Banana 2, our best image generation and editing model

6Text generation and chat | Gemini API

책 목록

나노바나나 프롬프트 설계 — 외우지 말고 짜라

전체 목차 보기

이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.

틸노트는 사용자가 AI를 활용해 노트를 쉽게 작성하거나 편집할 수 있는 서비스입니다.

회원 가입

AI 스퀘어 단톡방에 함께해요

AI 활용과 틸노트 사용 팁을 나누는 오픈채팅방입니다. 입장 비밀번호는 tilnote입니다.

참여하기
이용약관·개인정보처리방침