Files API
Gemini可以同时处理多种类型的输入数据,包括文本、图像和音频。
本指南向您展示如何使用 Files API 处理媒体文件。音频文件、图像、视频、文档和其他支持的文件类型的基本操作相同。
有关文件提示指南,请查看 文件提示引导 部分。
上传文件 #
您可以使用Files API上传媒体文件。当总请求大小(包括文件、文本提示、系统指令等)大于 100 MB 时,请始终使用 Files API。对于 PDF 文件,限制为 50 MB。
以下代码上传一个文件,然后在调用中使用该文件 generateContent.
from google import genai
client = genai.Client()
myfile = client.files.upload(file="path/to/sample.mp3")
response = client.models.generate_content(
model="gemini-4-hydrogen", contents=["Describe this audio clip", myfile]
)
print(response.text)
import {
GoogleGenAI,
createUserContent,
createPartFromUri,
} from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const myfile = await ai.files.upload({
file: "path/to/sample.mp3",
config: { mimeType: "audio/mpeg" },
});
const response = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: createUserContent([
createPartFromUri(myfile.uri, myfile.mimeType),
"Describe this audio clip",
]),
});
console.log(response.text);
}
await main();
file, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
if err != nil {
log.Fatal(err)
}
defer client.Files.Delete(ctx, file.Name)
resp, err := client.Models.GenerateContent(ctx, "gemini-4-hydrogen", []*genai.Content{
{
Parts: []*genai.Part{
genai.NewPartFromFile(*file),
genai.NewPartFromText("Describe this audio clip"),
},
},
}, nil)
if err != nil {
log.Fatal(err)
}
printResponse(resp)
AUDIO_PATH="path/to/sample.mp3"
MIME_TYPE=$(file -b --mime-type "${AUDIO_PATH}")
NUM_BYTES=$(wc -c < "${AUDIO_PATH}")
DISPLAY_NAME=AUDIO
tmp_header_file=upload-header.tmp
# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-D "${tmp_header_file}" \
-H "X-Goog-Upload-Protocol: resumable" \
-H "X-Goog-Upload-Command: start" \
-H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
-H "Content-Type: application/json" \
-d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null
upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"
# Upload the actual bytes.
curl "${upload_url}" \
-H "Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Offset: 0" \
-H "X-Goog-Upload-Command: upload, finalize" \
--data-binary "@${AUDIO_PATH}" 2> /dev/null > file_info.json
file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri
# Now generate content using that file
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":[
{"text": "Describe this audio clip"},
{"file_data":{"mime_type": "${MIME_TYPE}", "file_uri": '$file_uri'}}]
}]
}' 2> /dev/null > response.json
cat response.json
echo
jq ".candidates[].content.parts[].text" response.json
获取文件的元数据 #
您可以通过调用验证API是否成功存储了上传的文件并获取其元数据 files.get.
from google import genai
client = genai.Client()
myfile = client.files.upload(file='path/to/sample.mp3')
file_name = myfile.name
myfile = client.files.get(name=file_name)
print(myfile)
import {
GoogleGenAI,
} from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const myfile = await ai.files.upload({
file: "path/to/sample.mp3",
config: { mimeType: "audio/mpeg" },
});
const fileName = myfile.name;
const fetchedFile = await ai.files.get({ name: fileName });
console.log(fetchedFile);
}
await main();
file, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
if err != nil {
log.Fatal(err)
}
gotFile, err := client.Files.Get(ctx, file.Name)
if err != nil {
log.Fatal(err)
}
fmt.Println("Got file:", gotFile.Name)
# file_info.json was created in the upload example
name=$(jq ".file.name" file_info.json)
# Get the file of interest to check state
curl https://generativelanguage.googleapis.com/v1beta/files/$name \
-H "x-goog-api-key: $GEMINI_API_KEY" > file_info.json
# Print some information about the file you got
name=$(jq ".file.name" file_info.json)
echo name=$name
file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri
列出已上传的文件 #
以下代码获取所有上传文件的列表:
from google import genai
client = genai.Client()
print('My files:')
for f in client.files.list():
print(' ', f.name)
import {
GoogleGenAI,
} from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const listResponse = await ai.files.list({ config: { pageSize: 10 } });
for await (const file of listResponse) {
console.log(file.name);
}
}
await main();
import {
GoogleGenAI,
createUserContent,
createPartFromUri,
} from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const myfile = await ai.files.upload({
file: "path/to/sample.mp3",
config: { mimeType: "audio/mpeg" },
});
const response = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: createUserContent([
createPartFromUri(myfile.uri, myfile.mimeType),
"Describe this audio clip",
]),
});
console.log(response.text);
}
await main();
import {
GoogleGenAI,
createUserContent,
createPartFromUri,
} from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const myfile = await ai.files.upload({
file: "path/to/sample.mp3",
config: { mimeType: "audio/mpeg" },
});
const response = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: createUserContent([
createPartFromUri(myfile.uri, myfile.mimeType),
"Describe this audio clip",
]),
});
console.log(response.text);
}
await main();
删除上传的文件 #
文件将在 48 小时后自动删除。您还可以手动删除上传的文件:
import {
GoogleGenAI,
createUserContent,
createPartFromUri,
} from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const myfile = await ai.files.upload({
file: "path/to/sample.mp3",
config: { mimeType: "audio/mpeg" },
});
const response = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: createUserContent([
createPartFromUri(myfile.uri, myfile.mimeType),
"Describe this audio clip",
]),
});
console.log(response.text);
}
await main();
import {
GoogleGenAI,
createUserContent,
createPartFromUri,
} from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const myfile = await ai.files.upload({
file: "path/to/sample.mp3",
config: { mimeType: "audio/mpeg" },
});
const response = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: createUserContent([
createPartFromUri(myfile.uri, myfile.mimeType),
"Describe this audio clip",
]),
});
console.log(response.text);
}
await main();
import {
GoogleGenAI,
createUserContent,
createPartFromUri,
} from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const myfile = await ai.files.upload({
file: "path/to/sample.mp3",
config: { mimeType: "audio/mpeg" },
});
const response = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: createUserContent([
createPartFromUri(myfile.uri, myfile.mimeType),
"Describe this audio clip",
]),
});
console.log(response.text);
}
await main();
import {
GoogleGenAI,
createUserContent,
createPartFromUri,
} from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const myfile = await ai.files.upload({
file: "path/to/sample.mp3",
config: { mimeType: "audio/mpeg" },
});
const response = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: createUserContent([
createPartFromUri(myfile.uri, myfile.mimeType),
"Describe this audio clip",
]),
});
console.log(response.text);
}
await main();
使用信息 #
您可以使用 Files API 上传媒体文件并与之交互。 Files API 允许您为每个项目存储最多 20 GB 的文件,每个文件的最大大小为 2 GB。文件存储时间为 48 小时。
在此期间,您可以使用 API 获取有关文件的元数据。但是,您无法下载用户上传的文件。您可以使用以下命令下载模型生成的文件,例如视频 files.download 方法。 Files API 在提供 Gemini API 的所有地区免费提供。
文件提示策略 #
本节提供有关使用带有 Gemini API 提示的媒体文件的指南和最佳实践。
能够在提示中使用各种类型的数据,使您可以更灵活地使用 Gemini API 处理哪些任务。例如,您可以向模型发送一张美味佳肴的照片,并要求其写一篇关于这顿饭的简短博客。
提示 | 回应 |
|---|---|
根据这张图片写一篇简短、引人入胜的博客文章。它应该包括照片中餐食的描述,并谈论我的旅途餐食准备过程。
| 准备饭菜是节省时间和金钱的好方法,而且还可以帮助您吃得更健康。这顿饭是健康美味的膳食的一个很好的例子,可以轻松提前准备。 这顿饭的特色是糙米、烤蔬菜和照烧鸡肉。糙米是一种健康且复杂的碳水化合物,可为您提供持续的能量。烤蔬菜是获取每日维生素和矿物质的好方法,而照烧鸡肉是美味且富含蛋白质的选择。 这顿饭也很容易准备。只需煮糙米,烤蔬菜,然后煮照烧鸡肉。一切煮熟后,将其放入备餐容器中并存放在冰箱中。然后您就可以拿起一个容器,开始忙碌的早晨! 如果您正在寻找一顿可以轻松提前准备的健康美味的饭菜,那么这顿饭是一个不错的选择。它富含营养和风味,一定会让您感到饱足和满足。 这是准备健康美味的饭菜! |
如果您无法从使用媒体文件的提示中获得所需的输出,有一些策略可以帮助您获得所需的结果。以下部分提供了改进使用多模态输入的提示的设计方法和故障排除技巧。
您可以通过遵循以下最佳实践来改进多模态提示:
快速设计基础 * 请在您的说明中具体说明:制定清晰简洁的说明,尽量减少误解的空间。
- 在提示中添加一些示例:使用现实的小例子来说明您想要实现的目标。
- 一步步分解:将复杂的任务划分为可管理的子目标,指导模型完成整个过程。
- 指定输出格式:在提示中,要求输出采用您想要的格式,例如 markdown、JSON、HTML 等。
- 对于单图像提示,请将您的图像放在第一位:虽然 Gemini 可以按任何顺序处理图像和文本输入,但对于包含单个图像的提示,如果将该图像放置在文本提示之前,效果可能会更好。
对多模态提示进行故障排除 * 如果模型没有从图像的相关部分绘制信息:删除提示,提示您希望提示从图像的哪些方面提取信息。
- 如果模型输出太通用(没有针对图像进行足够的定制):在提示开始时,尝试要求模型在提供任务说明之前描述图像,或者尝试要求模型参考图像中的内容。
请在您的说明中具体说明 #
当提示清晰且详细时,它会取得最大的成功。如果您有特定的输出,最好在提示中包含该要求,以确保获得所需的输出。
对于这张机场董事会的图像,要求模型仅“描述该图像”就可以生成一般描述。如果您需要模型从图像中解析时间和城市,您可以直接在提示中包含该请求。
提示 | 模型响应 |
|---|---|
| 该图显示了机场到达和出发板。 |
更新提示 | 改善反应 |
|---|---|
| 10:50 莫斯科 |
添加几个例子 #
Gemini 模型可以接受多个输入,它可以用作示例来了解您想要的输出。添加这些示例可以帮助模型识别模式并将给定图像和响应之间的关系应用到新示例。这也称为“小样本”学习。
在下面的示例中,初始输出以句子形式编写,并且还包含国家/地区(巴西)。假设您希望以不同的格式或样式输出,并且您只需要城市,而不需要国家/地区。在提示中添加少量示例可以引导模型按照您想要的方式做出响应。
提示 | 模型响应 |
|---|---|
| 标志性建筑是巴西里约热内卢的基督救世主雕像。 |
更新提示 | 改善反应 |
|---|---|
确定城市以及地标。 | 城市:罗马,地标:罗马斗兽场。 |
| 城市: 北京, 地标: 紫禁城 |
| 城市:里约热内卢,地标:基督救世主雕像 |
一步步分解 #
对于复杂的任务,例如需要视觉理解和推理的任务,将任务分成更小、更简单的步骤可能会有所帮助。或者,如果您在提示中直接要求模型“逐步思考”,也可能会有效。
提示 | 模型响应 |
|---|---|
| 很快,您就只剩下 3 卷了。 |
更新提示 | 改善反应 |
|---|---|
|
|
数学问题或其他类型的文字问题非常适合要求模型逐步思考。
提示 | 回应 |
|---|---|
| -135 |
模型的响应不正确。改进这一点的一些方法是要求模型在回答提示之前解析问题。
提示 | 回应 |
|---|---|
| 点击展开结果 $ b(n) = b(n-1) * (-3) $ $ b(1) = 15 $ 将 n = 4 代入公式: $ b(4) = b(4-1) * (-3) $ $ b(4) = b(3) * (-3) $ 我们不知道 b(3) 的值,因此替换 n =将 3 代入公式: $ b(3) = b(3-1) * (-3) $ $ b(3) = b(2) * (-3) $ 我们不知道 b(2) 的值,因此将 n = 2 代入公式中: $ b(2) = b(2-1) * (-3) $ $ b(2) = b(1) * (-3) $ 我们知道 b(1) 的值为 15,,因此将其代入公式: $ b(2) = 15 * (-3) $ $ b(2) = -45 $ 现在我们知道了 b(2) 的值,将其代入 b(3) 的公式中: $ b(3) = b(2) * (-3) $ $ b(3) = -45 * (-3) $ $ b(3) = 135 $ 现在我们知道了 b(3) 的值,将其代入 b(4) 的公式中: $ b(4) = b(3) * (-3) $ $ b(4) = 135 * (-3) $ $ b(4) = -405 $ 因此,序列中的第四项是 -405. |
该模型响应是正确的 - 现在为了使响应更加简化,您可以要求模型逐步思考。
更新提示 | 改善反应 |
|---|---|
| 第一项是 15. 第二项是 b(1) * (-3) = 15 * (-3) = -45. 第三项是 b(2) * (-3) = -45 * (-3) = 135. 第四项是 b(3) * (-3) = 135 * (-3) = -405. |
指定输出格式 #
一个常见的问题是模型输出需要采用某种格式(例如 markdown、JSON、HTML),特别是当模型输出需要由下游任务摄取时。您可以通过在提示中指示模型执行此操作来尝试生成该格式的输出。下面是两个例子:
提示 | 模型响应 | |||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
提示 | 模型响应 |
|---|---|
| ` |
对于单图像提示,请将您的图像放在第一位 #
虽然 Gemini 可以在提示中以任意顺序解释图像和文本,但在文本提示之前放置单个图像可能会产生更好的结果。在以下示例中,您会注意到每个提示中图像首先出现在文本之前。
对多模态提示进行故障排除 #
如果您没有得到有用的回复,您可能需要对提示进行故障排除。以下是您可以尝试的一些策略。
如果模型没有从图像的相关部分绘制信息 #
要获得更具体的响应,您可以指出您希望提示从图像的哪些方面提取信息以告知其响应。
提示 | 模型响应 |
|---|---|
| 尿布在用完之前可以使用 198 天。 |
更新提示 | 改善反应 |
|---|---|
使用盒子上显示的重量来确定孩子的年龄,并使用盒子中尿布的总数。 将总数除以孩子每天换尿布的数量。 | 盒子里装有 198 尿布。盒子上注明尿布适用于体重为 22-37 磅的儿童。 此体重范围内的儿童平均年龄可能在 1 至 2 岁之间。 2 岁的儿童通常每天都会使用 6 尿布,因此,尿布将持续大约 33 天(198/6)。 |
如果模型输出过于通用并且没有针对图像输入进行足够的定制 #
为了帮助模型调整其对图像的响应,请尝试要求其在执行推理任务之前描述图像。
提示 | 模型响应 |
|---|---|
| 所有四幅图像都是风景摄影的例子。 |
更新提示 | 改善反应 |
|---|---|
| 第一张图片显示一个人收拾行李箱。第二张图片显示了购物中心空荡荡的走廊。第三张图片显示了一卷卫生纸。第四张图片显示了一片黑暗且波涛汹涌的大海。 这些图像的共同点是它们都是阈限空间的例子。阈限空间是位于两个其他地方或情况之间的地方或情况。它们通常具有不确定性或模糊性的特点。 第一张图片显示了一个人在家里和旅行之间的状态。第二张图显示了两家商店之间的走廊。第三张图片是卫生纸,它可以代表浴室。浴室是私人领域和公共领域之间的过渡空间。这是我们为进入或离开外部世界做好准备的地方。 第四张图片显示了介于平静和暴风雨之间的大海。 阈限空间既令人兴奋又令人不安。它们可以是新的开始的地方,也可以是结束的地方。它们可以是反思的场所,也可以是行动的场所。 |
您还可以尝试明确要求模型参考图像中的内容。
更新提示 | 改善反应 |
|---|---|
| 所有图像都与旅行有关。第一张图片显示一个人正在收拾行李箱,第二张图片显示购物中心空荡荡的走廊,第三张图片显示一叠卫生纸,第四张图片显示黑暗和波涛汹涌的大海。 这些图像都与旅行有关,因为它们都是人们在旅行时需要或使用的东西。第一张图片显示一个人收拾行李,这是人们在旅行时所做的事情。第二张图片显示了购物中心空荡荡的走廊,这是人们经常去购买旅行物品的地方。第三张图显示了一叠卫生纸,这是人们在旅行时经常使用的东西。第四张图展示了一片漆黑、波涛汹涌的大海,这是人们在旅行时经常遇到的情况。 |
同样的技巧也适用于图像的创意输出。在下面的兔子示例中,明确要求模型包含图像中的各个方面可以改善输出。
提示 | 模型响应 |
|---|---|
| 小兔子,那么柔软,棕色,在田野里跳来跳去。你的耳朵那么长,你的尾巴那么小,你是所有生物中最可爱的。 |
更新提示 | 改善反应 |
|---|---|
| 绿色的小兔子,耳朵那么长,那么敏锐。在你凝视的远方,你看到了什么? |
排除提示的哪一部分失败的问题 #
很难知道提示是否失败,因为模型没有 理解图像 首先,或者如果它确实理解图像但没有执行正确的操作 推理步骤 之后。为了消除这些原因之间的歧义,请要求模型描述图像中的内容。
在以下示例中,如果模型响应与茶搭配时看起来令人惊讶的零食(例如爆米花),您可以首先进行故障排除以确定模型是否正确识别出图像中包含茶。
提示 | 提示故障排除 |
|---|---|
|
|
另一种策略是要求模型解释其推理。这可以帮助你缩小推理失败的部分(如果有)。
提示 | 提示故障排除 |
|---|---|
|
|
后续步骤 #
尝试使用以下命令编写您自己的多模态提示 Google AI Studio.
有关使用 Gemini Files API 上传媒体文件并将其包含在提示中的信息,请参阅 愿景, 音频, 和 文件处理 指南。
有关提示设计的更多指导,例如调整采样参数,请参阅 即时策略 页。


确定城市以及地标。

我什么时候会用完卫生纸?
序列中的第四项是什么?
将此图像中的表格解析为 markdown 格式
提供以下所有属性的列表:成分、菜肴类型、素食与否,采用 JSON 格式
这些尿布可以给宝宝用几天?
这些图像之间有什么共同点?
你能为我写一首关于这个图像的诗吗?
我可以在 1 分钟内制作什么零食来搭配这个?