Google GenAI SDK로 마이그레이션하기

Google GenAI SDK로 마이그레이션하기

2024년 말 Gemini 2.0 릴리스부터 Google GenAI SDK라는 새로운 라이브러리 세트를 도입했어요. 업데이트된 클라이언트 아키텍처를 통한 개선된 개발자 경험과, 개발자·엔터프라이즈 워크플로 간의 전환 단순화를 제공해요.

Google GenAI SDK는 이제 지원되는 모든 플랫폼에서 정식 출시(GA) 상태예요. 레거시 라이브러리 중 하나를 사용하고 있다면 마이그레이션을 강력히 권장해요.

이 가이드는 마이그레이션된 코드의 전·후 예시를 제공해 시작하는 데 도움을 줘요.

참고: Go 예시는 가독성을 위해 import와 기타 보일러플레이트 코드를 생략했어요.

출처: 문서

본문

설치

Before

Python

pip install -U -q "google-generativeai"

JavaScript

npm install @google/generative-ai

Go

go get github.com/google/generative-ai-go

Java

<dependency>
    <groupId>com.google.ai.client.generativeai</groupId>
    <artifactId>generativeai</artifactId>
    <version>0.9.0</version>
</dependency>

After

Python

pip install -U -q "google-genai"

JavaScript

npm install @google/genai

Go

go get google.golang.org/genai

Java

<dependency>
    <groupId>com.google.genai</groupId>
    <artifactId>google-genai</artifactId>
    <version>1.67.0</version>
</dependency>

API 접근

이전 SDK는 다양한 임시 방식으로 백그라운드에서 API 클라이언트를 암묵적으로 처리했어요. 이 때문에 클라이언트와 자격 증명을 관리하기 어려웠죠. 이제는 중앙의 Client 객체를 통해 상호작용해요. 이 Client 객체는 다양한 API 서비스(models, chats, files, tunings 등)의 단일 진입점 역할을 하여, 일관성을 높이고 여러 API 호출에 걸친 자격 증명·구성 관리를 단순화해요.

Before (덜 중앙화된 API 접근)

Python

이전 SDK는 대부분의 API 호출에서 최상위 클라이언트 객체를 명시적으로 사용하지 않았어요. GenerativeModel 객체를 직접 인스턴스화해 상호작용했죠.

import google.generativeai as genai

# Directly create and use model objects
model = genai.GenerativeModel('gemini-3.8-flash')
response = model.generate_content(...)
chat = model.start_chat(...)

JavaScript

GoogleGenerativeAI가 모델과 채팅의 중심 지점이었지만, 파일과 캐시 관리 같은 다른 기능은 종종 완전히 별도의 클라이언트 클래스를 import하고 인스턴스화해야 했어요.

import { GoogleGenerativeAI } from "@google/generative-ai";
import { GoogleAIFileManager, GoogleAICacheManager } from "@google/generative-ai/server"; // For files/caching

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
const fileManager = new GoogleAIFileManager("GEMINI_API_KEY");
const cacheManager = new GoogleAICacheManager("GEMINI_API_KEY");

// Get a model instance, then call methods on it
const model = genAI.getGenerativeModel({ model: "gemini-3.8-flash" });
const result = await model.generateContent(...);
const chat = model.startChat(...);

// Call methods on separate client objects for other services
const uploadedFile = await fileManager.uploadFile(...);
const cache = await cacheManager.create(...);

Java

import com.google.genai.Chat;
import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

// Previously, model operations were called on separate model instances
Client client = new Client();
GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", "Tell me a story.", null);
Chat chat = client.chats.create("gemini-3.8-flash");

Go

genai.NewClient 함수가 클라이언트를 만들었지만, 생성 모델 작업은 일반적으로 이 클라이언트에서 얻은 별도의 GenerativeModel 인스턴스에서 호출됐어요. 다른 서비스는 별도의 패키지나 패턴을 통해 접근했을 수 있어요.

import (
      "github.com/google/generative-ai-go/genai"
      "github.com/google/generative-ai-go/genai/fileman" // For files
      "google.golang.org/api/option"
)

client, err := genai.NewClient(ctx, option.WithAPIKey("GEMINI_API_KEY"))
fileClient, err := fileman.NewClient(ctx, option.WithAPIKey("GEMINI_API_KEY"))

// Get a model instance, then call methods on it
model := client.GenerativeModel("gemini-3.8-flash")
resp, err := model.GenerateContent(...)
cs := model.StartChat()

// Call methods on separate client objects for other services
uploadedFile, err := fileClient.UploadFile(...)

After (중앙화된 클라이언트 객체)

Python

from google import genai

# Create a single client object
client = genai.Client()

# Access API methods through services on the client object
response = client.models.generate_content(...)
chat = client.chats.create(...)
my_file = client.files.upload(...)
tuning_job = client.tunings.tune(...)

JavaScript

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

// Create a single client object
const ai = new GoogleGenAI({apiKey: "GEMINI_API_KEY"});

// Access API methods through services on the client object
const response = await ai.models.generateContent(...);
const chat = ai.chats.create(...);
const uploadedFile = await ai.files.upload(...);
const cache = await ai.caches.create(...);

Java

import com.google.genai.Chat;
import com.google.genai.Client;
import com.google.genai.types.CachedContent;
import com.google.genai.types.CreateCachedContentConfig;
import com.google.genai.types.File;
import com.google.genai.types.GenerateContentResponse;

// Create a single client object
Client client = new Client();

// Access API methods through services on the client object
GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", "Tell me a story.", null);
Chat chat = client.chats.create("gemini-3.8-flash");
File uploadedFile = client.files.upload("sample.txt", null);
CachedContent cache =
    client.caches.create("gemini-3.8-flash", CreateCachedContentConfig.builder().build());

Go

import "google.golang.org/genai"

// Create a single client object
client, err := genai.NewClient(ctx, nil)

// Access API methods through services on the client object
result, err := client.Models.GenerateContent(...)
chat, err := client.Chats.Create(...)
uploadedFile, err := client.Files.Upload(...)
tuningJob, err := client.Tunings.Tune(...)

