9장. Gemini API로 확장하기

LLM API를 처음 붙일 때 개발자는 대개 텍스트부터 생각한다. 채팅창이 있고, 사용자가 문장을 입력하고, 모델이 답을 돌려준다. 여기까지는 익숙하다. 그런데 Gemini를 붙이는 순간 질문이 달라진다.

사용자가 꼭 글만 보내야 할까? 스크린샷은 안 될까? PDF는? 음성 메모는? 제품 사진은? 회의 녹음은? 대시보드 캡처와 에러 로그를 한 번에 넣으면 더 잘 설명하지 않을까?

바로 이 지점이 중요하다. Gemini API를 이해한다는 것은 단순히 Google의 모델 하나를 더 배운다는 뜻이 아니다. 텍스트 중심 기능 설계에서 멀티모달 서비스 설계로 사고를 넓히는 일에 가깝다. 공식 문서도 Gemini를 텍스트 생성만이 아니라 이미지 이해, 비디오 이해, 문서 처리, 오디오 이해, 구조화 출력, 함수 호출, 긴 컨텍스트, 도구 사용, Live API까지 포함하는 넓은 플랫폼으로 설명한다.¹

이 장에서는 Gemini API의 요청 구조가 어떻게 생겼는지, 멀티모달 입력을 어떤 식으로 다뤄야 하는지, JSON 같은 구조화 응답을 어떻게 강제하는지, 그리고 이 감각이 실제 서비스 설계에서 왜 중요한지를 차근차근 살펴보자.

Gemini를 붙이면 입력 설계부터 달라진다

OpenAI나 Claude를 먼저 접한 개발자라면 무의식적으로 이런 구조를 떠올린다.

"메시지 몇 개를 쌓고, 시스템 프롬프트를 얹고, 답을 받는다."

물론 Gemini도 대화형으로 쓸 수 있다. 하지만 Gemini의 진짜 재미는 그보다 앞에 있다. 사용자가 주는 근거 자체를 바꿀 수 있다는 점이다.

예를 들어 고객지원 도구를 만든다고 하자. 텍스트형 사고에서는 사용자가 "결제가 안 돼요"라고 쓰면 그 문장을 해석하는 데 집중한다. 그런데 멀티모달 사고로 바꾸면 서비스는 이렇게 바뀐다.

사용자는 에러 메시지 스크린샷을 올리고, 결제 페이지 URL을 붙이고, 마지막으로 "이게 왜 발생했는지 설명하고 해결 순서를 알려줘"라고 묻는다. 그러면 모델은 글만 읽는 것이 아니라 화면, 문구, 맥락을 함께 본다.

이 차이는 생각보다 크다. 텍스트만 받는 서비스는 언제나 사용자의 설명 능력에 의존한다. 하지만 실제 사용자들은 문제를 정확히 설명하지 못하는 경우가 많다. 대신 스크린샷은 잘 올린다. PDF는 던져 준다. 음성 메모는 남긴다. Gemini는 바로 그 현실적인 입력을 서비스 자산으로 바꾸는 쪽에 강하다.¹

AI Studio에서 먼저 감각을 잡는 것이 좋다

Gemini를 코드부터 붙여도 되지만, 실무에서는 먼저 Google AI Studio에서 감각을 익히는 편이 훨씬 빠르다. AI Studio는 텍스트, 이미지, 오디오, 비디오 등 여러 모달리티를 한 공간에서 시험해 볼 수 있는 플레이그라운드 역할을 하고, API 키 발급과 사용량 확인, 프로젝트 관리까지 한 흐름으로 이어진다.²

이게 왜 좋을까. 이유는 단순하다. 멀티모달 기능은 코드보다 입력 실험이 먼저이기 때문이다.

예를 들어 같은 제품 사진이라도 프롬프트를 이렇게 바꾸면 결과가 달라진다.

"이 사진을 설명해 줘."

"이 사진에서 구매 결정을 방해하는 요소를 세 가지 찾아줘."

