# 迁移到 Google GenAI SDK

从 Gemini 2.0 版本开始，2024, 后期我们引入了一组新的库，称为 [Google GenAI SDK](/docs/libraries)。它通过以下方式提供了改进的开发人员体验 [更新的客户端架构](/docs/migrate#client), 和 [简化过渡](/docs/migrate-to-cloud) 开发人员和企业工作流程之间。

Google GenAI SDK 现已投入使用 [正式发布 (GA)](/docs/libraries#new-libraries) 跨所有支持的平台。如果您正在使用我们的其中之一 [遗留库](/docs/libraries#previous-sdks)，我们强烈建议您迁移。

本指南提供了迁移代码之前和之后的示例，以帮助您入门。

{% callout type="note" %}
Go 示例省略了导入和其他样板代码以提高可读性。
{% /callout %}

## 安装  {% #install-sdk %}

**之前**

{% tabs %}
{% tab label="Python" %}
```shell
pip install -U -q "google-generativeai"
```
{% /tab %}

{% tab label="JavaScript" %}
```shell
npm install @google/generative-ai
```
{% /tab %}

{% tab label="Java" %}
```xml
<dependency>
    <groupId>com.google.ai.client.generativeai</groupId>
    <artifactId>generativeai</artifactId>
    <version>0.9.0</version>
</dependency>
```
{% /tab %}

{% tab label="Go" %}
```shell
go get github.com/google/generative-ai-go
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
```shell
pip install -U -q "google-genai"
```
{% /tab %}

{% tab label="JavaScript" %}
```shell
npm install @google/genai
```
{% /tab %}

{% tab label="Java" %}
```xml
<dependency>
    <groupId>com.google.genai</groupId>
    <artifactId>google-genai</artifactId>
    <version>1.67.0</version>
</dependency>
```
{% /tab %}

{% tab label="Go" %}
```shell
go get google.golang.org/genai
```
{% /tab %}
{% /tabs %}

## API访问  {% #client %}

旧的 SDK 使用各种临时方法在幕后隐式处理 API 客户端。这使得管理客户端和凭据变得困难。现在，您通过中央进行交互 `Client` 对象。这个 `Client` 对象充当各种 API 服务的单个入口点（例如， `models`, `chats`, `files`, `tunings`），促进不同 API 调用的一致性并简化凭证和配置管理。

**之前（不太集中的 API 访问）**

{% tabs %}
{% tab label="Python" %}
对于大多数 API 调用，旧的 SDK 没有显式使用顶级客户端对象。您将直接实例化并与之交互 `GenerativeModel`
对象。

```python
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(...)
```
{% /tab %}

{% tab label="JavaScript" %}
同时 `GoogleGenerativeAI` 是模型和聊天的中心点，文件和缓存管理等其他功能通常需要导入和实例化完全独立的客户端类。

```javascript
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(...);
```
{% /tab %}

{% tab label="Java" %}
```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");
```
{% /tab %}

{% tab label="Go" %}
该 `genai.NewClient` 函数创建了一个客户端，但生成模型操作通常在单独的客户端上调用 `GenerativeModel` 从该客户端获取的实例。其他服务可能是通过不同的包或模式访问的。

```go
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(...)
```
{% /tab %}
{% /tabs %}

**之后（集中式客户端对象）**

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

# Create a single client object
client = genai.Client(http_options={"api_version": "v1beta"})

# 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(...)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

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

// 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(...);
```
{% /tab %}

{% tab label="Java" %}
```java
import com.google.genai.Chat;
import com.google.genai.Client;
import com.google.genai.types.HttpOptions;
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 = Client.builder().httpOptions(HttpOptions.builder().apiVersion("v1beta").build()).build();

// 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());
```
{% /tab %}

{% tab label="Go" %}
```go
import "google.golang.org/genai"

// Create a single client object
client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})

// 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(...)
```
{% /tab %}
{% /tabs %}

## 认证  {% #authenticate %}

旧库和新库都使用 API 密钥进行身份验证。你可以 [创造](https://aistudio.google.com/apikey) 您的 API 密钥位于 Google AI Studio 中。

**之前**

{% tabs %}
{% tab label="Python" %}
旧的 SDK 隐式处理 API 客户端对象。

```python
import google.generativeai as genai

genai.configure(api_key=...)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
```
{% /tab %}

{% tab label="Java" %}
```java
import com.google.genai.Client;

// Passing the API key explicitly to the client builder
Client client = Client.builder().apiKey("GEMINI_API_KEY").build();
```
{% /tab %}

{% tab label="Go" %}
导入谷歌库：

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

创建客户端：

```go
client, err := genai.NewClient(ctx, option.WithAPIKey("GEMINI_API_KEY"))
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
使用Google GenAI SDK，您首先创建一个API客户端，用于调用API。新的 SDK 将从中获取您的 API 密钥 `GEMINI_API_KEY` 环境变量（如果您不将环境变量传递给客户端）。

```shell
export GEMINI_API_KEY="YOUR_API_KEY"
```

```python
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")
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({apiKey: "GEMINI_API_KEY"});
```
{% /tab %}

{% tab label="Java" %}
```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();
```
{% /tab %}

{% tab label="Go" %}
导入 GenAI 库：

```go
import "google.golang.org/genai"
```

创建客户端：

```go
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    Backend: genai.BackendGeminiAPI,
})
```
{% /tab %}
{% /tabs %}

## 生成内容  {% #generate-content %}

### 文本  {% #text %}

**之前**

{% tabs %}
{% tab label="Python" %}
以前没有客户端对象，您可以直接通过以下方式访问 API `GenerativeModel` 对象。

```python
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)
```
{% /tab %}

{% tab label="JavaScript" %}
```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());
```
{% /tab %}

{% tab label="Java" %}
```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());
```
{% /tab %}

{% tab label="Go" %}
```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
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
新的 Google GenAI SDK 通过以下方式提供对所有 API 方法的访问： `Client` 对象。除了一些有状态的特殊情况（`chat` 和 live-api `session`s)，这些都是无状态函数。为了实用性和统一性，返回的对象是 `pydantic` 类。