인증

레거시 라이브러리와 새 라이브러리 모두 API 키로 인증해요. API 키는 Google AI Studio에서 만들 수 있어요.

Before

Python

이전 SDK는 API 클라이언트 객체를 암묵적으로 처리했어요.

import google.generativeai as genai

genai.configure(api_key=...)

JavaScript

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");

Java

import com.google.genai.Client;

// Passing the API key explicitly to the client builder
Client client = Client.builder().apiKey("GEMINI_API_KEY").build();

Go

Google 라이브러리를 import하세요.

import (
      "github.com/google/generative-ai-go/genai"
      "google.golang.org/api/option"
)

클라이언트를 만드세요.

client, err := genai.NewClient(ctx, option.WithAPIKey("GEMINI_API_KEY"))

After

Python

Google GenAI SDK에서는 먼저 API 클라이언트를 만들고, 이를 사용해 API를 호출해요. 새 SDK는 클라이언트에 API 키를 전달하지 않으면 GEMINI_API_KEY 환경 변수에서 API 키를 읽어와요.

export GEMINI_API_KEY="YOUR_API_KEY"

from google import genai

client = genai.Client() # Set the API key using the GEMINI_API_KEY env var.
                        # Alternatively, you could set the API key explicitly:
                        # client = genai.Client(api_key="YOUR_API_KEY")

JavaScript

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

const ai = new GoogleGenAI({apiKey: "GEMINI_API_KEY"});

Java

import com.google.genai.Client;

// The client automatically picks up the GEMINI_API_KEY environment variable,
// or you can pass it explicitly via Client.builder().apiKey("GEMINI_API_KEY").build()
Client client = new Client();

Go

GenAI 라이브러리를 import하세요.

import "google.golang.org/genai"

클라이언트를 만드세요.

client, err := genai.NewClient(ctx, &genai.ClientConfig{
        Backend:  genai.BackendGeminiAPI,
})

콘텐츠 생성

텍스트

Before

Python

이전에는 클라이언트 객체가 없고 GenerativeModel 객체를 통해 API에 직접 접근했어요.

import google.generativeai as genai

model = genai.GenerativeModel('gemini-3.8-flash')
response = model.generate_content(
    'Tell me a story in 300 words'
)
print(response.text)

JavaScript

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-3.8-flash" });
const prompt = "Tell me a story in 300 words";

const result = await model.generateContent(prompt);
console.log(result.response.text());

Java

import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();
String prompt = "Tell me a story in 300 words";

GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", prompt, null);
System.out.println(response.text());

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey("GEMINI_API_KEY"))
if err != nil {
    log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-3.8-flash")
resp, err := model.GenerateContent(ctx, genai.Text("Tell me a story in 300 words."))
if err != nil {
    log.Fatal(err)
}

printResponse(resp) // utility for printing response parts

After

Python

새 Google GenAI SDK는 Client 객체를 통해 모든 API 메서드에 접근할 수 있게 해 줘요. 몇 가지 상태가 있는 특수한 경우(chat과 live-api session)를 제외하면 모두 상태 없는 함수예요. 유틸리티와 일관성을 위해 반환되는 객체는 pydantic 클래스예요.

from google import genai
client = genai.Client()

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents='Tell me a story in 300 words.'
)
print(response.text)

print(response.model_dump_json(
    exclude_none=True, indent=4))

JavaScript

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

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: "Tell me a story in 300 words.",
});
console.log(response.text);

Java

import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash", "Tell me a story in 300 words.", null);
System.out.println(response.text());

Go

ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
if err != nil {
    log.Fatal(err)
}

result, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", genai.Text("Tell me a story in 300 words."), nil)
if err != nil {
    log.Fatal(err)
}
debugPrint(result) // utility for printing result

이미지

Before

Python

import google.generativeai as genai

model = genai.GenerativeModel('gemini-3.8-flash')
response = model.generate_content([
    'Tell me a story based on this image',
    Image.open(image_path)
])
print(response.text)

JavaScript

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
const model = genAI.getGenerativeModel({ model: "gemini-3.8-flash" });

function fileToGenerativePart(path, mimeType) {
  return {
    inlineData: {
      data: Buffer.from(fs.readFileSync(path)).toString("base64"),
      mimeType,
    },
  };
}

const prompt = "Tell me a story based on this image";

const imagePart = fileToGenerativePart(
  `path/to/organ.jpg`,
  "image/jpeg",
);

const result = await model.generateContent([prompt, imagePart]);
console.log(result.response.text());

Java

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("path/to/organ.jpg"));
Part imagePart = Part.fromBytes(imageBytes, "image/jpeg");

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash",
        Content.fromParts(Part.fromText("Tell me a story based on this image"), imagePart),
        null);
System.out.println(response.text());

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey("GEMINI_API_KEY"))
if err != nil {
    log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-3.8-flash")

imgData, err := os.ReadFile("path/to/organ.jpg")
if err != nil {
    log.Fatal(err)
}

resp, err := model.GenerateContent(ctx,
    genai.Text("Tell me about this instrument"),
    genai.ImageData("jpeg", imgData))
if err != nil {
    log.Fatal(err)
}

printResponse(resp) // utility for printing response

After

Python

새 SDK에도 많은 편의 기능이 존재해요. 예를 들어 PIL.Image 객체가 자동으로 변환돼요.

from google import genai
from PIL import Image

client = genai.Client()

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents=[
        'Tell me a story based on this image',
        Image.open(image_path)
    ]
)
print(response.text)

JavaScript

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

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

const organ = await ai.files.upload({
  file: "path/to/organ.jpg",
});

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    createUserContent([
      "Tell me a story based on this image",
      createPartFromUri(organ.uri, organ.mimeType)
    ]),
  ],
});
console.log(response.text);

Java

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.File;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Part;

Client client = new Client();

