本文整理自 GitHub 项目 tashfeenahmed/freellmapi 的中文 README（MIT 许可），功能描述与警示语忠于原文，章节组织与评述为本文编辑归纳。
几乎每家正经的 AI 实验室都给免费额度：每月几百万 token，或者每天几千次请求。单看一家就是个玩具，但把它们叠起来——34 家提供方、474 个模型系列、635 个免费端点，合计约每月 74 亿 token——这就是一股能用的算力。
问题是手工叠加太痛苦：三十四套 SDK、三十四种限流规则、三十四个可能随时失败的请求点。
FreeLLMAPI 做的事就是把这些收拢成一个 OpenAI 兼容的 /v1 端点。你的应用只认一个地址、一个密钥，由它的路由器在背后挑模型、扛限流、切提供方。
一、它到底解决了什么
一句话概括它的工作方式（原文）：
一个请求进去，最合适的免费模型出来：路由器挑出优先级最高、密钥健康且未超出任何限流的模型，在内存中解密密钥并调用提供方；遇到 429/5xx 就让那个密钥进入冷却，然后重试你链路上的下一个模型。
围绕这个核心，它做了几件关键的事：
- 按密钥的限流跟踪——以
(平台, 模型, 密钥)为单位维护 RPM/RPD/TPM/TPD 计数器，会学习各提供方公布的上限，让路由始终不越线。这是"能长期稳定白嫖"的技术前提。 - 统一模型条目——同一个模型出现在多家提供方上时合并成一个条目，组内严格故障转移。
- 自更新目录——每天两次从 freellmapi.co 同步**经过签名（Ed25519 验签）**的目录，新模型、额度变更和提供方怪癖修复自动生效，不用
git pull。免费额度的格局每周都在变，这一条很实用。 - 粘性会话——对话会在同一个模型上停留 30 分钟；中途确实换了模型，可选的精简交接说明能让话题保持连贯。
二、接口覆盖得比想象中全
很多聚合工具只做 Chat Completions，FreeLLMAPI 的接口面相当完整：
| 接口 | 用途 |
|---|---|
/v1/chat/completions、/v1/responses | 标准对话；后者是 Codex CLI 需要的 |
/v1/completions | 编辑器的幽灵文本补全 |
/v1/messages | Anthropic Messages 协议——Claude Code 和官方 Anthropic SDK 可直接接入 |
/v1beta | 原生 Gemini 协议——Gemini CLI 可用（含流式、token 计数、模型列表） |
/v1/images/generations、/v1/audio/speech | 图像生成与文本转语音 |
/v1/embeddings、/v1/models | 嵌入与模型列表 |
| Ollama 模拟（可选） | 给 Zed、JetBrains 及其他本地模型客户端提供 NDJSON 接口 |
还有两个亮点功能：
- Fusion（多模型合成）：请求虚拟模型
fusion，路由器把提示词并行分发给一组风格各异的免费模型，再由一个评审模型从多份草稿中合成答案。 - 工具调用与结构化输出：OpenAI 风格的
tools可在各提供方之间往返，纯文本形式的工具调用会被"救回"成真正的tool_calls；response_format、seed、logprobs等采样参数按提供方透传。
三、支持的生态
提供方（共 34 家）：Google、Groq、Cerebras、Mistral、Cohere、NVIDIA、HuggingFace、OpenRouter、Cloudflare、Z.ai（智谱）、OpenCode Zen、ModelScope 魔搭（Qwen3 / DeepSeek V4 / GLM-5，需绑定阿里云中国站账号）等。
635 个端点构成：584 个聊天、41 个嵌入、7 个转录、3 个视频。
可直接对接的编程智能体：
Claude Code、Codex CLI、Gemini CLI、Aider、Cline、Roo Code、Continue、OpenCode、Goose、Qwen Code、Kilo Code、Crush、Cursor、Zed、JetBrains AI。
setup-* 系列命令可以一条命令配好：
npx freellmapi setup-claude --url http://localhost:3001 --api-key <统一密钥>
每个生成器都支持 --dry-run，改动已有配置前会先创建带时间戳的备份，并且是合并进用户配置而不是覆盖。
四、五分钟部署
一行命令（需要 Docker），会建好 ~/freellmapi、生成加密密钥、拉镜像并启动容器：
curl -fsSL https://freellmapi.co/install.sh | bash
重复执行是安全的：.env 和加密密钥会保留，容器更新到 :latest。
启动后四步：
- 打开
http://localhost:3001 - 在密钥页添加你的提供方密钥
- 按喜好调整回退链顺序（比如一条编程链、一条视觉链）
- 取到统一 API 密钥，指向你的 OpenAI SDK
其他平台：Windows 最省事是下载 Releases 里的 .exe 安装包；Android 有实验性的 Termux 指南。还有原生桌面应用——路由器加仪表盘跑在托盘里，带一个悬浮窗显示实时请求统计，不需要注册账号或设密码，唯一的凭据就是悬浮窗里的统一 API 密钥（macOS 12+，Apple Silicon 选 arm64）。
本地开发：npm install && npm run dev（服务 :3001，仪表盘 :5173，双向热更新）。
五、怎么用：模型填 auto
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:3001/v1",
api_key="freellmapi-your-unified-key",
)
resp = client.chat.completions.create(
model="auto", # 交给路由器；也可用 "auto:fast"、"auto:smart"、配置档或具体模型 id
messages=[{"role": "user", "content": "用一句话概括罗马的衰亡。"}],
)
print(resp.choices[0].message.content)
print("Routed via:", resp.headers.get("x-routed-via"))
两个细节值得记住：
model可以填auto（路由器挑）、auto:fast、auto:smart、命名配置档，或具体模型 id；- 每个响应都带
X-Routed-Via: <平台>/<模型>头——出了问题能立刻知道是哪家提供方在拖后腿。
六、安全与隐私设计
这一点做得比同类项目认真：
- 提供方密钥 AES-256-GCM 加密存在 SQLite 里，每次请求时在内存中解密；你的应用自始至终只看到一个统一的
freellmapi-…bearer 令牌； - 本地优先、单用户设计，请求从你的机器直接发往你启用的上游提供方；
- 目录服务器不会看到你的提示词、补全结果或提供方密钥；你自己的启用/停用选择和自定义提供方永远不会被目录同步覆盖；
- 附带可选的响应缓存、加密的数据库备份、定期密钥健康检查、密钥批量导入导出；
- 运维友好：Node 20+ 能跑的地方都能跑，空闲常驻内存约 40MB，树莓派也行。
七、代价：必须知道的局限
这部分原文写得非常坦诚，值得完整转述：
叠加免费额度是有实实在在的代价的：没有前沿模型，延迟不稳定，没有 SLA。而且到了一天的后半段，顶级模型陆续触及当日上限，这个端点的实际智能水平会下滑，然后在 UTC 午夜重置。
免责声明也很清楚：
本项目用于个人实验和学习，不适用于生产环境。 免费额度的存在是为了让开发者拿来做原型；它们不是稳定、有支持的推理基础设施，也不该被当成这种东西。如果你要在 FreeLLMAPI 之上做真正的产品，上线前请换成付费 API。
另外，各家提供方的服务条款如何看待"一个个人的、单用户的代理"，项目在 2026 年 5 月逐家审查过并公开了结论；流量经它代理时，你注册账号时接受的上游条款依然适用，遵守它们是使用者的责任。
还有一个商业模式要说清：路由器本体永远是 MIT 许可、完全免费；另外有一条付费的实时目录服务（每年 $19 或一次性 $49 永久），用一个 fla_ 密钥覆盖你运行的所有路由器。不订阅也能用，只是目录更新要手动。
适合谁
- 想在原型阶段把 API 成本压到零的独立开发者；
- 想同时用 Claude Code / Codex CLI / Cursor 做多方案对比、又不想多开几份订阅的人；
- 想研究多提供方路由、限流跟踪、故障转移这些机制怎么实现的工程师（代码是 MIT 的，架构文档有中文版）。
不适合的也很明确：任何要上生产、要 SLA 的场景。把它当成一台"免费额度聚合试验台"而不是推理基础设施，心态就对了。
本文基于 tashfeenahmed/freellmapi 的中文 README（MIT 许可）整理，功能清单与局限、免责声明部分忠于原文；章节划分、表格整理与评述为本文作者归纳。项目文档有完整中文版（安装部署、API 参考、客户端接入、架构与内部实现），可到仓库 docs/zh-cn/ 查阅。