Node.js에서 Gemini API 사용하기 - 2026년 최신 가이드

English (N/A)
#Gemini#Google#AI#Node.js#TypeScript#API

Google의 Gemini API를 사용하려고 찾아보면 정보가 파편화되어 있어서 헷갈리는 경우가 많다. 공식 SDK가 뭔지, 어떤 패키지를 써야 하는지, Vertex AI와는 뭐가 다른지 등등. 이 글에서는 2026년 기준 가장 안정적인 방법으로 Gemini API를 사용하는 방법을 정리한다.

공식 SDK 설치

Google에서 공식으로 제공하는 SDK는 @google/genai다.

npm install @google/genai

주의할 점이 있다. 예전에 사용하던 @google/generativeai 패키지는 더 이상 유지되지 않는다. 새 프로젝트라면 반드시 @google/genai를 사용해야 한다.

API 키 발급

Google AI Studio에서 API 키를 발급받으면 된다. 무료 티어도 제공되니 테스트 용도로는 충분하다.

기본 사용법

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

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

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: '안녕하세요, Gemini!',
});

console.log(response.text);

환경 변수에 GOOGLE_API_KEY를 설정해두면 아래처럼 더 간단하게 초기화할 수도 있다.

const ai = new GoogleGenAI({});

스트리밍

응답을 실시간으로 받아야 할 때는 generateContentStream을 사용한다.

const response = await ai.models.generateContentStream({
  model: 'gemini-2.5-flash',
  contents: '긴 글을 작성해줘',
});

for await (const chunk of response) {
  process.stdout.write(chunk.text);
}

멀티턴 채팅

대화 맥락을 유지해야 할 때는 chats를 사용한다.

const chat = ai.chats.create({
  model: 'gemini-2.5-flash',
});

const response1 = await chat.sendMessage({ message: '내 이름은 철수야' });
console.log(response1.text);

const response2 = await chat.sendMessage({ message: '내 이름이 뭐라고 했지?' });
console.log(response2.text); // 철수라고 기억하고 있다

멀티모달 파일 처리

Gemini의 강점 중 하나가 멀티모달 처리다. 이미지, PDF, 오디오, 비디오 파일을 모두 처리할 수 있다.

파일 처리 방식 선택

파일 크기에 따라 두 가지 방식을 선택하면 된다.

  • 인라인 데이터 (base64): 총 요청 크기 100MB 미만일 때
  • Files API: 100MB 이상이거나 파일을 재사용할 때

Files API는 무료이고, 업로드된 파일은 48시간 동안 보관된다.

인라인 vs Files API 성능 비교

어떤 방식이 더 빠를까? 단일 요청에서는 인라인 base64가 더 빠르다. 별도의 업로드 단계 없이 바로 요청을 보내기 때문이다.

반면 Files API는 파일을 한 번 업로드해두면 여러 요청에서 재사용할 수 있다. 같은 파일로 여러 번 요청해야 한다면 Files API가 유리하다.

인라인 base64를 쓰면 좋은 경우:

  • 100MB 이하 파일
  • 일회성 처리
  • 실시간 응답이 중요할 때 (예: 사용자가 이미지 올리면 바로 분석 결과 보여주기)
  • 빠른 프로토타이핑

Files API를 쓰면 좋은 경우:

  • 100MB 초과 파일 (최대 2GB)
  • 같은 파일로 여러 번 요청할 때 (멀티턴 대화 등)
  • 반복 업로드를 피하고 싶을 때

이미지 분석

import * as fs from 'node:fs';

// 인라인 방식 (작은 파일)
const base64Image = fs.readFileSync('image.jpg', { encoding: 'base64' });

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: [
    {
      inlineData: {
        mimeType: 'image/jpeg',
        data: base64Image,
      },
    },
    { text: '이 이미지를 설명해줘' },
  ],
});

import { createPartFromUri } from '@google/genai';

// Files API 방식 (큰 파일)
const uploadedImage = await ai.files.upload({
  file: 'large-image.jpg',
  config: { mimeType: 'image/jpeg' },
});

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: [
    createPartFromUri(uploadedImage.uri, uploadedImage.mimeType),
    '이 이미지에서 텍스트를 추출해줘',
  ],
});

PDF 문서 분석

import { createPartFromUri } from '@google/genai';

const file = await ai.files.upload({
  file: 'document.pdf',
  config: { displayName: 'my-document.pdf' },
});

// 대용량 파일은 처리 완료까지 대기가 필요하다
let fileInfo = await ai.files.get({ name: file.name });
while (fileInfo.state === 'PROCESSING') {
  await new Promise(resolve => setTimeout(resolve, 5000));
  fileInfo = await ai.files.get({ name: file.name });
}

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: [
    createPartFromUri(file.uri, file.mimeType),
    '이 문서를 요약해줘',
  ],
});

console.log(response.text);

PDF는 최대 1000페이지, 50MB까지 지원된다.