```python
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))
```
{% /tab %}

{% tab label="JavaScript" %}
```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);
```
{% /tab %}

{% tab label="Java" %}
```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());
```
{% /tab %}

{% tab label="Go" %}
```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
```
{% /tab %}
{% /tabs %}

### 图像  {% #image %}

**之前**

{% tabs %}
{% tab label="Python" %}
```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)
```
{% /tab %}

{% tab label="JavaScript" %}
```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());
```
{% /tab %}

{% tab label="Java" %}
```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());
```
{% /tab %}

{% tab label="Go" %}
```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
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
新型 SDK 中存在许多相同的便利功能。例如， `PIL.Image` 对象会自动转换。

```python
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)
```
{% /tab %}

{% tab label="JavaScript" %}
```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);
```
{% /tab %}

{% tab label="Java" %}
```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());
```
{% /tab %}

{% tab label="Go" %}
```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
```
{% /tab %}
{% /tabs %}

### 流式输出  {% #streaming %}

**之前**

{% tabs %}
{% tab label="Python" %}
```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)
```
{% /tab %}

{% tab label="JavaScript" %}
```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);
}
```
{% /tab %}

{% tab label="Java" %}
```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());
  }
}
```
{% /tab %}

{% tab label="Go" %}
```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
}
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
```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)
```
{% /tab %}

{% tab label="JavaScript" %}
```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;
}
```
{% /tab %}

{% tab label="Java" %}
```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());
  }
}
```
{% /tab %}

{% tab label="Go" %}
```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)
}
```
{% /tab %}
{% /tabs %}

## 配置  {% #configuration %}

**之前**

{% tabs %}
{% tab label="Python" %}
```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')
```
{% /tab %}

{% tab label="JavaScript" %}
```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())
```
{% /tab %}

{% tab label="Java" %}
```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());
```
{% /tab %}

