使用媒体文件进行提示

Python Node.js Go

在 ai.google.dev 上查看

在 Google Colab 中运行

在 GitHub 上查看源代码

Gemini API 支持使用文本、图片、音频和视频数据进行提示（也称为多模态提示），这意味着您可以在提示中包含这些类型的媒体文件。对于小型文件，您可以在提供提示时 将 Gemini 模型直接指向本地文件先使用 File API 上传较大的文件，然后再将这些文件添加到提示中。

使用 File API，每个项目最多可以存储 20GB 的文件，每个文件的大小不超过 2GB。文件会存储 48 小时。在此期间，您可以使用 API 密钥访问以生成文件，但无法通过 API 下载文件。凡是已推出 Gemini API 的地区，您都可以免费使用 Files API。

File API 会处理可用于通过 model.generateContent 或 model.streamGenerateContent 生成内容的输入。如需了解有效文件格式（MIME 类型）和支持的模型，请参阅支持的文件格式。

本指南介绍了如何使用 File API 上传媒体文件，并将其添加到对 Gemini API 的 GenerateContent 调用中。如需了解详情，请参阅代码示例。

准备工作：设置您的项目和 API 密钥

在调用 Gemini API（或其 File API）之前，您需要设置项目并配置 API 密钥。

from google.colab import userdata
GOOGLE_API_KEY=userdata.get('GOOGLE_API_KEY')

genai.configure(api_key=GOOGLE_API_KEY)

使用图片提示

在本教程中，您将使用 File API 上传示例图片，然后使用该图片生成内容。

上传图片文件

请参阅“附录”部分，了解如何上传您自己的文件。

1. 准备要上传的示例图片：

     curl -o image.jpg https://storage.googleapis.com/generativeai-downloads/images/jetpack.jpg
   

2. 请使用 media.upload 上传该文件，以便您可以通过其他 API 调用访问该文件：

   sample_file = genai.upload_file(path="image.jpg",
                               display_name="Sample drawing")
   
   print(f"Uploaded file '{sample_file.display_name}' as: {sample_file.uri}")
   

response 显示上传的图片是使用指定的 display_name 存储的，并且具有 uri，用于在 Gemini API 调用中引用该文件。使用 response 跟踪已上传的文件如何映射到 URI。

根据您的用例，您可以将 URI 存储在结构中，例如 dict 或数据库。

获取图片文件的元数据

上传文件后，您可以通过 SDK 调用 files.get 来验证 API 是否已成功存储文件并获取其元数据。

通过此方法，您可以获取与 Google Cloud 项目（与您的 API 密钥相关联）关联的上传文件的元数据。只有 name（以及 uri）才是唯一的。只有在您自行管理唯一性时，才使用 display_name 标识文件。

file = genai.get_file(name=sample_file.name)
print(f"Retrieved file '{file.display_name}' as: {sample_file.uri}")

使用上传的图片文件生成内容

上传图片后，您可以发出在响应中引用 uri 的 GenerateContent 请求（通过上传文件或直接获取文件的元数据）。

在此示例中，您将创建一个以文本开头，后跟上传文件的 URI 引用的提示：

# The Gemini 1.5 models are versatile and work with multimodal prompts
model = genai.GenerativeModel(model_name="models/gemini-1.5-flash")

response = model.generate_content([sample_file, "Describe the image with a creative description."])

Markdown(">" + response.text)

删除图片文件

系统会在 48 小时后自动删除文件。您也可以通过 SDK 使用 files.delete 手动删除它们。

genai.delete_file(sample_file.name)
print(f'Deleted {sample_file.display_name}.')

使用视频提示

在本教程中，您将使用 File API 上传示例视频，然后使用该视频生成内容。

上传视频文件

Gemini API 直接接受视频文件格式。本示例使用的是短片“Big Buck Bunny”。

“Big Buck Bunny”的版权归 2008 年 Blender Foundation / www.bigbuckbunny.org 所有，并根据知识共享署名 3.0 许可获得了许可。

请参阅“附录”部分，了解如何上传您自己的文件。

1. 准备要上传的示例视频文件：

   wget https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4
   

2. 请使用 media.upload 上传该文件，以便您可以通过其他 API 调用访问该文件：

   video_file_name = "BigBuckBunny_320x180.mp4"
   
   print(f"Uploading file...")
   video_file = genai.upload_file(path=video_file_name)
   print(f"Completed upload: {video_file.uri}")
   

验证视频文件的上传状态

通过 SDK 调用 files.get 方法，验证 API 是否已成功上传视频文件。

视频文件具有 File API 中的 State 字段。视频上传后，在可以进行推理之前将处于 PROCESSING 状态。只有 ACTIVE 文件可用于模型推断。

import time

while video_file.state.name == "PROCESSING":
    print('.', end='')
    time.sleep(10)
    video_file = genai.get_file(video_file.name)