"이 사진을 이커머스 상세페이지용 관점에서 분석해 줘."

모델의 능력 차이보다 서비스 질문 차이가 더 크게 느껴질 때가 많다. AI Studio는 바로 이 실험을 빠르게 해 보게 해 준다. 그러니 Gemini를 붙일 때는 SDK 문법보다 먼저, 어떤 입력 조합이 사용자 문제를 가장 잘 드러내는가를 시험하는 습관이 중요하다.²

Gemini 요청은 '채팅 메시지'보다 '콘텐츠 묶음'으로 이해하자

Gemini API를 이해하는 가장 좋은 방법은 messages보다 contents와 parts를 떠올리는 것이다. 실전에서는 하나의 요청 안에 텍스트 조각, 이미지 데이터, PDF 파일, 이전 대화 턴 같은 것들이 함께 들어간다. 그리고 출력 제어용 설정은 별도의 생성 설정으로 붙는다.³

감각적으로 보면 이런 구조다.

• contents: 대화나 입력의 큰 묶음

• parts: 그 안에 들어가는 실제 조각들

• generationConfig: 온도, 응답 길이, 응답 형식 같은 제어값

• safetySettings, tools: 안전성과 외부 도구 사용 설정

즉 Gemini에서는 "사용자가 한 문장을 보냈다"보다 "사용자가 여러 형태의 근거를 한 요청 안에 넣었다"는 생각이 더 잘 맞는다.

예를 들어 멀티모달 요청은 개념적으로 이런 모습에 가깝다.

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "이 대시보드 스크린샷을 보고 이상 징후와 우선 대응 순서를 알려줘." },
        {
          "inline_data": {
            "mime_type": "image/png",
            "data": "<base64-encoded-image>"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "temperature": 0.2
  }
}

중요한 것은 문법 그 자체보다 사고방식이다. 텍스트 기반 API에서는 프롬프트가 거의 전부였다. Gemini에서는 프롬프트와 함께 무엇을 보여 주는가가 같은 무게를 가진다.

그래서 서비스 설계 질문도 바뀐다.

"프롬프트를 어떻게 쓸까?"가 아니라 "사용자에게 어떤 증거를 올리게 만들까?"가 된다.

이 질문이 좋아지면 제품이 좋아진다.

멀티모달의 핵심은 OCR 대체가 아니라 추론 단계의 결합이다

Gemini를 처음 볼 때 많은 팀이 이렇게 생각한다.

"좋네. 이미지도 읽네. OCR 붙인 것보다 편하겠네."

맞는 말이지만, 반만 맞다.

진짜 강점은 단지 이미지를 글로 바꾸는 데 있지 않다. 서로 다른 입력을 따로따로 처리하던 파이프라인을 한 번에 추론하게 만드는 것에 있다.⁶

예를 들어 예전 방식이라면 다음처럼 나눴을 수 있다.

1. PDF에서 텍스트 추출

2. 스크린샷에서 OCR 수행

3. 로그 텍스트 정규화

4. 각 결과를 다시 LLM에 넣어 요약

이 구조는 돌아가긴 한다. 하지만 중간 단계가 많을수록 오류도 많아진다. OCR이 잘못 읽고, 표가 깨지고, 문맥 연결이 끊긴다.

Gemini식 사고는 다르다. 문서, 화면, 질문을 한 요청 안에 모아 놓고 모델이 그 관계를 함께 보게 한다. 그러면 개발자는 전처리 체인을 끝없이 늘리는 대신, 어떤 입력 조합이 문제 해결에 가장 도움이 되는지에 집중할 수 있다.

이 접근은 다음 같은 서비스에서 특히 강하다.

• 문서 QA: 계약서 PDF를 올리고 특정 조항의 위험을 묻는 서비스

• 운영 도우미: 모니터링 화면 캡처와 알림 로그를 함께 분석하는 도구

• 커머스 보조: 상품 사진과 설명 문구를 함께 보고 개선점을 제안하는 기능