{% tab label="Go" %}
```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
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
对于新 SDK 中的所有方法，所需参数均作为关键字参数提供。所有可选输入均在 `config`
论点。配置参数可以指定为 Python 字典或 `Config` 课程在 `google.genai.types` 命名空间。为了实用性和统一性，所有定义在 `types` 模块是 `pydantic`
类。

```python
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,
),
)
```
{% /tab %}

{% tab label="JavaScript" %}
```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);
```
{% /tab %}

{% tab label="Java" %}
```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());
```
{% /tab %}

{% tab label="Go" %}
```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
```
{% /tab %}
{% /tabs %}

## 安全设置  {% #safety-settings %}

生成带有安全设置的响应：

**之前**

{% tabs %}
{% tab label="Python" %}
```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',
  }
)
```
{% /tab %}

{% tab label="JavaScript" %}
```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);
}
```
{% /tab %}

{% tab label="Java" %}
```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());
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
```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'
          ),
      ]
  ),
)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import {GoogleGenAI, HarmCategory, HarmBlockThreshold} 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: HarmCategory.HARM_CATEGORY_HARASSMENT,
        threshold: HarmBlockThreshold.BLOCK_ONLY_HIGH,
      },
    ],
  },
});

console.log("Finish reason:", response.candidates?.[0]?.finishReason);
console.log("Safety ratings:", response.candidates?.[0]?.safetyRatings);
```
{% /tab %}

{% tab label="Java" %}
```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());
```
{% /tab %}
{% /tabs %}

## 异步  {% #async %}

**之前**

{% tabs %}
{% tab label="Python" %}
```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'
)
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
要将新的 SDK 与 `asyncio`，有一个单独的 `async`
下每个方法的实现 `client.aio`.

```python
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.'
)
```
{% /tab %}
{% /tabs %}

## 聊天  {% #chat %}

开始聊天并向模特发送消息：

**之前**

{% tabs %}
{% tab label="Python" %}
```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?")
```
{% /tab %}

{% tab label="JavaScript" %}
```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());
```
{% /tab %}

{% tab label="Java" %}
```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());
```
{% /tab %}

{% tab label="Go" %}
```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
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
```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?')
```
{% /tab %}

{% tab label="JavaScript" %}
```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);
```
{% /tab %}

{% tab label="Java" %}
```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());
```
{% /tab %}

{% tab label="Go" %}
```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
```
{% /tab %}
{% /tabs %}

## 函数调用  {% #function-calling %}

**之前**

{% tabs %}
{% tab label="Python" %}
```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
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
在新的SDK中，默认为自动函数调用。在这里，您禁用它。

```python
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
```
{% /tab %}
{% /tabs %}

### 自动函数调用  {% #automatic-function %}

**之前**

{% tabs %}
{% tab label="Python" %}
旧版SDK仅支持聊天中自动函数调用。在新的 SDK 中，这是默认行为 `generate_content`.

```python
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?")
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
```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]
  ),
)
```
{% /tab %}
{% /tabs %}

## 代码执行  {% #code-execution %}

代码执行是一个允许模型生成Python代码、运行它并返回结果的工具。

**之前**

{% tabs %}
{% tab label="Python" %}
```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.")
```
{% /tab %}

{% tab label="JavaScript" %}
```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());
```
{% /tab %}

{% tab label="Java" %}
```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());
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
```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)],
    ),
)
```
{% /tab %}

{% tab label="JavaScript" %}
```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);
```
{% /tab %}

{% tab label="Java" %}
```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());
```
{% /tab %}
{% /tabs %}

## 搜索事实依据  {% #search-grounding %}

`GoogleSearch` (Gemini>=2.0) 和 `GoogleSearchRetrieval` (Gemini < 2.0) 是允许模型检索事实依据的公共网络数据的工具，由 Google 提供支持。

**之前**

{% tabs %}
{% tab label="Python" %}
```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'
)
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
```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()
            )
        ]
    )
)
```
{% /tab %}
{% /tabs %}

## JSON 响应  {% #json-response %}

生成 JSON 格式的答案。

**之前**