File organ = client.files.upload("path/to/organ.jpg", null);

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash",
        Content.fromParts(
            Part.fromText("Tell me a story based on this image"),
            Part.fromUri(organ.uri().orElse(""), organ.mimeType().orElse("image/jpeg"))),
        null);
System.out.println(response.text());

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
    log.Fatal(err)
}

imgData, err := os.ReadFile("path/to/organ.jpg")
if err != nil {
    log.Fatal(err)
}

parts := []*genai.Part{
    {Text: "Tell me a story based on this image"},
    {InlineData: &genai.Blob{Data: imgData, MIMEType: "image/jpeg"}},
}
contents := []*genai.Content{
    {Parts: parts},
}

result, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
    log.Fatal(err)
}
debugPrint(result) // utility for printing result

스트리밍

Before

Python

import google.generativeai as genai

response = model.generate_content(
    "Write a cute story about cats.",
    stream=True)
for chunk in response:
    print(chunk.text)

JavaScript

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
const model = genAI.getGenerativeModel({ model: "gemini-3.8-flash" });

const prompt = "Write a story about a magic backpack.";

const result = await model.generateContentStream(prompt);

// Print text as it comes in.
for await (const chunk of result.stream) {
  const chunkText = chunk.text();
  process.stdout.write(chunkText);
}

Java

import com.google.genai.Client;
import com.google.genai.ResponseStream;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();
String prompt = "Write a story about a magic backpack.";

try (ResponseStream<GenerateContentResponse> stream =
    client.models.generateContentStream("gemini-3.8-flash", prompt, null)) {
  for (GenerateContentResponse chunk : stream) {
    System.out.print(chunk.text());
  }
}

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey("GEMINI_API_KEY"))
if err != nil {
    log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-3.8-flash")
iter := model.GenerateContentStream(ctx, genai.Text("Write a story about a magic backpack."))
for {
    resp, err := iter.Next()
    if err == iterator.Done {
        break
    }
    if err != nil {
        log.Fatal(err)
    }
    printResponse(resp) // utility for printing the response
}

After

Python

from google import genai

client = genai.Client()

for chunk in client.models.generate_content_stream(
  model='gemini-3.8-flash',
  contents='Tell me a story in 300 words.'
):
    print(chunk.text)

JavaScript

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

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

const response = await ai.models.generateContentStream({
  model: "gemini-3.8-flash",
  contents: "Write a story about a magic backpack.",
});
let text = "";
for await (const chunk of response) {
  console.log(chunk.text);
  text += chunk.text;
}

Java

import com.google.genai.Client;
import com.google.genai.ResponseStream;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();

try (ResponseStream<GenerateContentResponse> response =
    client.models.generateContentStream(
        "gemini-3.8-flash", "Tell me a story in 300 words.", null)) {
  for (GenerateContentResponse chunk : response) {
    System.out.println(chunk.text());
  }
}

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
    log.Fatal(err)
}

for result, err := range client.Models.GenerateContentStream(
    ctx,
    "gemini-3.8-flash",
    genai.Text("Write a story about a magic backpack."),
    nil,
) {
    if err != nil {
        log.Fatal(err)
    }
    fmt.Print(result.Candidates[0].Content.Parts[0].Text)
}

구성

Before

Python

import google.generativeai as genai

model = genai.GenerativeModel(
  'gemini-3.8-flash',
    system_instruction='you are a story teller for kids under 5 years old',
    generation_config=genai.GenerationConfig(
      max_output_tokens=400,
      top_k=2,
      top_p=0.5,
      temperature=0.5,
      response_mime_type='application/json',
      stop_sequences=['\n'],
    )
)
response = model.generate_content('tell me a story in 100 words')

JavaScript

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
const model = genAI.getGenerativeModel({
  model: "gemini-3.8-flash",
  generationConfig: {
    candidateCount: 1,
    stopSequences: ["x"],
    maxOutputTokens: 20,
    temperature: 1.0,
  },
});

const result = await model.generateContent(
  "Tell me a story about a magic backpack.",
);
console.log(result.response.text())

Java

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Part;
import java.util.Arrays;

Client client = new Client();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .systemInstruction(
            Content.fromParts(Part.fromText("you are a story teller for kids under 5 years old")))
        .maxOutputTokens(400)
        .topK(2.0f)
        .topP(0.5f)
        .temperature(0.5f)
        .responseMimeType("application/json")
        .stopSequences(Arrays.asList("\n"))
        .build();

GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", "tell me a story in 100 words", config);
System.out.println(response.text());

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey("GEMINI_API_KEY"))
if err != nil {
    log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-3.8-flash")
model.SetTemperature(0.5)
model.SetTopP(0.5)
model.SetTopK(2.0)
model.SetMaxOutputTokens(100)
model.ResponseMIMEType = "application/json"
resp, err := model.GenerateContent(ctx, genai.Text("Tell me about New York"))
if err != nil {
    log.Fatal(err)
}
printResponse(resp) // utility for printing response

After

Python

새 SDK의 모든 메서드에서 필수 인자는 키워드 인자로 제공돼요. 모든 선택 입력은 config 인자로 제공돼요. 설정 인자는 Python 딕셔너리 또는 google.genai.types 네임스페이스의 Config 클래스로 지정할 수 있어요. 유틸리티와 일관성을 위해 types 모듈 내의 모든 정의는 pydantic 클래스예요.

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
  model='gemini-3.8-flash',
  contents='Tell me a story in 100 words.',
  config=types.GenerateContentConfig(
      system_instruction='you are a story teller for kids under 5 years old',
      max_output_tokens= 400,
      top_k= 2,
      top_p= 0.5,
      temperature= 0.5,
      response_mime_type= 'application/json',
      stop_sequences= ['\n'],
      seed=42,
  ),
)

JavaScript

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

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: "Tell me a story about a magic backpack.",
  config: {
    candidateCount: 1,
    stopSequences: ["x"],
    maxOutputTokens: 20,
    temperature: 1.0,
  },
});

console.log(response.text);

Java

import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import java.util.Arrays;