• 교육 서비스: 판서 사진, 교재 PDF, 학생 질문을 함께 받아 설명하는 기능

멀티모달은 기능이 하나 더 늘어나는 것이 아니다. 서비스가 사용자 현실에 더 가까워지는 방식이다.

응답 형식까지 설계해야 비로소 서비스가 된다

Gemini는 기본적으로 자연어 텍스트를 생성하지만, 서비스 개발에서는 "그럴듯한 문장"보다 "안정적인 형식"이 더 중요할 때가 많다. 예를 들어 자동 분류, 티켓 생성, 워크플로 트리거, 대시보드 적재 같은 기능은 예쁜 문장보다 JSON이 훨씬 쓸모 있다.

공식 문서에서는 responseMimeType과 responseSchema를 사용해 JSON 같은 구조화 출력을 유도할 수 있고, enum 값처럼 제한된 답변 형식도 만들 수 있다고 설명한다. 또 이런 구조화 출력은 텍스트 전용 요청뿐 아니라 이미지, 비디오, 오디오를 포함한 멀티모달 요청에도 적용할 수 있다.⁴

이건 정말 중요하다. 왜냐하면 멀티모달 서비스는 "보고 이해한다"에서 끝나면 안 되기 때문이다. 보고 나서 시스템이 바로 다음 행동을 할 수 있어야 한다.

예를 들어 고객지원 자동화라면 자연어 설명 대신 이런 JSON이 더 유용하다.

{
  "category": "payment_error",
  "severity": "high",
  "summary": "결제 승인 직전 단계에서 카드 인증 실패 메시지가 노출됨",
  "actionItems": [
    "PG사 인증 로그 확인",
    "브라우저별 재현 여부 확인",
    "사용자에게 재시도 가이드 발송"
  ]
}

이렇게 되면 모델 출력은 곧바로 내부 티켓 시스템, 관리자 화면, 알림 워크플로에 연결될 수 있다.

Gemini에서 구조화 출력을 설계할 때 기억하면 좋은 원칙은 단순하다.

첫째, 자유서술이 아니라 필요한 필드를 먼저 정한다. 둘째, 사람이 읽기 좋은 출력과 시스템이 처리하기 좋은 출력을 분리한다. 셋째, 멀티모달 입력일수록 요약 텍스트보다 구조화 필드가 더 중요해진다.

이미지나 문서 분석 결과를 사람 손으로 다시 읽고 복붙하게 만들면, 멀티모달의 장점이 절반으로 줄어든다.

Gemini의 통합 방식은 'Google스럽다'는 점을 기억하자

Gemini API를 서비스에 붙이는 길은 한 가지가 아니다. 가장 단순한 방법은 공식 SDK나 REST로 직접 generateContent를 호출하는 것이다. 여기에 Google AI Studio로 프로토타입을 만들고, 필요하면 Files API, Google Search, URL context, Code execution, File Search, Live API 같은 기능으로 확장해 갈 수 있다. 공식 문서에는 기존 OpenAI 스타일 코드베이스를 옮길 때 참고할 수 있는 OpenAI compatibility 가이드도 따로 준비되어 있다.¹

이걸 실무 감각으로 바꿔 말하면 이렇다.

처음엔 "Gemini 모델 하나 호출"로 시작할 수 있다. 하지만 조금만 지나면 "파일 입력은 어떻게 관리하지?", "검색 근거는 어떻게 붙이지?", "실시간 음성 상호작용은 Live API로 갈까?", "기존 OpenAI 인터페이스를 얼마나 유지할까?" 같은 통합 질문이 자연스럽게 따라온다.

즉 Gemini는 모델만 붙이는 경험보다 주변 기능까지 묶어 서비스 흐름을 설계하는 경험에 가깝다.

간단한 텍스트 요청은 공식 SDK로도 매우 직관적으로 시작할 수 있다.

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

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

const response = await ai.models.generateContent({
  model: "gemini-3-flash-preview",
  contents: "이 회의 메모를 세 문장으로 요약해 줘."
});