{% tabs %}
{% tab label="Python" %}
通过指定一个 `response_schema` 和设置 `response_mime_type="application/json"` 用户可以约束模型产生 `JSON` 遵循给定结构的响应。

```python
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
  ),
)
```
{% /tab %}

{% tab label="JavaScript" %}
```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());
```
{% /tab %}

{% tab label="Java" %}
```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());
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
新款SDK采用 `pydantic` 提供模式的类（尽管您可以传递 `genai.types.Schema`，或同等的 `dict`）。在可能的情况下，SDK 会解析返回的 JSON，并将结果返回为 `response.parsed`。如果您提供了 `pydantic` 类作为 SDK 将转换的模式 `JSON`
到该类的一个实例。

```python
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
```
{% /tab %}

{% tab label="JavaScript" %}
```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);
```
{% /tab %}

{% tab label="Java" %}
```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());
```
{% /tab %}
{% /tabs %}

## 文件  {% #files %}

### 上传  {% #upload %}

上传文件：

**之前**

{% tabs %}
{% tab label="Python" %}
```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)
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
```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)
```
{% /tab %}
{% /tabs %}

### 列出并获取  {% #list-and-get %}

列出上传的文件并获取带有文件名的上传文件：

**之前**

{% tabs %}
{% tab label="Python" %}
```python
import google.generativeai as genai

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

file = genai.get_file(name=file.name)
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
client = genai.Client()

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

file = client.files.get(name=file.name)
```
{% /tab %}
{% /tabs %}

### 删除  {% #delete %}

删除文件：

**之前**

{% tabs %}
{% tab label="Python" %}
```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)
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
```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)
```
{% /tab %}
{% /tabs %}

## 上下文缓存  {% #context-caching %}

上下文缓存允许用户将内容传递给模型一次，缓存输入 token，然后在后续调用中引用缓存的 token 以降低成本。

**之前**

{% tabs %}
{% tab label="Python" %}
```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")
```
{% /tab %}

{% tab label="JavaScript" %}
```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());
```
{% /tab %}

{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.HttpOptions;
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 = Client.builder().httpOptions(HttpOptions.builder().apiVersion("v1beta").build()).build();

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());
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
```python
import requests
import pathlib
from google import genai
from google.genai import types

client = genai.Client(http_options={"api_version": "v1beta"})

# 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,
    )
)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY", httpOptions: { apiVersion: "v1beta" } });
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);
```
{% /tab %}

{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.HttpOptions;
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 = Client.builder().httpOptions(HttpOptions.builder().apiVersion("v1beta").build()).build();

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());
```
{% /tab %}
{% /tabs %}

## 计数 token  {% #count-tokens %}

统计一次请求中token的数量。

**之前**

{% tabs %}
{% tab label="Python" %}
```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.')
```
{% /tab %}

{% tab label="JavaScript" %}
```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 }
```
{% /tab %}

{% tab label="Java" %}
```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());
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
```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.',
)
```
{% /tab %}

{% tab label="JavaScript" %}
```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);
```
{% /tab %}

{% tab label="Java" %}
```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());
```
{% /tab %}
{% /tabs %}

## 生成图像  {% #generate-images %}

生成图像：

**之前**

{% tabs %}
{% tab label="Python" %}
```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",
)
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
```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)
```
{% /tab %}
{% /tabs %}

## 嵌入内容  {% #embed-content %}

生成内容嵌入。

**之前**

{% tabs %}
{% tab label="Python" %}
```python
import google.generativeai as genai

response = genai.embed_content(
  model='models/gemini-embedding-001',
  content='Hello world'
)
```
{% /tab %}

{% tab label="JavaScript" %}
```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);
```
{% /tab %}

{% tab label="Java" %}
```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());
```
{% /tab %}
{% /tabs %}

**之后**

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

response = client.models.embed_content(
  model='gemini-embedding-001',
  contents='Hello world',
)
```
{% /tab %}

{% tab label="JavaScript" %}
```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);
```
{% /tab %}

{% tab label="Java" %}
```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());
```
{% /tab %}
{% /tabs %}