if video_file.state.name == "FAILED":
  raise ValueError(video_file.state.name)

获取视频文件的元数据

您可以随时通过 SDK 调用 files.get 方法，获取上传的视频文件的元数据。

通过此方法，您可以获取与 Google Cloud 项目（与您的 API 密钥相关联）关联的上传文件的元数据。只有 name（以及 uri）才是唯一的。只有在您自行管理唯一性时，才使用 display_name 标识文件。

file = genai.get_file(name=video_file.name)
print(f"Retrieved file '{file.display_name}' as: {video_file.uri}")

使用上传的视频文件生成内容

上传视频后，您可以发出在响应中引用 uri 的 GenerateContent 请求（通过上传文件或直接获取文件的元数据）。

在对视频进行推理之前，请确保您已验证视频文件的上传状态（上文部分）。

# Create the prompt.
prompt = "Describe this video."

# The Gemini 1.5 models are versatile and work with multimodal prompts
model = genai.GenerativeModel(model_name="models/gemini-1.5-flash")

# Make the LLM request.
print("Making LLM inference request...")
response = model.generate_content([video_file, prompt],
                                  request_options={"timeout": 600})
print(response.text)

删除视频文件

系统会在 48 小时后自动删除文件。您也可以通过 SDK 使用 files.delete 手动删除它们。

genai.delete_file(file_response.name)
print(f'Deleted file {file_response.uri}')

支持的文件格式

Gemini 模型支持以多种文件格式输入提示。本部分介绍了使用常规媒体格式进行提示的注意事项，特别是图片、音频、视频和纯文本文件。您只能将媒体文件用于提示特定模型版本，如下表所示。

图片格式

您可以使用图片数据在 Gemini 1.5 模型中给出提示。使用图片进行提示时，它们遵循以下限制和要求：

• 图片必须采用以下图片数据 MIME 类型之一：
  • PNG - image/png
  • JPEG - image/jpeg
  • WEBP - image/webp
  • HEIC - image/heic
  • HEIF - image/heif
• 对于 Gemini 1.5 模型，最多可上传 3600 张图片。
• 对图片中的像素数没有具体限制；不过，系统会将较大的图片缩小以适应 3072 x 3072 的最大分辨率，同时保留其原始宽高比。

音频格式

在 Gemini 1.5 模型中，你可以使用音频数据来给出提示。使用音频进行提示时，需要遵循以下限制和要求：

• 以下常见音频格式 MIME 类型支持音频数据：
  • WAV - audio/wav
  • MP3 - 音频/mp3
  • AIFF - audio/aiff
  • AAC - audio/aac
  • OGG Vorbis - 音频/ogg
  • FLAC - audio/flac
• 单个提示中支持的音频数据长度上限为 9.5 小时。
• 音频文件会被重新采样降至 16 Kbps 的数据分辨率，并且多个音频频道会合并为一个通道。
• 单个提示中音频文件的数量没有特定限制；但是，单个提示中所有音频文件的总长度不能超过 9.5 小时。

视频格式

你可以使用视频数据在 Gemini 1.5 模型中给出提示。

• 以下常见的视频格式 MIME 类型支持视频数据：

  • video/mp4
  • video/mpeg
  • 视频/移动
  • 视频/avi
  • video/x-flv
  • 视频/mpg
  • 视频/webm
  • 视频/wmv
  • 视频/3gpp

• File API 服务会以每秒 1 帧 (FPS) 的速度对图片进行视频采样，并且可能会发生变化，以提供最佳的推理质量。无论分辨率和质量如何，单个图片都会占用 258 个词元。

纯文本格式

File API 支持上传具有以下 MIME 类型的纯文本文件：

• text/plain
• text/html
• text/css
• text/javascript
• application/x-javascript
• 文本/x-typescript
• 应用/x-typescript
• 文本/csv
• 文本/markdown
• 文本/x-python
• application/x-python-code
• application/json
• text/xml
• 应用/rtf
• 文本/rtf

对于 MIME 类型不在列表中的纯文本文件，您可以尝试手动指定上述 MIME 类型之一。

附录：将文件上传到 Colab

此笔记本使用 File API 处理从互联网下载的文件。如果您要在 Colab 中运行此命令，并且希望使用自己的文件，则需要先将这些文件上传到 Colab 实例。

首先，点击左侧边栏中的文件，然后点击上传按钮：

接下来，您需要将该文件上传到 File API。在以下代码单元的表单中，输入所上传文件的文件名，并为该文件提供适当的显示名，然后运行该单元。

my_filename = "gemini_logo.png" # @param {type:"string"}
my_file_display_name = "Gemini Logo" # @param {type:"string"}

my_file = genai.upload_file(path=my_filename,
                            display_name=my_file_display_name)
print(f"Uploaded file '{my_file.display_name}' as: {my_file.uri}")