console.log(response.text);

하지만 서비스가 커질수록 중요한 것은 호출 한 줄이 아니라, 어떤 입력 경로와 어떤 출력 계약을 둘 것인가다.

모델 선택은 Flash를 기본값으로, Pro를 승급 경로로 생각하면 편하다

Gemini 모델 문서를 보면 Flash, Flash-Lite, Pro 같은 계열이 있고, Gemini 2.5와 Gemini 3 라인업도 함께 보인다.⁵ 실무에서는 이걸 외울 필요보다 언제 어떤 계열을 기본값으로 둘지 감각을 잡는 것이 중요하다.

대체로 이렇게 생각하면 편하다.

Flash 계열은 빠르고 넓게 처리해야 하는 서비스의 기본값이다. 실시간 채팅, 대량 요약, 분류, 첫 화면 응답처럼 속도와 비용이 중요한 곳에 잘 맞는다. Flash-Lite는 더 가벼운 작업에서 특히 유리하다. 반대로 Pro 계열은 더 복잡한 추론, 더 까다로운 문서 해석, 더 중요한 멀티모달 판단에 투입하는 승급 모델로 생각할 수 있다.

이 전략이 좋은 이유는 제품 설계와도 맞기 때문이다. 모든 요청에 최고급 모델을 태우는 서비스는 보통 오래 못 간다. 첫 응답은 Flash로 빠르게 처리하고, 특정 조건에서만 Pro로 재판단하거나 심화 분석을 거는 구조가 현실적이다.

예를 들어 이런 식이다.

• 일반 문서 요약은 Flash

• 표와 이미지가 섞인 복합 보고서 분석은 Pro

• 고객이 올린 스크린샷의 1차 분류는 Flash

• 결제 실패나 보안 경고처럼 오판 비용이 큰 사례는 Pro 재검토

Gemini를 잘 쓰는 팀은 모델 이름을 자랑하지 않는다. 대신 어떤 요청을 어떤 티어로 보낼지 제품 규칙으로 정한다.

서비스 적용 포인트는 '입력 경험'에서 갈린다

Gemini를 붙여 만든 서비스가 기대만큼 좋아지지 않는 경우가 있다. 이유는 종종 모델이 아니라 UI에 있다. 멀티모달 모델인데도 여전히 텍스트 박스 하나만 던져 놓았기 때문이다.

Gemini를 서비스에 붙일 때는 입력 경험을 조금 다르게 설계하는 편이 좋다.

첫째, 사용자가 파일이나 이미지를 올려도 되는 상황을 적극적으로 열어 둔다. 둘째, 그냥 업로드만 받지 말고 무엇을 함께 묻는지 안내한다. 셋째, 모델이 분석한 결과를 다시 구조화된 액션으로 연결한다.

예를 들어 "문서를 업로드하세요"보다 "계약서 PDF를 올리고, 특히 걱정되는 조항이 있다면 함께 적어 주세요"가 훨씬 낫다. "스크린샷을 올리세요"보다 "오류 화면 전체가 보이게 캡처해 주세요. 무엇을 하다가 이 화면이 떴는지도 적어 주세요"가 더 좋다.

멀티모달 서비스는 모델이 똑똑해서 성공하는 게 아니다. 사용자가 문제의 근거를 자연스럽게 건네도록 만드는 입력 UX가 받쳐 줄 때 성공한다.

Gemini를 쓸 때 자주 하는 실수

Gemini는 강력하지만, 처음 붙일 때 빠지기 쉬운 함정도 분명하다.

텍스트 프롬프트만 바꾸면 된다고 생각하는 실수

Gemini를 OpenAI의 대체 채팅 API처럼만 쓰면 장점이 잘 드러나지 않는다. 멀티모달 모델인데 입력 설계가 텍스트 하나로 고정되면, 서비스는 여전히 예전 사고에 머문다.

파일을 받으면서도 출력은 자유서술로만 두는 실수

