Gemini 中文指南
获取 API 密钥 ↗

文本生成

↓ 下载 Markdown

Gemini API 可以从文本、图像、视频和音频输入生成文本输出。

这是一个基本示例:

python
  from google import genai

  client = genai.Client()

  response = client.models.generate_content(
      model="gemini-4-hydrogen",
      contents="How does AI work?"
  )
  print(response.text)

用Gemini思考 #

Gemini型号常有 “思考” 默认情况下启用,允许模型在响应请求之前进行推理。

每个模型都支持不同的思维配置,使您可以控制成本、延迟和智能。有关更多详细信息,请参阅 思维指南.

python
from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents="How does AI work?",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="high")
    ),
)
print(response.text)

系统指令及其他配置 #

您可以使用系统指令来指导 Gemini 模型的行为。为此,请通过 GenerateContentConfig 对象。

python
from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-4-hydrogen",
    config=types.GenerateContentConfig(
        system_instruction="You are a cat. Your name is Neko."),
    contents="Hello there"
)

print(response.text)

该 GenerateContentConfig 对象还允许您覆盖默认生成参数,例如 max_output_tokens 或 thinking_config.

python
from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents=["Explain how AI works"],
    config=types.GenerateContentConfig(
        max_output_tokens=1000
    )
)
print(response.text)

请参阅 GenerateContentConfig 在我们的 API 参考中,获取可配置参数及其描述的完整列表。

多模态输入 #

Gemini API 支持多模态输入,允许您将文本与媒体文件结合起来。以下示例演示了提供图像:

python
from PIL import Image
from google import genai

client = genai.Client()

image = Image.open("/path/to/organ.png")
response = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents=[image, "Tell me about this instrument"]
)
print(response.text)

有关提供图像和更高级图像处理的替代方法,请参阅我们的 图像理解指南。 API还支持 文件, 视频, 和 音频 输入和理解。

流式响应 #

默认情况下,模型仅在整个生成过程完成后才返回响应。

要获得更流畅的交互,请使用流式传输来接收 GenerateContentResponse 实例在生成时逐渐增加。

python
from google import genai

client = genai.Client()

response = client.models.generate_content_stream(
    model="gemini-4-hydrogen",
    contents=["Explain how AI works"],
)
for chunk in response:
    print(chunk.text, end="")

多轮对话(聊天) #

我们的 SDK 提供了将多轮提示和响应收集到聊天中的功能,让您可以轻松地跟踪对话历史记录。

python
from google import genai

client = genai.Client()
chat = client.chats.create(model="gemini-4-hydrogen")

response = chat.send_message("I have 2 dogs in my house.")
print(response.text)

response = chat.send_message("How many paws are in my house?")
print(response.text)

for message in chat.get_history():
    print(f'role - {message.role}', end=": ")
    print(message.parts[0].text)

流式传输还可用于多轮对话。

python
from google import genai

client = genai.Client()
chat = client.chats.create(model="gemini-4-hydrogen")

response = chat.send_message_stream("I have 2 dogs in my house.")
for chunk in response:
    print(chunk.text, end="")

response = chat.send_message_stream("How many paws are in my house?")
for chunk in response:
    print(chunk.text, end="")

for message in chat.get_history():
    print(f'role - {message.role}', end=": ")
    print(message.parts[0].text)

提示提示 #

请咨询我们的 及时的工程指南 有关充分利用 Gemini 的建议。

后续步骤 #

内容生成 #

这是向模型发送提示的中央端点。生成内容有两个端点,主要区别在于接收响应的方式:

  • generateContent (休息):接收请求并在模型完成整个生成后提供单个响应。
  • streamGenerateContent (上海证券交易所):接收完全相同的请求,但模型在生成响应时流回响应块。这为交互式应用程序提供了更好的用户体验,因为它允许您立即显示部分结果。

请求体结构 #

该 请求正文 是一个 JSON 对象 相同的 适用于标准和流模式,由一些核心对象构建:

  • Content 对象:代表对话中的一个回合。
  • Part 对象:对象中的一段数据 Content 转动(如文本或图像)。
  • inline_data (Blob):原始媒体字节及其 MIME 类型的容器。

