Gemini Files API 怎么管理上传文件：ACTIVE 状态、48 小时过期与主动删除

把 PDF 或视频直接塞进每一次 Gemini 请求，最先变慢的通常不是模型，而是重复上传。同一份资料要问三四个问题时，更合适的做法是先交给 Files API，再用返回的文件 URI 参与后续请求。不过“上传接口返回成功”只说明资源已经创建，文件是否完成处理、何时过期、什么时候应该主动删除，还需要应用自己管控。

先分清三个状态：已创建、处理中、可引用

Files API 返回的是一个 File 资源。资源里有 name、uri、state、sizeBytes、createTime 和 expirationTime 等字段。真正影响下一步的不是 HTTP 200 响应，而是 state：上传后文件可能还在后台处理，失败时还会在资源里带上对应的错误信息。

因此，业务表不要只保存一个“上传成功”布尔值。最少要把远端资源名、URI、状态和过期时间记录下来，并保留本地文件的 SHA-256。这样同一文件重试时可以判断是“已有可复用资源”，还是“旧资源已过期，需要重新上传”。

上传、查询和删除应该怎么选

如果资料会被多个提示复用，Files API 能把媒体上传与模型请求拆开，减少每次请求重复传输。若只有一次很小的请求，直接以内联数据提交更简单；若是大文件、视频或需要多轮提问，先上传再引用通常更容易控制重试和成本。

这里有一个容易混淆的点：文件的 uri 是给模型请求引用的资源地址，不能当作永久下载地址。官方说明文件在保存期间也不能通过 Files API 下载，所以原文件仍要由自己的对象存储或业务归档负责。

用 Go 把 ACTIVE 检查做成可重试步骤

下面的示例只保留生命周期里最关键的读取动作。上传接口的 multipart 细节可以交给项目现有的上传模块；拿到 files/... 资源名后，统一用 GET 查询状态。轮询要有上限，不能让一个处理异常的文件一直占住任务。

type GeminiFile struct {
    Name           string `json:"name"`
    URI            string `json:"uri"`
    State          string `json:"state"`
    ExpirationTime string `json:"expirationTime"`
    Error          *struct {
        Message string `json:"message"`
    } `json:"error,omitempty"`
}

func waitFile(ctx context.Context, client *http.Client, apiKey, resource string) (GeminiFile, error) {
    for attempt := 0; attempt 

生产代码还应检查响应状态码、限制响应体大小，并对 429、5xx 和网络断开做带上限的退避。示例故意没有把轮询次数写成无限循环：处理异常时，明确失败比悄悄堆积任务更容易恢复。

48 小时窗口内，哪些数据要落库

官方文档列出的保存窗口和容量限制适合做任务级资源，不适合替代自己的文件管理。可以建立一张简化的 ai_file_asset 表：

CREATE TABLE ai_file_asset (
  id BIGINT PRIMARY KEY,
  task_id VARCHAR(64) NOT NULL,
  source_sha256 CHAR(64) NOT NULL,
  remote_name VARCHAR(128) NOT NULL,
  remote_uri TEXT NOT NULL,
  state VARCHAR(16) NOT NULL,
  expires_at TIMESTAMP NULL,
  deleted_at TIMESTAMP NULL,
  created_at TIMESTAMP NOT NULL,
  UNIQUE KEY uk_task_file (task_id, source_sha256)
);

任务重试时先按 task_id + source_sha256 查找。记录仍为 ACTIVE 且距离 expires_at 有余量，就继续复用；已经过期或查询返回资源不存在，则重新上传。删除动作写入 deleted_at，不要直接物理抹掉整行，否则很难解释一次任务到底用了哪份资料。

容易踩中的四个边界

• 把 HTTP 成功当成 ACTIVE：上传后的处理状态仍需查询，不能立即把 URI 交给模型。
• 只保存 URI：没有远端 name 和本地哈希，过期重传时容易产生重复资源。
• 依赖远端文件长期保存：48 小时是 Files API 的窗口，不是项目归档方案。
• 删除后不留审计：任务完成、用户撤回或敏感数据清理，都应记录触发原因和时间。

常见问题

Gemini Files API 上传后为什么不能马上使用？

文件可能仍处于处理状态。先读取 File 资源，等 state 变成 ACTIVE，失败则读取错误信息并结束本次任务。

Files API 的文件能保存多久？

官方文档说明文件保存 48 小时，并提供 expirationTime。需要更长时间时，应在自己的存储系统保留原件并在需要时重新上传。

文件 URI 可以当下载链接吗？

不可以。URI 主要用于在 Gemini 请求中引用文件，Files API 文档还特别说明保存期间不能下载文件。

什么时候应该主动删除文件？

短任务完成、用户撤回资料、资料包含敏感内容，或本地已经确认不再需要时，都可以主动删除，并把删除结果写入任务审计记录。

把文件当成有期限的任务资源

Files API 最稳妥的接法不是“上传一次、拿到 URI 就结束”，而是把它当作有状态、有期限、可回收的任务资源：上传后查询，ACTIVE 后引用，任务结束后删除，过期前由本地记录决定是否重传。这样既能享受大文件复用的便利，也不会把临时文件误当成永久知识库。