Client client = new Client();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .candidateCount(1)
        .stopSequences(Arrays.asList("x"))
        .maxOutputTokens(20)
        .temperature(1.0f)
        .build();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash", "Tell me a story about a magic backpack.", config);
System.out.println(response.text());

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
    log.Fatal(err)
}

result, err := client.Models.GenerateContent(ctx,
    "gemini-3.8-flash",
    genai.Text("Tell me about New York"),
    &genai.GenerateContentConfig{
        Temperature:      genai.Ptr[float32](0.5),
        TopP:             genai.Ptr[float32](0.5),
        TopK:             genai.Ptr[float32](2.0),
        ResponseMIMEType: "application/json",
        StopSequences:    []string{"Yankees"},
        CandidateCount:   2,
        Seed:             genai.Ptr[int32](42),
        MaxOutputTokens:  128,
        PresencePenalty:  genai.Ptr[float32](0.5),
        FrequencyPenalty: genai.Ptr[float32](0.5),
    },
)
if err != nil {
    log.Fatal(err)
}
debugPrint(result) // utility for printing response

안전 설정

안전 설정으로 응답을 생성하세요.

Before

Python

import google.generativeai as genai

model = genai.GenerativeModel('gemini-3.8-flash')
response = model.generate_content(
    'say something bad',
    safety_settings={
        'HATE': 'BLOCK_ONLY_HIGH',
        'HARASSMENT': 'BLOCK_ONLY_HIGH',
  }
)

JavaScript

import { GoogleGenerativeAI, HarmCategory, HarmBlockThreshold } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
const model = genAI.getGenerativeModel({
  model: "gemini-3.8-flash",
  safetySettings: [
    {
      category: HarmCategory.HARM_CATEGORY_HARASSMENT,
      threshold: HarmBlockThreshold.BLOCK_LOW_AND_ABOVE,
    },
  ],
});

const unsafePrompt =
  "I support Martians Soccer Club and I think " +
  "Jupiterians Football Club sucks! Write an ironic phrase telling " +
  "them how I feel about them.";

const result = await model.generateContent(unsafePrompt);

try {
  result.response.text();
} catch (e) {
  console.error(e);
  console.log(result.response.candidates[0].safetyRatings);
}

Java

import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.HarmBlockThreshold;
import com.google.genai.types.HarmCategory;
import com.google.genai.types.SafetySetting;
import java.util.Arrays;

Client client = new Client();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .safetySettings(
            Arrays.asList(
                SafetySetting.builder()
                    .category(HarmCategory.Known.HARM_CATEGORY_HARASSMENT)
                    .threshold(HarmBlockThreshold.Known.BLOCK_LOW_AND_ABOVE)
                    .build()))
        .build();

GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", "say something bad", config);
System.out.println(response.text());

After

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
  model='gemini-3.8-flash',
  contents='say something bad',
  config=types.GenerateContentConfig(
      safety_settings= [
          types.SafetySetting(
              category='HARM_CATEGORY_HATE_SPEECH',
              threshold='BLOCK_ONLY_HIGH'
          ),
      ]
  ),
)

JavaScript

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

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
const unsafePrompt =
  "I support Martians Soccer Club and I think " +
  "Jupiterians Football Club sucks! Write an ironic phrase telling " +
  "them how I feel about them.";

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: unsafePrompt,
  config: {
    safetySettings: [
      {
        category: "HARM_CATEGORY_HARASSMENT",
        threshold: "BLOCK_ONLY_HIGH",
      },
    ],
  },
});

console.log("Finish reason:", response.candidates[0].finishReason);
console.log("Safety ratings:", response.candidates[0].safetyRatings);

Java

import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.HarmBlockThreshold;
import com.google.genai.types.HarmCategory;
import com.google.genai.types.SafetySetting;
import java.util.Arrays;

Client client = new Client();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .safetySettings(
            Arrays.asList(
                SafetySetting.builder()
                    .category(HarmCategory.Known.HARM_CATEGORY_HATE_SPEECH)
                    .threshold(HarmBlockThreshold.Known.BLOCK_ONLY_HIGH)
                    .build()))
        .build();

GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", "say something bad", config);
System.out.println("Finish reason: " + response.finishReason());

Async

Before

Python

import google.generativeai as genai

model = genai.GenerativeModel('gemini-3.8-flash')
response = model.generate_content_async(
    'tell me a story in 100 words'
)

After

Python

asyncio와 함께 새 SDK를 사용하려면 client.aio 아래에 모든 메서드의 별도 async 구현이 있어요.

from google import genai

client = genai.Client()

response = await client.aio.models.generate_content(
    model='gemini-3.8-flash',
    contents='Tell me a story in 300 words.'
)

채팅

채팅을 시작하고 모델에 메시지를 보내세요.

Before

Python

import google.generativeai as genai

model = genai.GenerativeModel('gemini-3.8-flash')
chat = model.start_chat()

response = chat.send_message(
    "Tell me a story in 100 words")
response = chat.send_message(
    "What happened after that?")

JavaScript

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
const model = genAI.getGenerativeModel({ model: "gemini-3.8-flash" });
const chat = model.startChat({
  history: [
    {
      role: "user",
      parts: [{ text: "Hello" }],
    },
    {
      role: "model",
      parts: [{ text: "Great to meet you. What would you like to know?" }],
    },
  ],
});
let result = await chat.sendMessage("I have 2 dogs in my house.");
console.log(result.response.text());
result = await chat.sendMessage("How many paws are in my house?");
console.log(result.response.text());

Java

import com.google.genai.Chat;
import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();
Chat chat = client.chats.create("gemini-3.8-flash");

GenerateContentResponse response1 = chat.sendMessage("Tell me a story in 100 words");
System.out.println(response1.text());

