Cherry Studio v2 文件模块调研OpenAI / Google / Anthropic Files API 全景对比与接入启示【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio本技术指南基于 Cherry Studio 开源仓库中 files-api-research.md 调研报告调研时间 2026-04-18系统梳理 OpenAI、GoogleGemini Dev API、Anthropic 三家 Files API 的能力边界、生命周期、计费模型与 SDK 用法并结合仓库内 v2 文件模块重构的 RFC 设计文档 与 FileManager Architecture 落地现状说明这份调研结论如何指导 Cherry Studio 的提供商上传Provider Upload边界设计。阅读本文后你将掌握三家 Files API 的端点契约与参数语义、决定选型的关键差异维度持久性 / 容量 / 引用方式 / 计费、官方 SDK 的可用代码范式以及 Cherry Studio v2 文件模块在面对把本地文件交给 LLM 提供商这一能力时为何选择延后引入、以及延后期间保留的设计意图。一、调研背景为什么 Cherry Studio 需要研究三家 Files APICherry Studio 是一款支持多个 LLM 提供商的桌面客户端。在其 v2 数据与 UI 重构v2-refactor-temp/中文件管理模块FileManager被重新设计为扁平file_entry 多态file_ref的两表模型其中一个明确的扩展预留点就是上传到提供商provider upload。在 rfc-file-manager.md 的范畴声明中两条决策直接与本调研相关AI SDK upload 延后——待 Vercel AI SDK Files API 稳定后以独立 PR 引入Upload 派生数据延后——file_upload表在 SDK Files API 稳定后独立 PR 引入不在 Phase 1 交付物内。而 FileManager Architecture §9 Provider Upload Boundary 则明确了当前的落地原则FileManager 只为需要字节或临时路径的调用方提供 entry 读取与withTempCopy它不缓存提供商上传标识符。任何未来的提供商上传架构都需要自己的具体消费者与契约而不是投机性地扩展文件引用模型。换言之把文件上传到 OpenAI / Google / Anthropic在 Cherry 中属于未来能力但它的契约空间必须现在就想清楚。本调研报告正是为这个决策收集的事实基础——三家提供商对文件的定义、持久化语义、引用协议与计费模型差异巨大直接决定了file_upload表与上传服务未来应该长什么样。二、核心对比一览调研报告以一张总表给出三家 Files API 的横向对比这是全文的骨架先完整呈现维度OpenAIGoogleGemini Dev APIAnthropic状态GAGABetaanthropic-beta: files-api-2025-04-14单文件上限512 MB2 GB500 MB账号/项目总容量2.5 TB / 项目20 GB / 项目500 GB / 组织生命周期默认永久可选expires_after48 小时自动删除不可续期永久需手动DELETE存储计费原始 Files 免费Vector Store $0.10/GB·天全免费全免费引用方式file_id/file_url/file_database64≤32 MBfile_data.file_uri/ inline base64source.typefile/base64/url统一 blockpurpose 分类有assistants/batch/fine-tune/vision/user_data/evals无单一池无单一池跨能力复用最强Responses / Assistants / Batch / Fine-tune / Vision 共用file_id主要服务generateContentMessages Code Execution Skills 双向闭环特色能力Vector Store File Search、Batch 产出回取视频帧率 / 时间裁剪fps/start_offset与 Citations Prompt Caching 深度协同、产出可下载音视频原生图像为主音视频走专用模型✅ 完整支持MP4 / MP3 等❌ 未明确支持仅 PDF / 图像 / 文本 / 代码多云可用N/AVertex AI 走 GCS URI不用 Files APIBedrock / Vertex AI 不可用仅 Anthropic 第一方一句话定位OpenAI——跨能力复用之王一个file_id在 Responses / Batch / Fine-tune / Vision 之间打通purpose强制分类带来秩序感。Google——音视频之王2 GB 超大单文件 视频时间戳裁剪但48h 即焚决定了它只适合上传即用场景。Anthropic——工程优雅之王统一source协议把file当作base64/url的平替与 Citations / Prompt Caching / Skills 深度联动但仍在 beta 且不支持音视频。选型建议场景推荐理由长期知识库 / 跨会话复用Anthropic / OpenAI均持久避开 Google 的 48h 过期视频 / 音频理解Google几乎是唯一选择一份数据跑多条流水线在线 Batch 微调OpenAIpurpose体系最顺手带高质量引用的文档问答Anthropicdocumentcitations.enabledfile_id组合最舒服预算敏感Google / Anthropic存储全免费OpenAI 的 Vector Store 按 GB·天收费三、OpenAI Files API3.1 基本端点Base URLhttps://api.openai.com需Authorization: Bearer $OPENAI_API_KEY。操作方法路径上传文件POST/v1/filesmultipart/form-data字段filepurpose可选expires_after列出文件GET/v1/files可按purpose/limit/order/after过滤获取元数据GET/v1/files/{file_id}下载内容GET/v1/files/{file_id}/content删除文件DELETE/v1/files/{file_id}File 对象典型字段id / object / bytes / created_at / expires_at / filename / purpose / status / status_details。3.2 purpose 参数purpose是 OpenAI Files API 的强制分类字段决定文件能被哪些能力消费assistants供 Assistants APIcode_interpreter、file_search引用。batchBatch API.jsonl输入产出 purpose 为batch_output。fine-tune微调训练集.jsonl符合 chat/completion 格式。visionVision / Responses 图像输入png/jpg/gif/webp。user_dataResponses API 通用用户文档PDF 等也可作为 Prompt 模板变量。evalsEvals API 数据集细节未完全确认。只读/系统产出batch_output、fine-tune-results不可手动上传。3.3 文件限制单文件512 MB。File Search 单文件 token≤ 5,000,000 tokens。项目总容量2.5 TB组织层面无硬上限。支持格式File Search 类文本文档pdf/md/docx/txt/html/代码、Visionpng/jpg/gif/webp、Batch/Fine-tunejsonl、Responsesinput_filePDF 等。3.4 生命周期默认expires_at: null文件永久保留需手动 DELETE。上传时可传expires_after相对created_at的秒数 anchor到期自动删除。Batch 产出文件不会自动过期需手动清理。Vector Store 是独立对象有自己的 expiration 策略供 File Search 使用。3.5 与其他能力的集成Responses API主推input_file { file_id }/input_image { file_id }也支持file_database64 ≤32 MB与file_url。Assistants API v2file_search工具走 Vector Store 消费purposeassistants的文件code_interpreter通过 messageattachments引用。v1 已弃用。Batch API上传purposebatch的.jsonl在/v1/batches用input_file_id引用输出通过/v1/files/{output_file_id}/content下载。Fine-tuningpurposefine-tune上传训练 / 验证集。Vision / 图像生成purposevision可做视觉模型输入或 image edit 源图。3.6 计费Files API 原始对象存储不单独计费。File Search / Vector Store$0.10 / GB·天每组织前 1 GB 免费工具调用 $2.50 / 1k calls。ChatKit / Agent Kit 上传$0.10 / GB·天每账号每月首 1 GB 免费。Fine-tune 训练数据训练期不单独计存储费按 token 训练费计。3.7 最简 SDK 示例Pythonopenai官方 SDKfrom openai import OpenAI client OpenAI() f client.files.create(fileopen(report.pdf, rb), purposeuser_data) resp client.responses.create( modelgpt-5, input[{role: user, content: [ {type: input_text, text: 总结这份 PDF}, {type: input_file, file_id: f.id}, ]}], ) print(resp.output_text)JavaScriptimport fs from fs; import OpenAI from openai; const openai new OpenAI(); const f await openai.files.create({ file: fs.createReadStream(report.pdf), purpose: user_data, }); const r await openai.responses.create({ model: gpt-5, input: [{ role: user, content: [ { type: input_text, text: 总结这份 PDF }, { type: input_file, file_id: f.id }, ]}], }); console.log(r.output_text);3.8 差异化亮点一次上传、多端复用同一file_id可在 Responses / Assistants / Batch / Fine-tune / Vision 之间跨场景引用受 purpose 约束这是相较 Anthropic 与 Google 较少见的长生命周期 跨能力设计。三种文件传递方式并存file_idFiles API/file_url外链/file_database64 内联 ≤32 MB开发者在持久托管与一次性内联之间可灵活选择。3.9 未确认项evalspurpose 的完整字段约束。各 purpose 的精细 MIME 白名单。expires_after的最大 / 最小秒数上限。四、Google Gemini Files API聚焦Gemini Developer APIgenerativelanguage.googleapis.com下的 Files service末尾对比 Vertex AI。4.1 基本端点REST v1beta基址https://generativelanguage.googleapis.com操作方法路径媒体上传resumablePOST/upload/v1beta/files仅创建元数据POST/v1beta/files列出文件GET/v1beta/filespageSize≤ 100默认 10获取文件GET/v1beta/files/{name}删除文件DELETE/v1beta/files/{name}注册 GCS 对象POST/v1beta/files:register文件资源字段name / displayName / mimeType / sizeBytes / uri / statePROCESSING / ACTIVE / FAILED/ expirationTime / sha256Hash / videoMetadata。4.2 上传协议Resumable upload推荐三步协议X-Goog-Upload-Protocol: resumableX-Goog-Upload-Command: start/upload, finalize头。SDKfiles.upload底层即此。Inlinebase64inlineData字节直接放进generateContent.contents。选择门槛图片请求总大小 ≤ 20 MB 用 inline否则走 Files API。PDF小文档 / 一次性用 inline较大或复用走 Files API无明确 MB 阈值。视频1 分钟可 inline100 MB 或 10 分钟以上强制Files API。4.3 文件限制单文件2 GB项目总存储20 GB。PDF单文件 ≤ 50 MB 且 ≤ 1000 页每页258 tokens。图片 MIMEimage/png、image/jpeg、image/webp、image/heic、image/heif。视频 MIMEMP4、MPEG、MOV、AVI、FLV、MPG、WebM、WMV、3GPP。音频约32 tokens/秒完整 MIME 列表未完全确认。普通generateContent请求总 payload ≤ 100 MB。4.4 生命周期与 TTL48 小时自动删除存储 48 小时后自动清理期间可读元数据但下载受限。expirationTime字段标注过期时刻。不支持延长 / 续期。长期保存请走 GCSVertex AI或重新上传。4.5 与 generateContent 的集成在contents.parts中通过file_data引用{file_data: {mime_type: video/mp4, file_uri: files/abc-123}}视频特殊点上传后state先为PROCESSING需轮询至ACTIVE才能推理。videoMetadata可传fps/start_offset/end_offsetPrompt 内用MM:SS引用时间戳。默认 1 FPS 抽帧默认分辨率约 300 tokens/秒低分辨率 100 tokens/秒单帧标准分辨率 258 tokens。1M context 模型可处理默认分辨率 1 小时视频低分辨率 3 小时。4.6 计费Files API 本身免费所有可用区域存储均不收费。输入 token 按模型实际消耗计价PDF 258 tokens/页视频按秒图片按分辨率 tile。4.7 最简 SDK 示例新 SDKgoogle-genaiPythonfrom google import genai client genai.Client(api_keyYOUR_KEY) my_file client.files.upload(filesample.pdf) resp client.models.generate_content( modelgemini-2.5-pro, contents[请总结这份文档, my_file], ) print(resp.text) for f in client.files.list(): print(f.name, f.state) client.files.delete(namemy_file.name)JavaScriptimport { GoogleGenAI, createUserContent, createPartFromUri } from google/genai; const ai new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY }); const uploaded await ai.files.upload({ file: sample.mp3, config: { mimeType: audio/mpeg }, }); const resp await ai.models.generateContent({ model: gemini-2.5-flash, contents: createUserContent([ 转写这段音频, createPartFromUri(uploaded.uri, uploaded.mimeType), ]), }); console.log(resp.text);旧的google-generativeai已进入维护模式新项目请用google-genaiPython/google/genaiNode。4.8 Vertex AI 对比Vertex AI没有独立 Files API文件引用通过GCSgs://URI主流方式公开可读或同项目。inline base64fileData。公网 HTTP(S) URL。Vertex AI Studio 控制台直传最大 7 MB。因此生产上 Vertex AI 侧的Files等价于 GCS 生命周期管理用户自管 TTL、权限、计费不存在 48 小时自动过期Gemini Developer API 的 Files 则是托管式、免费但 48h 即焚的临时存储。五、Anthropic Files API5.1 当前状态与 Beta HeaderFiles API 仍处于beta 阶段未 GA。调用任一端点需携带anthropic-beta: files-api-2025-04-14 anthropic-version: 2023-06-01Messages 中引用file_id时同样需要此 beta header。不适用于 ZDR且在Amazon Bedrock / Google Vertex AI 上不可用。值得一提的仓库佐证Cherry Studio 对anthropic-beta头的处理已有现成基建。src/main/ai/utils/anthropicHeaders.ts 负责根据请求场景返回应携带的 beta 标志名列表src/main/ai/runtime/aiSdk/params/features/anthropicHeaders.ts 则在 Anthropic-DIRECT 请求中把betas列表写进params.headers[anthropic-beta]Bedrock 场景由 Bedrock 侧处理。这意味着未来若接入 Files API只需把files-api-2025-04-14追加进既有的 beta 标志管线改动面很小。5.2 基本端点方法路径说明POST/v1/files上传multipart/form-data字段fileGET/v1/files分页列出当前 workspace 的文件GET/v1/files/{file_id}获取元数据id / filename / mime_type / size_bytes / created_at / type / downloadable可选scopeGET/v1/files/{file_id}/content下载文件内容仅限Skills / Code Execution 产出用户上传文件不可回取DELETE/v1/files/{file_id}删除不可恢复5.3 文件限制与 MIME单文件500 MB。组织总容量500 GB。速率限制beta 期约 100 req/min。支持 MIMEapplication/pdf→documentblocktext/plain→documentblockimage/jpeg/image/png/image/gif/image/webp→imageblockCode Execution 支持的数据集CSV / XLSX / DOCX 等→container_uploadblock音视频Files API 页未列出原生音视频类型仅视觉与 Code Execution 场景。音视频支持未确认。不支持作为document直传的格式.csv / .md / .docx / .xlsx建议先转 PDF 或纯文本。5.4 生命周期持久存储文件一直存在直到显式DELETE。作用域为 API key 所属workspace同 workspace 其他 key 可共享。删除后极短时间内进行中的 Messages 调用仍可能可读之后按 Anthropic 数据保留策略清除。无自动过期与 OpenAIexpires_after、Google 48h TTL 不同。5.5 与 Messages API 的集成source.type file替代base64/url{ type: document, source: { type: file, file_id: file_011C... }, title: ..., context: ..., citations: { enabled: true } }{ type: image, source: { type: file, file_id: file_011C... } }三种 source 的取舍base64每次请求重编码、吃带宽。url需可公开访问。file只传一次、跨请求复用天然适合 Prompt Caching同file_id哈希稳定命中率高。Code Execution Tool与Skills双向既消费 Files 作为输入又产出 Files图表、CSV可通过/content下载。Computer Use不直接消费file_id截图走 tool_result 的 image block是否有直接消费路径未确认。5.6 计费存储 / 上传 / 下载 / 列举 / 元数据 / 删除全免费。文件真正进入 Messages 请求时内容按普通输入 token计价。与Prompt Caching组合把大型 PDF / 图像放进带cache_control的 block配合稳定file_id可大幅降低重复请求的 token 成本。5.7 最简 SDK 示例Pythonfrom anthropic import Anthropic client Anthropic() up client.beta.files.upload( file(doc.pdf, open(doc.pdf, rb), application/pdf), ) resp client.beta.messages.create( modelclaude-opus-4-7, max_tokens1024, betas[files-api-2025-04-14], messages[{role: user, content: [ {type: text, text: 总结这份文档}, {type: document, source: {type: file, file_id: up.id}}, ]}], )JavaScriptimport Anthropic, { toFile } from anthropic-ai/sdk; import fs from fs; const anthropic new Anthropic(); const up await anthropic.beta.files.upload({ file: await toFile(fs.createReadStream(doc.pdf), undefined, { type: application/pdf }), betas: [files-api-2025-04-14], }); const resp await anthropic.beta.messages.create({ model: claude-opus-4-7, max_tokens: 1024, betas: [files-api-2025-04-14], messages: [{ role: user, content: [ { type: text, text: 总结这份文档 }, { type: document, source: { type: file, file_id: up.id } }, ]}], });5.8 差异化亮点统一 content block 抽象同一source协议把base64/url/file视为可互换子类型前端代码几乎无需改动即可从嵌入式升级为引用式比 OpenAI 的file_id与image_url混合模型更一致。与 Skills / Code Execution 的双向打通既能上传给模型读Code Execution 产出的图表 / 数据也以file_id回流并可/content下载——形成上传 → 分析 → 产出 → 下载闭环OpenAI 的 Code Interpreter 回取需走 assistants/thread 链路路径更长。Citations 与 Prompt Caching 协同documentblock 内建citations.enabled配合file_id产生稳定字符 / 页码级引用Prompt Caching 命中率相比重复 base64 显著更高。持久 无过期对比 OpenAI Assistants 默认生命周期语义与 Google 的 48h 自动过期对常驻知识库 / 跨会话引用更友好。上传 / 存储完全免费只在推理时按 token 计费商业模型透明。5.9 未确认项音视频原生支持。Computer Use 是否直接消费file_id。六、调研结论对 Cherry Studio v2 文件模块的设计启示6.1 三家能力差异决定了上传标识符必须由提供商侧自治FileManager Architecture §9 明确FileManager不缓存提供商上传标识符。本次调研为这条边界提供了充分依据同一份本地文件在 OpenAI 得到file_id受purpose约束、可跨 Responses/Batch/Fine-tune/Vision 复用在 Google 得到file_uri48 小时即焚在 Anthropic 得到file_idBeta、仅第一方 API、不适用于 Bedrock/Vertex AI。三家对文件对象的生命周期语义互不兼容OpenAI 可选过期、Google 强制 48h 过期、Anthropic 永久驻留。若在 Cherry 的通用文件引用模型file_ref中强行内建提供商文件对象概念会把这些互斥语义泄漏进持久化层。因此 v2 的选择是file_ref保持业务语义sourceType/sourceId/role提供商上传标识符由未来独立的file_upload表与上传服务自治这正好与调研中三家上传 API 契约无法统一抽象的事实互相印证。6.2file_upload表的设计意图延后引入rfc-file-manager.md §4.4 记录集成 Vercel AI SDKSharedV4ProviderReference所需的file_upload表在 SDK Files API 稳定后以独立 PR 引入不在 Phase 1 交付物内。调研报告的实践价值在于它锁定了这张表未来至少需要承载的字段族提供商标识如 OpenAIfile_id/ Googlefile_uri/ Anthropicfile_id、到期时间OpenAIexpires_at/ GoogleexpirationTime、以及来源文件到提供商对象的映射它同时提醒由于 Google 侧文件天然短命file_upload的清理策略不能只按 Cherry 本地file_entry生命周期推进还要考虑提供商侧的 TTL 语义——这与 FileManager Architecture §10 Orphan Sweep 中entry cleanup / DB sweep / file sweep三通道既有清理框架如何扩展是同一类问题。6.3 按场景收敛的接入优先级把调研的选型建议映射回 Cherry Studio 的业务场景可以给出这样的优先级判断Cherry 业务场景首选提供商能力理由源自调研长期知识库 / 跨会话附件复用Anthropic / OpenAI均持久避开 Google 48h 过期视频 / 音频理解如本地媒体文件Google Gemini2 GB 单文件上限 原生音视频 时间戳裁剪一份文件跑在线 Batch 微调流水线OpenAIpurpose体系天然支持多流水线复用带页码/字符级引用的文档问答Anthropicdocumentcitations.enabled 稳定file_id组合低成本常驻存储全免费Google / AnthropicOpenAI Vector Store 按 GB·天收费值得注意的是这并不意味着 Cherry 需要在通用层为三家分别建模——恰恰相反v2 架构选择让file_entry/file_ref保持与提供商无关把是否上传、上传到谁、何时过期全部留给未来的上传服务决策这正是调研报告最重要的工程结论文件引用引用谁与文件上传托管在哪是两件不同的事。6.4 未来接入时的复用面从仓库现状看未来引入 Files API 时 Cherry 已有可直接复用的设施Beta 头管线src/main/ai/utils/anthropicHeaders.ts 与 src/main/ai/runtime/aiSdk/params/features/anthropicHeaders.ts 已提供anthropic-beta的组装与写入通道Anthropic Files API 所需的files-api-2025-04-14只需扩展标志列表FileHandle 抽象FileManager Architecture §1.6.5 的FileHandle多态分发让managed本地托管与unmanaged外部路径两种来源统一入口未来接withTempCopy到提供商上传时读取侧无需为上传场景重写孤儿清理框架file_ref的注册式OrphanRefScanner见 rfc-file-manager.md §六与 FileManager 的 orphan sweep 通道可为file_upload表的过期行复用同一套扫描 报告 清理机制。七、结语这份调研报告回答了三个问题三家 Files API各自的能力边界容量、格式、音视频、生命周期语义永久 / 48h / 显式删除、以及引用与计费模型file_id/file_uri/source.file。它直接支撑了 Cherry Studio v2 文件模块两条关键决策——file_upload表延后、提供商上传标识符不进通用引用模型——并在未来 AI SDK Files API 稳定后为独立 PR 提供了现成的契约清单与场景优先级。对于要在 Cherry Studio 之上做多提供商文件能力的开发者建议把本文的选型建议表作为需求入口把三家 SDK 示例作为接入脚手架同时留意调研报告中标注的未确认项OpenAIevals约束与expires_after上下限、Google 音频 MIME 全表、Anthropic 音视频与 Computer Use 支持这些细节在正式接入前需要以当时的最新官方文档复核。附相关仓库资料调研报告原文v2-refactor-temp/docs/file-manager/files-api-research.mdv2 文件模块实现 RFCv2-refactor-temp/docs/file-manager/rfc-file-manager.mdFileManager 架构与提供商上传边界docs/references/file/file-manager-architecture.md文件模块整体架构docs/references/file/architecture.md文件引用关系 Schemasrc/main/data/db/schemas/fileRelations.tsAnthropic beta 头组装src/main/ai/utils/anthropicHeaders.ts、src/main/ai/runtime/aiSdk/params/features/anthropicHeaders.ts【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考