1. Gemini API란?

구분 내용
정의 Google Cloud AICore가 제공하는 대규모 언어‑·멀티모달 모델 서비스. “Gemini 2” 계열(Flash, Pro) 등급별 latency·맥락길이 상이
API 자바스크립트 개발자는 공식 SDK @google/genai 로 간편 사용
특징 ① 텍스트·이미지 동시 입력, ② 스트리밍(SSE) 지원, ③ 멀티턴 히스토리 유지, ④ 세분화된 생성 파라미터(temperature, top‑p, top‑k…)
모델군 Gemini 1.5 Pro / 2.0 Flash (텍스트·코드·이미지 다중 입력)
장점 낮은 지연(Flash), 멀티모달, 합리적 과금·무료 할당, Google 생태계‑SDK 제공
지원 호출 방식 REST (단건) / Streaming (서버 전송 SSE)
대화 기능 history 배열 제공 → 멀티턴 문맥 유지

2. 인증 · 기본 호출 플로우

  1. API Key 발급 (Google AI Studio → API Key)

  2. 요청 헤더 Authorization: Bearer <key> 또는 SDK 생성자에 직접 주입

  3. 모델 선택 gemini-2.0-pro (정밀)│gemini-2.0‑flash (저지연)

  4. 요청 Body 구성

    {
  "contents":[{ "role":"user", "parts":[{ "text":"Hello"}]}],
  "generationConfig":{ "temperature":0.5, "maxOutputTokens":1024 }
}

  5. 응답 형식

    {
  "candidates":[
    { "index":0, "content":{ "role":"model","parts":[{ "text":"Hi!"}]}}
  ],
  "usageMetadata":{ "inputTokens":3, "outputTokens":4 }
}

3. 자바스크립트 SDK 핵심 API 정리 (@google/genai)

메서드 목적 주요 인자
new GoogleGenAI({ apiKey }) 클라이언트 인스턴스 생성
genAI.generators.text(...) 단발 텍스트 생성(REST) model, prompt, generationConfig
genAI.chats.create(...) 대화 세션 생성 model, history, config
chat.sendMessage() 한 번에 전체 응답(REST) { message }
chat.sendMessageStream() SSE 스트림으로 응답 { message } ⇒ AsyncIterable<Chunk>

내부적으로 sendMessage() 는 HTTP POST /v1beta/models/{model}:generateContent,

sendMessageStream() 은 :streamGenerateContent 엔드포인트를 호출한다.

4. REST vs SSE (원리 차이)

항목 REST (chat.sendMessage) SSE (chat.sendMessageStream)
프로토콜 단일 HTTP POST HTTP keep‑alive + text/event-stream
동작 흐름 모델이 모든 토큰 생성 → 한 번에 반환 토큰 단위로 즉시 전송 → 클라이언트가 순차 렌더
장점 구현 간단, 오류 처리 용이 첫 바이트 Latency ↓, 긴 답변 UX ↑
단점 긴 답변 대기시간, 취소 불가 파서 작성 필요, Abort 처리 필수
구분 REST SSE(Stream)
UX 응답 전까지 로딩 표시 첫 토큰 즉시 노출
네트워크 짧은 JSON 1회 지속 연결, 이벤트 프레임
중단 재요청 필요 AbortController.abort()
적합 시나리오 FAQ·검색·배치 요약 채팅, 실시간 생성