在最高级别,请求正文包含 contents 对象,它是一个列表 Content 对象,每个对象代表对话的轮次。在大多数情况下,对于基本文本生成,您将有一个 Content 对象,但如果您想维护对话历史记录,您可以使用多个 Content 对象。

下图展示了一个典型的 generateContent 请求正文:

shell
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
          "role": "user",
          "parts": [
              // A list of Part objects goes here
          ]
      },
      {
          "role": "model",
          "parts": [
              // A list of Part objects goes here
          ]
      }
    ]
  }'

响应体结构 #

该 响应体 流式传输模式和标准模式类似,但以下情况除外:

在较高级别上,响应正文包含 candidates 对象,它是一个列表 Candidate 对象。的 Candidate 对象包含一个 Content 具有从模型返回的生成响应的对象。

REST API 示例 #

多模态提示(文字和图像) #

要在提示中同时提供文本和图像, parts 数组应该包含两个 Part 对象:一种用于文本,一种用于图像 inline_data.

shell
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
    "contents": [{
    "parts":[
        {
            "inline_data": {
            "mime_type":"image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ... (base64-encoded image)"
            }
        },
        {"text": "What is in this picture?"},
      ]
    }]
  }'

多轮对话(聊天) #

要构建多轮对话,您可以定义 contents 具有多个的数组 Content 对象。 API 将使用整个历史记录作为下一个响应的上下文。的 role 对于每个 Content 对象应该在之间交替 user 和 model.

shell
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Hello." }
        ]
      },
      {
        "role": "model",
        "parts": [
          { "text": "Hello! How can I help you today?" }
        ]
      },
      {
        "role": "user",
        "parts": [
          { "text": "Please write a four-line poem about the ocean." }
        ]
      }
    ]
  }'

要点 #

  • Content 是信封:它是消息轮转的顶级容器,无论消息来自用户还是模型。

  • Part 启用多模态:使用多个 Part 单个对象内 Content 对象组合不同类型的数据(文本、图像、视频 URI 等)。

  • 选择您的数据方法: * 对于小型、直接嵌入的媒体(如大多数图像),请使用 Part 使用 inline_data.

  • 对于较大的文件或您想要跨请求重用的文件,请使用文件 API 上传文件并使用 file_data 部分。

  • 管理对话历史记录:对于使用 REST API 的聊天应用程序,构建 contents 通过附加数组 Content 每回合的对象,交替 "user" 和 "model" 角色。如果您使用的是 SDK,请参阅 SDK 文档,了解管理对话历史记录的推荐方法。

响应示例 #

以下示例展示了这些组件如何针对不同类型的请求组合在一起。

纯文本回复 #

默认文本响应包含 candidates 具有一个或多个的数组 content 包含模型响应的对象。

以下是一个示例 标准 回应:

json
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "At its core, Artificial Intelligence works by learning from vast amounts of data ..."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 1
    }
  ],
}

以下为系列 流媒体 回应。每个响应包含一个 responseId 将完整的响应联系在一起:

json
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "The image displays"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  },
  "modelVersion": "gemini-4-hydrogen",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

...

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " the following materials:\n\n*   **Wood:** The accordion and the violin are primarily"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  }
  "modelVersion": "gemini-4-hydrogen",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

Live API(BidiGenerateContent)WebSocket API #

Live API 提供基于 WebSocket 的有状态 API,用于双向流,以实现实时流用例。您可以查看 Live API指南 和 Live API参考 了解更多详情。

专业型号 #

除了 Gemini 系列型号之外,Gemini API 还提供专用型号的端点,例如 Nano Banana, Lyria 和 嵌入 模型。您可以在模型部分查看这些指南。

平台API #

其余端点支持与迄今为止描述的主要端点一起使用的附加功能。查看主题 批处理模式 和 文件 API 在指南部分了解更多信息。

后续步骤 #

如果您刚刚开始,请查看以下指南,这将帮助您了解 Gemini API 编程模型:

您可能还想查看功能指南,其中介绍了不同的 Gemini API 功能并提供了代码示例:

搜索标题、API 名称或正文内容