结论先说
- 请求总大小超过 100 MB(PDF 文件超过 50 MB)或同一份媒体文件要反复提问时,必须改用 Files API:先上传拿到
uri,再在对话里传引用,避免每次重复传几百兆字节。 - 单文件上限为 2 GB,每个项目总暂存空间上限为 20 GB,文件保留时间为固定的 48 小时:到期由服务端自动清理,不支持手动延期,但可随时调
delete提前删除。 - Files API 上传和暂存本身完全免费,只有在你把文件
uri放进模型请求实际推理时,才会按对应多模态规则折算输入 token 计费。 - 长视频上传后不要立刻发提问:视频需服务端异步预处理,务必先通过
files.get确认文件状态从PROCESSING变为ACTIVE后再调用模型。 - 谷歌账号准备与多工具订阅入口:使用 Gemini、Google AI Studio 与 Antigravity 需具备符合地区与年龄要求的个人谷歌账号,缺号可查看本站 谷歌账号购买说明(含带 2FA 的 谷歌邮箱成品号),跨平台付费订阅总览见 AI 会员充值中心。

图:本站根据 Google Gemini API 文档:Files API 整理的示意图
本文根据 Google Gemini API 官方文档《Files API》《Gemini Developer API Pricing》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Google 官方网站。
适用于谁
- 想把几百 MB 的会议录像、长播客音频或上百页的 PDF 财报喂给 Gemini 模型做总结、提取时间戳的开发者;
- 直接在请求里内联塞 Base64 字节流导致体积超限报
400错误,需要改用client.files.upload的人; - 关心上传后的文件存多久、收不收存储费、单文件最大支持多少 GB 的工程师。
一、什么时候用内联传参,什么时候必须用 Files API
Gemini API 支持直接把小图片、短音频放进请求体,也支持通过 Files API 预上传。按官方现行规范对照如下:
| 指标项 | 请求体内联传入(Inline) | Files API 预上传(files.upload) |
|---|---|---|
| 触发体积边界 | 适合小图短片段;总请求超 100 MB(PDF 超 50 MB)不可用 | 单个文件最高支持 2 GB,项目总空间 20 GB |
| 多轮对话复用 | 每轮都要重传原始字节,浪费带宽且易超时 | 上传一次拿到 myfile.uri,48 小时内无限次引用 |
| 保留与删除 | 仅当次请求有效,不留存文件对象 | 默认保留 48 小时后自动销毁,支持主动删除 |
| 存储费用 | 无 | 托管存储免费,仅在送入模型推理时算输入 token |
另外官方文档说明,files.upload 返回的文件 URI 在 v1 与 v1beta 接口之间可以互通使用。如果你也在对比 Anthropic 同类接口的配额差异,可参考 Claude API Files API 怎么用。
二、Python 与 Node.js 上传、轮询状态与删除代码
1. 上传音频或 PDF 并直接提问(Python)
安装官方 google-genai SDK(环境准备见 Gemini API Python 调用教程)后,上传并传入新一代 Interactions API 的写法如下:
python
import time
from google import genai
client = genai.Client()
# 1. 上传本地视频、音频或大 PDF
myfile = client.files.upload(file="lecture.mp4")
# 2. 视频大文件需等待预处理完成变为 ACTIVE
while myfile.state.name == "PROCESSING":
time.sleep(3)
myfile = client.files.get(name=myfile.name)
if myfile.state.name != "ACTIVE":
raise RuntimeError(f"文件处理失败,当前状态: {myfile.state.name}")
# 3. 传入 URI 让模型分析内容
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input=[
{"type": "text", "text": "按章节列出这段视频的关键时间点与核心结论"},
{"type": "video", "uri": myfile.uri, "mime_type": myfile.mime_type},
],
)
print(interaction.output_text)
若使用 Node.js / TypeScript 开发,同样调用 await client.files.upload({ file: "sample.mp3", config: { mimeType: "audio/mpeg" } }),基础配置可看 Gemini API Node.js 调用教程。需要申请 AI Studio 密钥但缺少账号时,可在本站查看 谷歌账号说明。
2. 列出已上传文件与主动清理
如果项目累计上传快要接近 20 GB 配额上限,或者涉及敏感内部资料不想留在云端等满 48 小时,可以用 list 与 delete 立即销毁:
python
# 查看当前项目暂存的文件列表
for f in client.files.list():
print(f.name, f.uri)
# 分析完毕后主动删除指定文件
client.files.delete(name=myfile.name)