문서나 이미지를 분석시켜 놓고 결과를 긴 문장으로만 받으면, 그다음 시스템 연결이 어렵다. 멀티모달일수록 responseSchema 같은 구조화 출력이 더 중요하다.⁴

MIME 타입과 입력 품질을 가볍게 보는 실수

이미지, 오디오, 문서는 텍스트보다 입력 품질의 영향을 더 크게 받는다. 파일 형식, 해상도, 캡처 범위, 잡음 상태가 나쁘면 모델이 못하는 것이 아니라 근거가 빈약한 것이다. 멀티모달에서는 프롬프트 엔지니어링만큼 입력 수집 엔지니어링이 중요하다.

AI Studio 실험과 운영 코드를 분리하지 않는 실수

플레이그라운드에서 잘 되던 입력 조합이 운영에서는 다를 수 있다. 실제 사용자 파일은 더 지저분하고, 응답 형식은 더 엄격해야 하며, 비용과 지연 시간도 고려해야 한다. 그러니 AI Studio는 감각을 익히는 곳이고, 운영 코드는 별도의 계약과 검증을 가져야 한다.²

Gemini를 이해하면 왜 다음 단계가 쉬워질까

Gemini를 붙이고 나면 개발자의 시야가 조금 달라진다. 전에는 "좋은 프롬프트를 쓰자"가 중심이었다면, 이제는 "좋은 입력 조합을 설계하자", "응답을 시스템 계약으로 묶자", "모델이 볼 근거를 서비스가 어떻게 수집할까"가 중심이 된다.

이 변화는 뒤로 갈수록 더 중요해진다. 이후에 문서 처리, 멀티모달 업로드, 외부 도구 연결, 검색 증강 생성, 에이전트 설계 같은 주제로 갈수록, 텍스트만 받는 서비스보다 멀티모달 서비스가 훨씬 현실적인 제품이 되기 때문이다.

Gemini는 여기서 좋은 훈련 상대다. 왜냐하면 이 API는 개발자에게 계속 이렇게 묻기 때문이다.

"사용자 문제를 정말 텍스트 한 줄로만 받아야 하나?"

이 질문에 제대로 답하기 시작하면, 서비스의 입력 설계가 달라지고, 출력 계약이 달라지고, 결국 제품의 가능성도 넓어진다.

정리

이 장의 핵심은 분명하다. Gemini API를 이해한다는 것은 또 하나의 LLM API를 배우는 일이 아니라, 멀티모달 서비스 설계 감각을 배우는 일이다.

Gemini의 요청 구조는 텍스트 하나보다 콘텐츠 묶음에 가깝다. 텍스트와 이미지, 문서와 질문, 오디오와 지시를 함께 다루는 방향으로 설계되어 있다. 응답도 자연어로 끝낼 수 있지만, 실제 서비스에서는 JSON과 enum 같은 구조화 형식으로 받아야 자동화가 쉬워진다. 모델 선택 역시 Flash를 기본값으로 두고 Pro를 승급 경로로 쓰는 식의 제품 규칙이 중요하다.

무엇보다 Gemini가 주는 가장 큰 교훈은 이것이다. LLM 서비스는 점점 "질문을 잘 쓰는 기술"에서 "근거를 잘 모으고, 잘 보여 주고, 잘 연결하는 기술"로 이동하고 있다. 텍스트 중심 사고를 넘어서면, 그때부터 서비스가 훨씬 더 현실 세계를 닮기 시작한다.

다음 장에서는 이 감각을 한 단계 더 밀어 붙여, 특정 벤더를 잘 쓰는 수준을 넘어 여러 벤더를 함께 다루는 멀티 벤더 아키텍처로 시야를 넓혀 보자.

참고

¹Gemini API 공식 문서 개요

²Google AI Studio

³Gemini API Tutorial: Multimodal AI in Python

⁴구조화된 출력 생성하기

⁵Gemini API 모델 문서

⁶멀티모달 AI 개요