FreeLLM API

项目概述

FreeLLMAPI 将多家 LLM 提供商的免费额度，以及自定义的 OpenAI 兼容聊天、嵌入、图像和音频端点，统一接入一个 /v1 API。项目聚合 34 个免费提供商、474 个模型系列和 635 个免费端点，每月可提供约 74 亿词元的推理能力。提供商密钥使用 AES-256-GCM 加密存储，路由器会根据模型速度、能力、可靠性和各密钥限额选择最佳服务；遇到限流或服务异常时，会自动切换提供商与密钥。

核心特性

• 完整兼容 OpenAI 接口，包括聊天补全、Responses、文本补全、图像与视频生成、语音、音频转录、嵌入和模型查询。
• 支持 Anthropic Messages API，可直接连接 Claude Code，同时提供 Gemini /v1beta 与可选的 Ollama 仿真接口。
• “融合”模型会将提示并行发送给多个免费模型，再由裁判模型综合生成答案。
• 提供工具调用、结构化输出、采样参数透传和六种智能路由策略。
• 按“平台、模型、密钥”跟踪 RPM、RPD、TPM、TPD 限额，并在 429、5xx 错误后执行冷却、密钥轮换和故障转移。
• 提供粘性会话、上下文交接、可选提示压缩、响应缓存、加密备份、健康检查及管理面板。
• 通过 /mcp 提供 MCP 服务，允许智能体查询模型、健康状态、缓存和路由元数据；/v1/docs 提供交互式 API 文档。
• 路由器支持自动同步签名模型目录，可获取模型、配额及兼容性更新，且不会覆盖本地启用状态或自定义提供商。

快速开始

使用 Docker 一键安装：

# 安装并启动本地服务；重复执行会保留配置与加密密钥
curl -fsSL https://freellmapi.co/install.sh | bash

启动后访问 http://localhost:3001，在“Keys”页面添加提供商密钥、调整回退链，并复制统一 API 密钥。Windows 和 macOS 也可使用桌面安装包。

兼容客户端将 OpenAI 基础地址设置为：

http://localhost:3001/v1

例如使用 Python SDK：

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("实际路由：", resp.headers.get("x-routed-via"))

响应头 X-Routed-Via: <平台>/<模型> 可用于确认实际服务提供商。

CLI 与智能体集成

Claude Code 等工具可通过一条命令读取实时目录、备份并合并配置：

npx freellmapi setup-claude --url http://localhost:3001 --api-key <unified-key>

项目兼容 Codex CLI、Gemini CLI、Cursor、Cline、Roo Code、OpenCode、Aider、Continue、Zed 等工具。终端也可管理密钥：

# 使用仪表板会话令牌执行提供商密钥操作
npx freellmapi keys add|list|remove|test <platform>

架构与运行方式

FreeLLMAPI 定位为本地优先、单用户系统。请求从本机路由器发送至已启用的上游提供商，密钥保存在本地 SQLite 中并静态加密。系统可运行于 Windows、macOS、Linux 及 Raspberry Pi 等 Node.js 20+ 环境，空闲内存占用约 40 MB。

免费版本每月获取签名目录快照，新模型通常在进入实时目录 30 天后可用；付费路由可当日同步。实时目录每天更新两次，但不会接触用户提示词、补全内容或提供商密钥。