오디오 분석

import { createUserContent, createPartFromUri } from '@google/genai';

const audioFile = await ai.files.upload({
  file: 'audio.mp3',
  config: { mimeType: 'audio/mp3' },
});

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: createUserContent([
    createPartFromUri(audioFile.uri, audioFile.mimeType),
    '이 오디오를 텍스트로 변환해줘',
  ]),
});

WAV, MP3, AIFF, AAC, OGG, FLAC 형식을 지원하고, 최대 9.5시간까지 처리할 수 있다.

비디오 분석

import { createUserContent, createPartFromUri } from '@google/genai';

// 로컬 파일 업로드
const videoFile = await ai.files.upload({
  file: 'video.mp4',
  config: { mimeType: 'video/mp4' },
});

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: createUserContent([
    createPartFromUri(videoFile.uri, videoFile.mimeType),
    '이 비디오를 요약해줘',
  ]),
});

YouTube URL을 직접 전달하는 것도 가능하다.

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: [
    {
      fileData: {
        fileUri: 'https://www.youtube.com/watch?v=VIDEO_ID',
      },
    },
    { text: '이 영상의 핵심 내용을 알려줘' },
  ],
});

Google Cloud Storage 연동

2026년 1월부터 GCS에 저장된 파일을 직접 사용할 수 있게 되었다. 이미 GCS에 파일이 있다면 다시 업로드할 필요 없이 바로 등록해서 사용하면 된다.

IAM 권한 설정

먼저 Gemini API 서비스 에이전트에 스토리지 접근 권한을 부여해야 한다.

# 서비스 에이전트 생성
gcloud beta services identity create \
  --service=generativelanguage.googleapis.com \
  --project=YOUR_PROJECT_ID

# Storage Object Viewer 역할 부여
gcloud storage buckets add-iam-policy-binding gs://YOUR_BUCKET \
  --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-generativelanguage.iam.gserviceaccount.com" \
  --role="roles/storage.objectViewer"

GCS 파일 등록 및 사용

const registeredFiles = await ai.files.registerFiles({
  uris: [
    'gs://my-bucket/document.pdf',
    'gs://my-bucket/image.jpg',
  ],
});

for (const file of registeredFiles.files) {
  const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: [
      {
        fileData: {
          fileUri: file.uri,
          mimeType: file.mimeType,
        },
      },
      { text: '이 파일을 분석해줘' },
    ],
  });

  console.log(response.text);
}

GCS 등록의 장점은 Files API의 48시간 보관과 달리 30일까지 유지된다는 점이다.

Gemini API vs Vertex AI

Gemini API를 찾다 보면 Vertex AI라는 것도 나온다. 둘 다 같은 Gemini 모델을 사용하지만 접근 방식과 대상이 다르다.

Gemini API (Google AI Studio) 는 개인 개발자, 스타트업, 프로토타입 용도로 적합하다. API 키만 있으면 바로 시작할 수 있고, 무료 티어도 제공된다. 단, SLA가 없다.

Vertex AI 는 기업용 프로덕션 환경에 적합하다. GCP 프로젝트 설정이 필요하고 유료지만, SLA가 보장되고 MLOps 도구들이 함께 제공된다. 민감한 데이터를 다루거나 컴플라이언스가 중요한 경우에는 Vertex AI를 선택해야 한다.

좋은 점은 SDK가 동일하다는 것이다. 나중에 Vertex AI로 전환하고 싶다면 설정만 바꾸면 된다.

// Gemini API
const ai = new GoogleGenAI({ apiKey: 'KEY' });

// Vertex AI로 전환
const ai = new GoogleGenAI({
  vertexai: true,
  project: 'my-project',
  location: 'us-central1',
});

// 나머지 코드는 동일

사용 가능한 모델

2026년 2월 기준 주요 모델은 다음과 같다.

  • gemini-2.5-pro: 가장 강력한 stable 모델. adaptive thinking 지원.
  • gemini-2.5-flash: 빠르고 가성비 좋은 stable 모델. 일반적인 용도로 추천.
  • gemini-3-pro-preview: 최신 preview 모델. agentic, coding 특화.

참고로 Gemini 1.0, 1.5 모델은 이미 종료되었고, 2.0 Flash도 2026년 3월 3일에 종료 예정이다.

정리

Gemini API를 Node.js에서 사용하려면:

  1. @google/genai 패키지 설치
  2. Google AI Studio에서 API 키 발급
  3. GoogleGenAI 클라이언트 초기화 후 사용

멀티모달 파일은 100MB 미만이면 인라인 base64, 그 이상이거나 재사용이 필요하면 Files API를 사용하면 된다. GCS에 파일이 있다면 registerFiles로 바로 등록해서 쓸 수 있다.

프로토타입 단계에서는 Gemini API로 시작하고, 프로덕션으로 갈 때 필요하면 Vertex AI로 전환하는 전략이 합리적이다.

참고