GenerateContentResponse response2 = chat.sendMessage("What happened after that?");
System.out.println(response2.text());

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey("GEMINI_API_KEY"))
if err != nil {
    log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-3.8-flash")
cs := model.StartChat()

cs.History = []*genai.Content{
    {
        Parts: []genai.Part{
            genai.Text("Hello, I have 2 dogs in my house."),
        },
        Role: "user",
    },
    {
        Parts: []genai.Part{
            genai.Text("Great to meet you. What would you like to know?"),
        },
        Role: "model",
    },
}

res, err := cs.SendMessage(ctx, genai.Text("How many paws are in my house?"))
if err != nil {
    log.Fatal(err)
}
printResponse(res) // utility for printing the response

After

Python

from google import genai

client = genai.Client()

chat = client.chats.create(model='gemini-3.8-flash')

response = chat.send_message(
    message='Tell me a story in 100 words')
response = chat.send_message(
    message='What happened after that?')

JavaScript

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

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
const chat = ai.chats.create({
  model: "gemini-3.8-flash",
  history: [
    {
      role: "user",
      parts: [{ text: "Hello" }],
    },
    {
      role: "model",
      parts: [{ text: "Great to meet you. What would you like to know?" }],
    },
  ],
});

const response1 = await chat.sendMessage({
  message: "I have 2 dogs in my house.",
});
console.log("Chat response 1:", response1.text);

const response2 = await chat.sendMessage({
  message: "How many paws are in my house?",
});
console.log("Chat response 2:", response2.text);

Java

import com.google.genai.Chat;
import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();
Chat chat = client.chats.create("gemini-3.8-flash");

GenerateContentResponse response1 = chat.sendMessage("I have 2 dogs in my house.");
System.out.println("Chat response 1: " + response1.text());

GenerateContentResponse response2 = chat.sendMessage("How many paws are in my house?");
System.out.println("Chat response 2: " + response2.text());

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
    log.Fatal(err)
}

chat, err := client.Chats.Create(ctx, "gemini-3.8-flash", nil, nil)
if err != nil {
    log.Fatal(err)
}

result, err := chat.SendMessage(ctx, genai.Part{Text: "Hello, I have 2 dogs in my house."})
if err != nil {
    log.Fatal(err)
}
debugPrint(result) // utility for printing result

result, err = chat.SendMessage(ctx, genai.Part{Text: "How many paws are in my house?"})
if err != nil {
    log.Fatal(err)
}
debugPrint(result) // utility for printing result

함수 호출

Before

Python

import google.generativeai as genai
from enum import Enum

def get_current_weather(location: str) -> str:
    """Get the current whether in a given location.

    Args:
        location: required, The city and state, e.g. San Franciso, CA
        unit: celsius or fahrenheit
    """
    print(f'Called with: {location=}')
    return "23C"

model = genai.GenerativeModel(
    model_name="gemini-3.8-flash",
    tools=[get_current_weather]
)

response = model.generate_content("What is the weather in San Francisco?")
function_call = response.candidates[0].parts[0].function_call

After

Python

새 SDK에서는 자동 함수 호출이 기본값이에요. 여기서는 이를 비활성화해요.

from google import genai
from google.genai import types

client = genai.Client()

def get_current_weather(location: str) -> str:
    """Get the current whether in a given location.

    Args:
        location: required, The city and state, e.g. San Franciso, CA
        unit: celsius or fahrenheit
    """
    print(f'Called with: {location=}')
    return "23C"

response = client.models.generate_content(
  model='gemini-3.8-flash',
  contents="What is the weather like in Boston?",
  config=types.GenerateContentConfig(
      tools=[get_current_weather],
      automatic_function_calling={'disable': True},
  ),
)

function_call = response.candidates[0].content.parts[0].function_call

자동 함수 호출

Before

Python

이전 SDK는 채팅에서만 자동 함수 호출을 지원했어요. 새 SDK에서는 generate_content에서 이것이 기본 동작이에요.

import google.generativeai as genai

def get_current_weather(city: str) -> str:
    return "23C"

model = genai.GenerativeModel(
    model_name="gemini-3.8-flash",
    tools=[get_current_weather]
)

chat = model.start_chat(
    enable_automatic_function_calling=True)
result = chat.send_message("What is the weather in San Francisco?")

After

Python

from google import genai
from google.genai import types
client = genai.Client()

def get_current_weather(city: str) -> str:
    return "23C"

response = client.models.generate_content(
  model='gemini-3.8-flash',
  contents="What is the weather like in Boston?",
  config=types.GenerateContentConfig(
      tools=[get_current_weather]
  ),
)

코드 실행

코드 실행은 모델이 Python 코드를 생성하고 실행하며 결과를 반환할 수 있게 하는 도구예요.

Before

Python

import google.generativeai as genai

model = genai.GenerativeModel(
    model_name="gemini-3.8-flash",
    tools="code_execution"
)

result = model.generate_content(
  "What is the sum of the first 50 prime numbers? Generate and run code for "
  "the calculation, and make sure you get all 50.")

JavaScript

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
const model = genAI.getGenerativeModel({
  model: "gemini-3.8-flash",
  tools: [{ codeExecution: {} }],
});

const result = await model.generateContent(
  "What is the sum of the first 50 prime numbers? " +
    "Generate and run code for the calculation, and make sure you get " +
    "all 50.",
);

console.log(result.response.text());

Java

import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Tool;
import com.google.genai.types.ToolCodeExecution;
import java.util.Arrays;

Client client = new Client();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .tools(
            Arrays.asList(
                Tool.builder().codeExecution(ToolCodeExecution.builder().build()).build()))
        .build();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash",
        "What is the sum of the first 50 prime numbers? Generate and run code for "
            + "the calculation, and make sure you get all 50.",
        config);
System.out.println(response.text());

After

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents='What is the sum of the first 50 prime numbers? Generate and run '
            'code for the calculation, and make sure you get all 50.',
    config=types.GenerateContentConfig(
        tools=[types.Tool(code_execution=types.ToolCodeExecution)],
    ),
)

JavaScript

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

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: `Write and execute code that calculates the sum of the first 50 prime numbers.
            Ensure that only the executable code and its resulting output are generated.`,
});

