설치와 GoogleGenAI

설치할 패키지는 @google/genai야

공식 TypeScript/JavaScript SDK는 npm 범위 패키지인 @google/genai야. 2025년 8월에 수명 종료(EOL)된 @google/generative-ai를 대체하며, Node.js 20 이상이 필요해.

만들 클래스는 하나야

진입점은 GoogleGenAI야. Python SDK와 대응하는 생성 패턴은 세 가지야:

new GoogleGenAI({ apiKey: '...' }) — 키를 직접 지정해.
new GoogleGenAI({}) — Node.js 환경에서 GOOGLE_API_KEY를 읽어.
new GoogleGenAI({ vertexai: true, project: '...', location: '...' }) — Vertex AI에 연결해.

하위 모듈

생성한 ai 객체는 Python 클라이언트와 대응하는 API를 제공해:

ai.models — 생성, 스트리밍, 토큰 계산.
ai.chats — 여러 차례 이어지는 채팅.
ai.files — File API 업로드.
ai.caches — 컨텍스트 캐싱.
ai.live — 실시간 멀티모달 세션.

자주 쓰는 도우미 import

이 패키지는 스키마 도우미와 콘텐츠 생성 함수도 내보내:

Type — Type.STRING, Type.OBJECT 같은 스키마 형식 열거형.
createUserContent, createPartFromUri — 멀티모달 콘텐츠 작성기.
FunctionCallingConfigMode — AUTO, ANY, NONE.
ApiError — 예외 클래스.

Code

설치·bash

npm install @google/genai
# or
pnpm add @google/genai
# or
bun add @google/genai

클라이언트 생성 패턴·typescript

import {
  GoogleGenAI,
  Type,
  ApiError,
  FunctionCallingConfigMode,
  ThinkingLevel,
  createUserContent,
  createPartFromUri,
} from '@google/genai';

// 1. Explicit key
const ai = new GoogleGenAI({ apiKey: 'AIzaSy...' });

// 2. From env (set GOOGLE_API_KEY first)
const ai = new GoogleGenAI({});

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

// 4. Pin a specific API version
const ai = new GoogleGenAI({ apiKey: 'KEY', apiVersion: 'v1' });

첫 호출·typescript

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: 'Hello, Gemini!',
});
console.log(response.text);  // property, not method

Exercise

새 Node 프로젝트(npm init -y)에 @google/genai를 설치해. 환경 변수로 클라이언트를 만들고 Flash 응답을 출력하는 작은 hello.mjs를 작성한 뒤 Node 20 이상인지 확인해. 보너스로 같은 코드를 Bun 프로젝트에서도 실행해 봐. 수정 없이 작동해야 해.