图:本站根据 Google Gemini API 文档:Files API 整理的示意图
谷歌开发账号与主力编程订阅提示:若当前账号卡在地区不支持、手机核验或工作空间限制,可在本站选购已配置两步验证的 谷歌账号成品号(即时发货,质保首登,到手请按指引先登后改密);日常搭配主力模型开发,也可同步了解免境外卡自助兑换的 ChatGPT Plus 与 Claude Pro。
三、长视频与大文档省费及报错排查
- 刚传完视频马上提问报
FAILED_PRECONDITION或400:基本都是没等state变成ACTIVE就调了生成接口。加上上面的files.get循环等待即可解决;更多状态码含义见 Gemini API 报错 400、403、429、500 怎么办。 - 过了两天复用旧
uri报403或404:文件已满 48 小时被自动清理。业务数据库里不要把 Gemini 的file.uri当永久对象存储地址保存,应当保留你自己的源文件路径,捕获过期错误后自动重传一次刷新uri。 - 同一长视频连续追问十几次账单偏高:Files API 只免掉「网盘托管费」,每次把 1 小时视频的
uri放进请求都会重新计算几十万视频输入 token。多轮密集追问同一文件时,建议把上传后的文件配合上下文缓存一起用,计费细则见 Gemini API 价格。
常见问题
问:Files API 里上传的文件能下载回本地吗?
答:不能。官方设计 Files API 仅用于向 Gemini 模型喂入多模态上下文,只支持上传(upload)、查元数据(get / list)和删除(delete),不提供原始文件字节下载接口。
问:不同的 API Key 之间能共享同一个 file.uri 吗?
答:文件归属于创建该 API Key 所在的 Google Cloud / AI Studio 项目(Project)。跨项目的密钥无法读取彼此上传的文件 URI,会直接返回权限拒绝错误。
问:PDF 里的图表和扫描件排版会被识别吗?
答:通过 Files API 传入 PDF 时,Gemini 会按原生多模态视觉方式逐页解析页面图像与文字,不仅能读纯文本,还能看懂里面的折线图、表格与扫描页内容。
问:YouTube 公开视频也需要先下载再用 Files API 上传吗?
答:不需要。如果分析对象是公开的 YouTube 视频链接,Gemini API 支持直接在输入里传入视频网址解析;Files API 主要用于上传本地私有录屏、内部会议音频或未公开的超大 PDF 文档。
问:没有可用的个人谷歌账号,或者同时想开其他主流 AI 会员怎么办?
答:本站提供即买即发的 谷歌邮箱成品号(登录方法见 谷歌账号购买页),同时支持支付宝、微信支付与 AlipayHK 自助充值 ChatGPT Plus、Claude Code 等主流服务,实时价格与质保细则以各商品页说明为准。
相关教程
- Gemini API Python 调用教程:安装 google-genai SDK、流式输出、多轮对话与传图片
- Gemini API Node.js / JavaScript 调用教程:@google/genai 安装、流式输出
- Gemini API 报错 400、403、429、500、503、504 怎么办
- Claude API Files API 怎么用:上传一次、用 file_id 反复引用
参考资料
- Google Gemini API 官方文档:Files API — https://ai.google.dev/gemini-api/docs/files
- Google Gemini API 官方文档:Gemini Developer API Pricing — https://ai.google.dev/gemini-api/docs/pricing
0 条评论
还没有评论,来抢沙发~