// Each part may contain text, executable code, or an execution result.
for (const part of response.candidates[0].content.parts) {
  console.log(part);
  console.log("\n");
}

console.log("-".repeat(80));
// The `.text` accessor concatenates the parts into a markdown-formatted text.
console.log("\n", response.text);

Java

import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Part;
import com.google.genai.types.Tool;
import com.google.genai.types.ToolCodeExecution;
import java.util.Arrays;

Client client = new Client();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .tools(
            Arrays.asList(
                Tool.builder().codeExecution(ToolCodeExecution.builder().build()).build()))
        .build();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash",
        "Write and execute code that calculates the sum of the first 50 prime numbers. "
            + "Ensure that only the executable code and its resulting output are generated.",
        config);

if (response.parts() != null) {
  for (Part part : response.parts()) {
    System.out.println(part);
  }
}
System.out.println(response.text());

검색 그라운딩

GoogleSearch(Gemini>=2.0)와 GoogleSearchRetrieval(Gemini < 2.0)은 모델이 Google 제공의 공개 웹 데이터를 검색해 그라운딩할 수 있게 하는 도구예요.

Before

Python

import google.generativeai as genai

model = genai.GenerativeModel('gemini-3.8-flash')
response = model.generate_content(
    contents="what is the Google stock price?",
    tools='google_search_retrieval'
)

After

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents='What is the Google stock price?',
    config=types.GenerateContentConfig(
        tools=[
            types.Tool(
                google_search=types.GoogleSearch()
            )
        ]
    )
)

JSON 응답

JSON 형식으로 답변을 생성하세요.

Before

Python

response_schema를 지정하고 response_mime_type="application/json"으로 설정하면 사용자가 주어진 구조를 따르는 JSON 응답을 생성하도록 모델을 제한할 수 있어요.

import google.generativeai as genai
import typing_extensions as typing

class CountryInfo(typing.TypedDict):
    name: str
    population: int
    capital: str
    continent: str
    major_cities: list[str]
    gdp: int
    official_language: str
    total_area_sq_mi: int

model = genai.GenerativeModel(model_name="gemini-3.8-flash")
result = model.generate_content(
    "Give me information of the United States",
    generation_config=genai.GenerationConfig(
        response_mime_type="application/json",
        response_schema = CountryInfo
    ),
)

JavaScript

import { GoogleGenerativeAI, SchemaType } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");

const schema = {
  description: "List of recipes",
  type: SchemaType.ARRAY,
  items: {
    type: SchemaType.OBJECT,
    properties: {
      recipeName: {
        type: SchemaType.STRING,
        description: "Name of the recipe",
        nullable: false,
      },
    },
    required: ["recipeName"],
  },
};

const model = genAI.getGenerativeModel({
  model: "gemini-3.8-flash",
  generationConfig: {
    responseMimeType: "application/json",
    responseSchema: schema,
  },
});

const result = await model.generateContent(
  "List a few popular cookie recipes.",
);
console.log(result.response.text());

Java

import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Schema;
import com.google.genai.types.Type;
import java.util.Arrays;
import java.util.Map;

Client client = new Client();

Schema schema =
    Schema.builder()
        .description("List of recipes")
        .type(Type.Known.ARRAY)
        .items(
            Schema.builder()
                .type(Type.Known.OBJECT)
                .properties(
                    Map.of(
                        "recipeName",
                        Schema.builder()
                            .type(Type.Known.STRING)
                            .description("Name of the recipe")
                            .build()))
                .required(Arrays.asList("recipeName"))
                .build())
        .build();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .responseMimeType("application/json")
        .responseSchema(schema)
        .build();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash", "List a few popular cookie recipes.", config);
System.out.println(response.text());

After

Python

새 SDK는 스키마를 제공하기 위해 pydantic 클래스를 사용해요(genai.types.Schema 또는 그에 해당하는 dict를 전달할 수도 있음). 가능하면 SDK는 반환된 JSON을 파싱해 response.parsed에 결과를 반환해요. 스키마로 pydantic 클래스를 제공하면 SDK는 그 JSON을 클래스 인스턴스로 변환해요.

from google import genai
from pydantic import BaseModel

client = genai.Client()

class CountryInfo(BaseModel):
    name: str
    population: int
    capital: str
    continent: str
    major_cities: list[str]
    gdp: int
    official_language: str
    total_area_sq_mi: int

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents='Give me information of the United States.',
    config={
        'response_mime_type': 'application/json',
        'response_schema': CountryInfo,
    },
)

response.parsed

JavaScript

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

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: "List a few popular cookie recipes.",
  config: {
    responseMimeType: "application/json",
    responseSchema: {
      type: "array",
      items: {
        type: "object",
        properties: {
          recipeName: { type: "string" },
          ingredients: { type: "array", items: { type: "string" } },
        },
        required: ["recipeName", "ingredients"],
      },
    },
  },
});
console.log(response.text);

Java

import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Schema;
import com.google.genai.types.Type;
import java.util.Arrays;
import java.util.Map;

Client client = new Client();

Schema schema =
    Schema.builder()
        .type(Type.Known.ARRAY)
        .items(
            Schema.builder()
                .type(Type.Known.OBJECT)
                .properties(
                    Map.of(
                        "recipeName", Schema.builder().type(Type.Known.STRING).build(),
                        "ingredients",
                            Schema.builder()
                                .type(Type.Known.ARRAY)
                                .items(Schema.builder().type(Type.Known.STRING).build())
                                .build()))
                .required(Arrays.asList("recipeName", "ingredients"))
                .build())
        .build();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .responseMimeType("application/json")
        .responseSchema(schema)
        .build();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash", "List a few popular cookie recipes.", config);
System.out.println(response.text());

파일

업로드

파일을 업로드하세요.

Before

Python

import requests
import pathlib
import google.generativeai as genai

# Download file
response = requests.get(
    'https://storage.googleapis.com/generativeai-downloads/data/a11.txt')
pathlib.Path('a11.txt').write_text(response.text)

file = genai.upload_file(path='a11.txt')

