FreeLLMAPI: gom hàng chục gói LLM miễn phí vào một endpoint — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về tashfeenahmed/freellmapi — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: FreeLLMAPI: gom nhiều LLM miễn phí vào một API — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
FreeLLMAPI là một router tự host, gom nhiều gói LLM miễn phí (Google, Groq, Cerebras, OpenRouter…) thành một endpoint /v1 tương thích OpenAI. Bạn thêm key của từng nhà cung cấp, rồi trỏ SDK hoặc công cụ lập trình vào địa chỉ local. Cài bằng một dòng lệnh nếu đã có Docker, hoặc tải bản desktop trên Windows và macOS.
FreeLLMAPI là một ứng dụng chạy trên máy bạn, gom nhiều gói LLM miễn phí của các hãng khác nhau thành MỘT địa chỉ /v1 giống API của OpenAI. Bạn thêm key miễn phí của từng hãng vào một bảng quản trị. Sau đó công cụ nào của bạn nói được kiểu OpenAI cũng dùng được: thư viện Python, Cursor, Cline, Aider, Claude Code, Codex CLI…
Vấn đề nó giải quyết rất đời thường. Hãng AI nào cũng có gói miễn phí, nhưng mỗi gói có giới hạn riêng: số yêu cầu mỗi phút, số token mỗi ngày. Dùng tay từng gói thì rối và hay bị chặn giữa chừng. FreeLLMAPI làm thay phần đó: chọn model phù hợp cho mỗi yêu cầu, và khi một nhà cung cấp báo hết hạn mức thì tự chuyển sang nhà khác.
Repo hiện có khoảng 51.280 sao và 7.137 fork, giấy phép MIT, viết bằng TypeScript. Theo tác giả, danh mục hiện theo dõi 87 nhà cung cấp và 1.313 endpoint miễn phí. Điểm đáng giá nhất: bạn chỉ cần nhớ một địa chỉ và một key, còn chuyện nhà nào còn quota thì router lo. Cái giá là bạn tự cài, tự giữ key, và đây là công cụ cho mục đích thử nghiệm cá nhân.
tashfeenahmed/freellmapi
FreeLLMAPI gom các gói LLM miễn phí của nhiều nhà cung cấp thành một địa chỉ /v1 kiểu OpenAI chạy trên máy bạn, tự chọn model và tự chuyển khi hết hạn mức.
I.FreeLLMAPI làm được gì
Một endpoint cho nhiều loại yêu cầu. Ngoài chat (/v1/chat/completions), router còn có /v1/responses (Codex CLI cần cái này), /v1/completions, ảnh, video, giọng nói, chuyển giọng nói thành chữ, embeddings và /v1/models. Lợi ích: bạn không phải học API riêng của từng hãng.
Nói được cả kiểu Anthropic, Gemini và Ollama. Địa chỉ /v1/messages dùng định dạng của Anthropic, nên Claude Code và SDK của Anthropic chạy được trên kho model miễn phí. Gemini CLI dùng /v1beta. Ollama là tuỳ chọn bật thêm, dành cho Zed, JetBrains và các công cụ tương tự.
Định tuyến thông minh, tự chuyển khi lỗi. Router có sáu chiến lược, chấm điểm model theo tốc độ, năng lực và độ ổn định. Khi gặp lỗi 429 hoặc 5xx, nó thử model kế tiếp, có thời gian nghỉ và xoay key. Bạn có thể gọi model="auto", hoặc auto:fast, auto:smart, một profile, hay tên model cụ thể.
Theo dõi hạn mức từng key. Router đếm số yêu cầu và token theo phút và theo ngày cho từng key, để luôn nằm dưới trần của gói miễn phí.
Key được mã hoá. Key của các hãng được mã hoá AES-256-GCM trong SQLite. Ứng dụng của bạn chỉ thấy một token chung dạng freellmapi-….
Bảng quản trị. Giao diện web để quản lý key, sắp xếp chuỗi dự phòng, thử trực tiếp (playground) và xem thống kê độ trễ. Có 60 ngôn ngữ, trong đó có thể gồm tiếng Việt, nhưng README không nói rõ nên bạn cứ mở phần Settings để xem.
Các tính năng thêm: Fusion (gửi cùng một câu cho nhiều model rồi để một model "quan toà" tổng hợp), tool calling, đầu ra có cấu trúc, cache phản hồi tuỳ chọn, nén prompt tuỳ chọn, MCP server để ChatGPT hoặc agent gọi vào, và cả endpoint tuỳ biến (llama.cpp, LM Studio, vLLM, Ollama…).
II.Cần chuẩn bị gì
- Máy chạy được: Windows, macOS, Linux hoặc cả Raspberry Pi. README nói chạy ở đâu có Node 20+ là chạy được, và dùng khoảng 40 MB RAM lúc rảnh.
- Node:
package.jsonyêu cầu Node từ 20.18.0 đến dưới 25.0.0. Chỉ cần khi bạn chạy từ mã nguồn hoặc dùng lệnhnpx. - Docker: bắt buộc nếu dùng cách cài một dòng lệnh.
- Key của nhà cung cấp: bạn tự đăng ký tài khoản miễn phí ở các hãng (Google, Groq, Cerebras, OpenRouter…) và lấy key. README không hướng dẫn từng hãng. Danh sách và hạn mức xem ở trang chủ dự án.
- Phần cứng: README không yêu cầu GPU. Các model chạy ở phía nhà cung cấp.
- Biến cấu hình trong
.env.example:ENCRYPTION_KEY,PORT,REQUEST_ANALYTICS_RETENTION_DAYS,REQUEST_ANALYTICS_MAX_ROWS. Cách cài bằng một dòng lệnh sẽ tự tạo khoá mã hoá cho bạn.
III.Cài đặt từng bước
- Mở terminalTerminal có bash và Docker đã chạy
- Chạy lệnh càiMột dòng lệnh dựng thư mục, khoá mã hoá và container
- Mở bảng quản trịVào http://localhost:3001
- Thêm keyDán key các hãng vào trang Keys
- Lấy key chungCopy unified key ở đầu trang Keys
- Trỏ công cụ của bạnĐặt base URL thành http://localhost:3001/v1
Có ba đường cài: một dòng lệnh dùng Docker, bản desktop có sẵn trình cài, hoặc chạy từ mã nguồn. Phần dưới đi theo đường một dòng lệnh vì nhanh nhất.
A.Chạy lệnh cài một dòng
Mở terminal (macOS/Linux dùng Terminal có sẵn; Windows nên dùng Git Bash hoặc WSL, vì lệnh dưới là bash). Docker phải đang chạy trước. Bạn dán:
curl -fsSL https://freellmapi.co/install.sh | bashLệnh này tải script về và chạy. Theo README, script tạo thư mục ~/freellmapi, sinh khoá mã hoá, kéo image và khởi động container. Chạy lại lệnh là an toàn: file .env và khoá mã hoá được giữ nguyên, container được cập nhật lên bản :latest. Nếu ngại "tải về rồi chạy luôn", README có dẫn link để bạn đọc script trước.
B.Mở bảng quản trị và thêm key
Mở trình duyệt, vào http://localhost:3001. Ở trang Keys, thêm key của từng nhà cung cấp mà bạn đã đăng ký. Sau đó vào mục Fallback Chain để sắp thứ tự ưu tiên model theo ý bạn.
C.Lấy unified key
Ngay đầu trang Keys có một key chung dạng freellmapi-…. Đây là key duy nhất bạn đưa cho ứng dụng của mình. Key thật của các hãng nằm lại trong router.
Key chung và key của từng hãng đều là thông tin nhạy cảm. Đừng dán vào Git, ảnh chụp màn hình hay tin nhắn nhóm.
D.Cách khác: bản desktop (Windows và macOS)
Trên Windows, README khuyên dùng trình cài .exe trong trang Releases của repo. macOS có file .dmg: chọn arm64 nếu máy Apple Silicon, x64 nếu máy Intel (cần macOS 12 trở lên). Bản này chạy cả router và bảng quản trị từ khay hệ thống, không cần đặt tài khoản hay mật khẩu. Thứ bạn cần chỉ là unified key hiện trong cửa sổ nhỏ ở khay.
E.Cách khác: Docker Compose hoặc chạy từ mã nguồn
Repo có Dockerfile và docker-compose.yml. README chính chỉ trỏ tới tài liệu cài đặt chi tiết ở docs/en/install/01-install.md (gồm Docker Compose, chạy dev, build production, truy cập từ mạng LAN và sao lưu). Mình không chép lệnh ở đây vì phần README đã cung cấp không ghi các lệnh đó. Bạn mở file này để làm theo. Muốn lấy mã nguồn thì:
git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapiIV.Kiểm tra đã chạy được chưa
Cách dễ nhất: mở http://localhost:3001. Thấy bảng quản trị là router đã chạy. Nếu bạn đổi biến PORT, thay số cổng tương ứng.
Bước kiểm tra thứ hai là gọi thử bằng Python. Cài thư viện openai (pip install openai), rồi chạy đoạn mẫu của README:
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",
messages=[{"role": "user", "content": "Summarise the fall of Rome in one sentence."}],
)
print(resp.choices[0].message.content)
print("Routed via:", resp.headers.get("x-routed-via"))Thay freellmapi-your-unified-key bằng key chung của bạn. Nếu in ra được câu trả lời, bạn đã thành công. Theo README, mọi phản hồi đều kèm header X-Routed-Via cho biết model nào thực sự trả lời. Bạn cũng có thể dùng trang playground trong bảng quản trị để thử mà không cần viết code.
V.Dùng vào việc thật
A.Lập trình viên mới: dùng trợ lý code mà không tốn tiền key
Bạn đang học lập trình, muốn dùng Cline, Aider hay Cursor nhưng chưa muốn trả phí. Trong công cụ, đặt base URL là http://localhost:3001/v1, API key là unified key, model là auto. Router sẽ chọn model miễn phí còn quota. Khi một hãng báo hết hạn mức, yêu cầu tiếp theo tự sang hãng khác nên bạn ít bị đứt mạch.
Một địa chỉ, một key, còn chuyện hãng nào còn quota thì để router lo.
Ông T
B.Người dùng Claude Code: trỏ vào kho model miễn phí
Nếu đã dùng Claude Code và muốn thử chạy trên model miễn phí, README có sẵn lệnh tự cấu hình. Lệnh này đọc danh mục của bạn, sao lưu cấu hình cũ rồi gộp thêm vào:
npx freellmapi setup-claude --url http://localhost:3001 --api-key <unified-key>README cho biết mọi bộ tạo cấu hình đều có --dry-run để xem trước mà chưa ghi. Có thêm npx freellmapi launch (Claude Code) và launch-codex (Codex) để giữ key ngoài file cấu hình. Kết quả: mở công cụ lên là chạy qua router của bạn. Chất lượng tuỳ model miễn phí được chọn, nên đừng kỳ vọng ngang model trả phí.
C.Nhân viên văn phòng: tóm tắt và dịch nhanh bằng script nhỏ
Bạn có một đống văn bản cần tóm tắt hoặc soạn lại. Nhờ đồng nghiệp biết Python viết một script dùng đoạn mẫu ở trên, đổi nội dung content thành yêu cầu của bạn, ví dụ "Tóm tắt đoạn sau trong 3 gạch đầu dòng". Vì là endpoint kiểu OpenAI, script này sau đó đổi sang dịch vụ khác chỉ bằng cách sửa hai dòng base_url và api_key.
D.Chủ shop hoặc dev: quản lý key bằng dòng lệnh
Khi có nhiều key cần thêm hoặc kiểm tra, bạn không phải bấm tay trên web. README có nhóm lệnh quản lý key, cần dashboard session token (biến FREELLMAPI_DASHBOARD_TOKEN hoặc cờ --token):
npx freellmapi keys add|list|remove|testĐây là cú pháp tóm tắt trong README: thêm, liệt kê, xoá hoặc kiểm tra lại các key đã lưu. Chi tiết từng lệnh nằm ở cli/README.md. Bạn chạy keys test định kỳ để biết key nào đã hết hạn.
VI.Lỗi hay gặp và cách xử lý
Lệnh curl ... | bash báo lỗi hoặc không thấy Docker. Cách một dòng lệnh cần Docker đã cài và đang chạy. Mở Docker Desktop (hoặc dịch vụ Docker) lên, chờ nó sẵn sàng rồi chạy lại. README nói chạy lại an toàn, key mã hoá không bị mất.
Trên Windows, lệnh bash không chạy trong PowerShell. curl ... | bash là cú pháp bash. Dùng Git Bash hoặc WSL, hoặc tốt hơn là tải bản .exe trong Releases như README gợi ý.
Không vào được http://localhost:3001. Kiểm tra container hoặc ứng dụng desktop đã chạy chưa, và xem bạn có đặt PORT khác không. Nếu cổng bị chiếm bởi chương trình khác, đổi PORT trong .env rồi chạy lại.
Lỗi 401 khi gọi API. Thường là dán nhầm key. Phải dùng unified key (freellmapi-…) của router, không phải key của Google hay Groq. Ngược lại, key của từng hãng chỉ dán vào trang Keys.
Gọi mãi vẫn lỗi hoặc chậm, nhiều lỗi 429. Gói miễn phí có trần thấp. Thêm key của nhiều hãng hơn để router có chỗ chuyển, dùng keys test để loại key hỏng, và xem trang thống kê trong bảng quản trị để biết hãng nào hay lỗi. Cần xem sâu hơn thì đọc tài liệu định tuyến trong thư mục docs/.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh nếu đã có Docker hoặc dùng bản desktop. Một endpoint cho rất nhiều công cụ. Tự chuyển hãng khi hết quota. Key mã hoá, chạy trên máy bạn, README cho biết máy chủ danh mục không thấy prompt hay key của bạn. Mã nguồn MIT, miễn phí.
Giới hạn cần biết. Mô tả của tác giả ghi rõ "Personal experimentation only", tức là dành cho thử nghiệm cá nhân. Chất lượng và độ ổn định phụ thuộc gói miễn phí, mà các hãng có thể đổi hạn mức hoặc gỡ model bất cứ lúc nào. Dự án thiết kế cho một người dùng, chạy local, không phải hệ thống phục vụ nhiều khách. Bạn cũng nên tự đọc điều khoản của từng hãng trước khi dùng dồn nhiều key.
Về bản trả phí. Router vẫn miễn phí. Có thêm gói Premium (README nêu 19 USD một năm hoặc 49 USD một lần) cho danh mục model cập nhật trong cùng ngày. Bản miễn phí vẫn nhận danh mục, nhưng chậm khoảng 30 ngày. Bạn không cần mua gì để bắt đầu.
Khi nào chọn cách khác. Nếu làm sản phẩm thật cho khách, cần cam kết độ ổn định hay chất lượng, hãy dùng API trả phí chính thức. Nếu chỉ cần một hãng, cứ dùng thẳng key của hãng đó cho đơn giản. Còn để thử nghiệm, học tập, làm công cụ cá nhân, FreeLLMAPI là cách gọn để dùng hết phần miễn phí đang có.
Câu hỏi thường gặp
FreeLLMAPI có miễn phí không?
Router mang giấy phép MIT và dùng miễn phí. Bạn dùng gói miễn phí của các hãng AI bằng key của chính bạn. Có thêm gói Premium tuỳ chọn cho danh mục model cập nhật trong ngày, README nêu giá 19 USD một năm hoặc 49 USD một lần. Bản miễn phí vẫn chạy đầy đủ, chỉ nhận model mới chậm hơn khoảng 30 ngày.
Có cần GPU không?
README không yêu cầu GPU. Các model chạy ở phía nhà cung cấp, còn router trên máy bạn dùng khoảng 40 MB RAM lúc rảnh. Nếu bạn tự trỏ vào model cục bộ như Ollama hay llama.cpp thì phần cứng cần thế nào là tuỳ model đó, README chưa nói.
Chạy được trên Windows không?
Được. README khuyên Windows dùng trình cài .exe trong trang Releases của repo. Cách cài một dòng bằng curl cần Docker và cú pháp bash, nên dùng Git Bash hoặc WSL. Bản macOS (.dmg) và chạy từ mã nguồn cũng có.
Key và dữ liệu của tôi có an toàn không?
Theo README, key của các hãng được mã hoá AES-256-GCM trong SQLite trên máy bạn và chỉ giải mã trong bộ nhớ khi xử lý yêu cầu. Máy chủ danh mục không thấy prompt, câu trả lời hay key. Yêu cầu của bạn vẫn đi tới các hãng AI mà bạn bật, nên dữ liệu nhạy cảm bạn cần cân nhắc theo chính sách của từng hãng.
Khác gì việc dùng trực tiếp API của từng hãng?
Bạn chỉ dùng một địa chỉ kiểu OpenAI và một key chung, thay vì tự xử lý nhiều SDK và nhiều giới hạn khác nhau. Router tự chọn model, tự chuyển hãng khi gặp lỗi 429 hoặc 5xx và theo dõi hạn mức từng key. Đổi lại bạn phải tự cài và tự giữ router chạy.
Dùng được với những công cụ nào?
README liệt kê Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, Roo Code, OpenCode, Aider và nhiều công cụ khác, cùng mọi client tương thích OpenAI, Anthropic, Gemini hoặc Ollama. Nhiều công cụ có lệnh tự cấu hình, ví dụ npx freellmapi setup-claude. Chi tiết từng công cụ nằm trong tài liệu thư mục docs.
Có dùng để làm sản phẩm cho khách hàng được không?
Mô tả của tác giả ghi rõ chỉ dành cho thử nghiệm cá nhân, và README nói dự án là local-first, dành cho một người dùng. Với dịch vụ cần độ ổn định hay cam kết chất lượng thì nên cân nhắc API trả phí chính thức. Về điều khoản của từng hãng, README đã cung cấp chưa nói chi tiết nên bạn cần tự đọc.