model = genai.GenerativeModel('gemini-3.8-flash')
response = model.generate_content([
    'Can you summarize this file:',
    my_file
])
print(response.text)

After

Python

import requests
import pathlib
from google import genai

client = genai.Client()

# Download file
response = requests.get(
    'https://storage.googleapis.com/generativeai-downloads/data/a11.txt')
pathlib.Path('a11.txt').write_text(response.text)

my_file = client.files.upload(file='a11.txt')

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents=[
        'Can you summarize this file:',
        my_file
    ]
)
print(response.text)

나열 및 가져오기

업로드된 파일을 나열하고 파일 이름으로 업로드된 파일을 가져오세요.

Before

Python

import google.generativeai as genai

for file in genai.list_files():
  print(file.name)

file = genai.get_file(name=file.name)

After

Python

from google import genai
client = genai.Client()

for file in client.files.list():
    print(file.name)

file = client.files.get(name=file.name)

삭제

파일을 삭제하세요.

Before

Python

import pathlib
import google.generativeai as genai

pathlib.Path('dummy.txt').write_text(dummy)
dummy_file = genai.upload_file(path='dummy.txt')

file = genai.delete_file(name=dummy_file.name)

After

Python

import pathlib
from google import genai

client = genai.Client()

pathlib.Path('dummy.txt').write_text(dummy)
dummy_file = client.files.upload(file='dummy.txt')

response = client.files.delete(name=dummy_file.name)

컨텍스트 캐싱

컨텍스트 캐싱은 사용자가 콘텐츠를 모델에 한 번 전달하고, 입력 토큰을 캐시한 다음, 후속 호출에서 캐시된 토큰을 참조해 비용을 낮출 수 있게 해 줘요.

Before

Python

import requests
import pathlib
import google.generativeai as genai
from google.generativeai import caching

# Download file
response = requests.get(
    'https://storage.googleapis.com/generativeai-downloads/data/a11.txt')
pathlib.Path('a11.txt').write_text(response.text)

# Upload file
document = genai.upload_file(path="a11.txt")

# Create cache
apollo_cache = caching.CachedContent.create(
    model="gemini-3.8-flash",
    system_instruction="You are an expert at analyzing transcripts.",
    contents=[document],
)

# Generate response
apollo_model = genai.GenerativeModel.from_cached_content(
    cached_content=apollo_cache
)
response = apollo_model.generate_content("Find a lighthearted moment from this transcript")

JavaScript

import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
import { GoogleGenerativeAI } from "@google/generative-ai";

const cacheManager = new GoogleAICacheManager("GEMINI_API_KEY");
const fileManager = new GoogleAIFileManager("GEMINI_API_KEY");

const uploadResult = await fileManager.uploadFile("path/to/a11.txt", {
  mimeType: "text/plain",
});

const cacheResult = await cacheManager.create({
  model: "models/gemini-3.8-flash",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: uploadResult.file.uri,
            mimeType: uploadResult.file.mimeType,
          },
        },
      ],
    },
  ],
});

console.log(cacheResult);

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
const model = genAI.getGenerativeModelFromCachedContent(cacheResult);
const result = await model.generateContent(
  "Please summarize this transcript.",
);
console.log(result.response.text());

Java

import com.google.genai.Client;
import com.google.genai.types.CachedContent;
import com.google.genai.types.Content;
import com.google.genai.types.CreateCachedContentConfig;
import com.google.genai.types.File;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Part;
import java.util.Arrays;

Client client = new Client();

File uploadResult = client.files.upload("path/to/a11.txt", null);

CachedContent cacheResult =
    client.caches.create(
        "gemini-3.8-flash",
        CreateCachedContentConfig.builder()
            .contents(
                Arrays.asList(
                    Content.fromParts(
                        Part.fromUri(
                            uploadResult.uri().orElse(""),
                            uploadResult.mimeType().orElse("text/plain")))))
            .systemInstruction(
                Content.fromParts(Part.fromText("You are an expert at analyzing transcripts.")))
            .build());

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash",
        "Please summarize this transcript.",
        GenerateContentConfig.builder().cachedContent(cacheResult.name().orElse("")).build());
System.out.println(response.text());

After

Python

import requests
import pathlib
from google import genai
from google.genai import types

client = genai.Client()

# Check which models support caching.
for m in client.models.list():
  for action in m.supported_actions:
    if action == "createCachedContent":
      print(m.name)
      break

# Download file
response = requests.get(
    'https://storage.googleapis.com/generativeai-downloads/data/a11.txt')
pathlib.Path('a11.txt').write_text(response.text)

# Upload file
document = client.files.upload(file='a11.txt')

# Create cache
model='gemini-3.8-flash'
apollo_cache = client.caches.create(
      model=model,
      config={
          'contents': [document],
          'system_instruction': 'You are an expert at analyzing transcripts.',
      },
  )

# Generate response
response = client.models.generate_content(
    model=model,
    contents='Find a lighthearted moment from this transcript',
    config=types.GenerateContentConfig(
        cached_content=apollo_cache.name,
    )
)

JavaScript

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

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
const filePath = path.join(media, "a11.txt");
const document = await ai.files.upload({
  file: filePath,
  config: { mimeType: "text/plain" },
});
console.log("Uploaded file name:", document.name);
const modelName = "gemini-3.8-flash";

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: "You are an expert analyzing transcripts.",
  },
});
console.log("Cache created:", cache);

const response = await ai.models.generateContent({
  model: modelName,
  contents: "Please summarize this transcript",
  config: { cachedContent: cache.name },
});
console.log("Response text:", response.text);

Java

import com.google.genai.Client;
import com.google.genai.types.CachedContent;
import com.google.genai.types.Content;
import com.google.genai.types.CreateCachedContentConfig;
import com.google.genai.types.File;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Part;
import java.util.Arrays;

Client client = new Client();

File document = client.files.upload("a11.txt", null);
String modelName = "gemini-3.8-flash";

CachedContent cache =
    client.caches.create(
        modelName,
        CreateCachedContentConfig.builder()
            .contents(
                Arrays.asList(
                    Content.fromParts(
                        Part.fromUri(
                            document.uri().orElse(""), document.mimeType().orElse("text/plain")))))
            .systemInstruction(
                Content.fromParts(Part.fromText("You are an expert analyzing transcripts.")))
            .build());

GenerateContentResponse response =
    client.models.generateContent(
        modelName,
        "Find a lighthearted moment from this transcript",
        GenerateContentConfig.builder().cachedContent(cache.name().orElse("")).build());
System.out.println(response.text());

토큰 수 세기

요청의 토큰 수를 세세요.

Before

Python

import google.generativeai as genai

model = genai.GenerativeModel('gemini-3.8-flash')
response = model.count_tokens(
    'The quick brown fox jumps over the lazy dog.')

JavaScript

 import { GoogleGenerativeAI } from "@google/generative-ai";

 const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
 const model = genAI.getGenerativeModel({
   model: "gemini-3.8-flash",
 });

 // Count tokens in a prompt without calling text generation.
 const countResult = await model.countTokens(
   "The quick brown fox jumps over the lazy dog.",
 );

 console.log(countResult.totalTokens); // 11

 const generateResult = await model.generateContent(
   "The quick brown fox jumps over the lazy dog.",
 );

 // On the response for `generateContent`, use `usageMetadata`
 // to get separate input and output token counts
 // (`promptTokenCount` and `candidatesTokenCount`, respectively),
 // as well as the combined token count (`totalTokenCount`).
 console.log(generateResult.response.usageMetadata);
 // candidatesTokenCount and totalTokenCount depend on response, may vary
 // { promptTokenCount: 11, candidatesTokenCount: 124, totalTokenCount: 135 }

Java

import com.google.genai.Client;
import com.google.genai.types.CountTokensResponse;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();
String prompt = "The quick brown fox jumps over the lazy dog.";

CountTokensResponse countResult = client.models.countTokens("gemini-3.8-flash", prompt, null);
System.out.println(countResult.totalTokens().orElse(0));

GenerateContentResponse generateResult =
    client.models.generateContent("gemini-3.8-flash", prompt, null);
System.out.println(generateResult.usageMetadata());

After

Python

from google import genai

client = genai.Client()

response = client.models.count_tokens(
    model='gemini-3.8-flash',
    contents='The quick brown fox jumps over the lazy dog.',
)

JavaScript

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

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
const prompt = "The quick brown fox jumps over the lazy dog.";
const countTokensResponse = await ai.models.countTokens({
  model: "gemini-3.8-flash",
  contents: prompt,
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: prompt,
});
console.log(generateResponse.usageMetadata);

Java

import com.google.genai.Client;
import com.google.genai.types.CountTokensResponse;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();
String prompt = "The quick brown fox jumps over the lazy dog.";

CountTokensResponse countTokensResponse =
    client.models.countTokens("gemini-3.8-flash", prompt, null);
System.out.println(countTokensResponse.totalTokens().orElse(0));

GenerateContentResponse generateResponse =
    client.models.generateContent("gemini-3.8-flash", prompt, null);
System.out.println(generateResponse.usageMetadata());

이미지 생성

이미지를 생성하세요.

Before

Python

#pip install https://github.com/google-gemini/generative-ai-python@imagen
import google.generativeai as genai

imagen = genai.ImageGenerationModel(
    "imagen-3.0-generate-001")
gen_images = imagen.generate_images(
    prompt="Robot holding a red skateboard",
    number_of_images=1,
    safety_filter_level="block_low_and_above",
    person_generation="allow_adult",
    aspect_ratio="3:4",
)

After

Python

from google import genai

client = genai.Client()

gen_images = client.models.generate_images(
    model='gemini-2.5-flash-image',
    prompt='Robot holding a red skateboard',
    config=types.GenerateImagesConfig(
        number_of_images= 1,
        safety_filter_level= "BLOCK_LOW_AND_ABOVE",
        person_generation= "ALLOW_ADULT",
        aspect_ratio= "3:4",
    )
)

for n, image in enumerate(gen_images.generated_images):
    pathlib.Path(f'{n}.png').write_bytes(
        image.image.image_bytes)

콘텐츠 임베딩

콘텐츠 임베딩을 생성하세요.

Before

Python

import google.generativeai as genai

response = genai.embed_content(
  model='models/gemini-embedding-001',
  content='Hello world'
)

JavaScript

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
const model = genAI.getGenerativeModel({
  model: "gemini-embedding-001",
});

const result = await model.embedContent("Hello world!");

console.log(result.embedding);

Java

import com.google.genai.Client;
import com.google.genai.types.EmbedContentResponse;

Client client = new Client();

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-001", "Hello world!", null);
System.out.println(response.embeddings());

After

Python

from google import genai

client = genai.Client()

response = client.models.embed_content(
  model='gemini-embedding-001',
  contents='Hello world',
)

JavaScript

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

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
const text = "Hello World!";
const result = await ai.models.embedContent({
  model: "gemini-embedding-001",
  contents: text,
  config: { outputDimensionality: 10 },
});
console.log(result.embeddings);

Java

import com.google.genai.Client;
import com.google.genai.types.EmbedContentConfig;
import com.google.genai.types.EmbedContentResponse;

Client client = new Client();
String text = "Hello World!";

EmbedContentResponse result =
    client.models.embedContent(
        "gemini-embedding-001",
        text,
        EmbedContentConfig.builder().outputDimensionality(10).build());
System.out.println(result.embeddings());

더 알아보기 (Learn more)

Google GenAI SDK는 클라이언트 아키텍처를 중앙화하고 자동 함수 호출을 기본으로 지원하며 pydantic 클래스를 사용하는 등 레거시 SDK보다 개선된 개발자 경험을 제공해요. 개발자와 엔터프라이즈 워크플로 간 전환에 대한 안내는 클라우드로 마이그레이션 문서를 이어서 살펴보세요.