free-one-api: An OpenAI-Format Gateway in Front of Reverse-Engineered LLM Libraries

The gap free-one-api fills between reverse-engineered clients and OpenAI-shaped code

Every reverse-engineered LLM client tends to invent its own calling convention. One library exposes a Python object, another a CLI, another an HTTP route with its own request schema. If you have application code, an SDK, or a tool that already speaks the OpenAI chat completions format, none of those clients can be dropped in without writing glue for each one. free-one-api exists to remove that glue. The repository describes itself as letting you access all reverse-engineered LLM libraries through the standard OpenAI API format, and the topic list names the specific targets: chatgpt, gpt4free, bard, claude, huggingchat, tongyiqianwen.

The audience is narrow and worth stating plainly. This is for people who have already decided to depend on unofficial endpoints and want to manage several of them from one place. It is not for teams that need an upstream with a support contract, and the README draws that line itself: if you want the official, paid APIs of those same models through a standard OpenAI interface, it points to songquanpeng/one-api instead, and notes that free-one-api can also be paired with one-api. That sentence is the clearest statement of scope in the whole document.

Channels, heartbeat checks and automatic disabling

The unit of configuration is the channel. A channel is one configured route to one reverse-engineered backend, and the screenshots in the repository show a channel list page and an add-channel form in the web UI. Multiple channels can point at the same or different libraries, which is what makes the load balancing feature meaningful: requests are spread across the channels you have enabled.

The mechanism that keeps this from silently rotting is the heartbeat check. The README lists a heartbeat detection mechanism and automatic disabling of unavailable channels as a feature. In practice this is the most defensible design decision in the project, because reverse-engineered endpoints fail in ways that official APIs do not: a site changes a header, a session token expires, a library's parsing breaks against new markup. Without periodic probing, a dead channel would keep absorbing a share of load-balanced traffic and produce intermittent failures that look like client bugs. Automatic disabling converts that into a channel that drops out of rotation.

What the supplied material does not describe is the probe interval, what a heartbeat request actually sends, how many consecutive failures trigger disabling, or whether a disabled channel is ever re-enabled automatically. Those are configuration questions you will have to answer from the deployment documentation rather than from the README.

Deployment surface: Docker image, web UI and a separate documentation site

The README does not inline installation steps. It links to two documentation locations: a GitHub Pages site at rockchinq.github.io/free-one-api and a self-hosted documentation site at free-one-api.rockchin.top, and states that deployment and configuration are covered there. It also publishes a Docker image, rockchin/free-one-api, which the README references through a Docker Hub badge and which is the most likely starting point for a self-hosted install.

Because the README does not reproduce the commands, this article cannot give you a verified docker run invocation or a verified set of configuration keys. What can be confirmed from the repository layout is that the project is Python, that it ships a web frontend under web/ (the logo asset lives at web/src/assets/logo.png), and that the UI covers at least channel listing and channel creation. The honest position is that the concrete install command and config keys live in the linked docs, and you should read them there rather than trust a reconstruction. The one deployment-adjacent fact worth flagging is the licence: AGPL-3.0, which is a copyleft licence with network-use provisions. If you plan to run a modified version as a service other people reach over a network, read the licence text and get your own advice. This article is not legal advice.

The adapter stability problem the maintainer states outright

The most important limitation is written by the project itself, in the contributor call near the top of the README. It says contributors are needed because there are too many adapters, that they are very unstable, and that one person cannot keep up, and it asks for help testing each adapter, finding new reverse-engineering libraries and submitting pull requests. That is not a marketing caveat. It is a statement that the adapter layer is the weak point and that it is understaffed.

This has a direct operational consequence. The value of the heartbeat and auto-disable features is proportional to how often adapters break, which means the project's own reliability tooling is compensating for a known rate of failure rather than preventing it. If you adopt free-one-api, budget for adapter maintenance as an ongoing cost, not a one-time setup. The release history also suggests a slow cadence: the newest release listed is v1.0.1 from April 2024, following v1.0.0 in March 2024 and a beta in February 2024. A long gap between the last release and the last repository push does not by itself prove abandonment, and the repository is not archived, but it does mean you should check whether the adapters you need have been touched recently before you build on them.

Where free-one-api is the wrong tool, and what one-api does differently

The README names the alternative directly. songquanpeng/one-api is the project to use when you want to reach the official, paid interfaces of these LLMs through an OpenAI-standard API. The difference is not a feature checklist, it is what sits at the far end of the pipe. one-api fronts credentialed, supported API accounts. free-one-api fronts reverse-engineered clients that impersonate or scrape consumer-facing services. That distinction drives everything else: one-api's failure modes are quota, billing and key rotation; free-one-api's failure modes are upstream changes, session expiry and adapter breakage.

There is also a licensing difference worth noting without over-reading it. one-api is a separate project with its own licence, and free-one-api is AGPL-3.0. If you are choosing between them for a hosted service, the licence terms are as much a part of the decision as the adapter list.

A third option is to skip the gateway entirely and call one reverse-engineered library directly. If you only ever use one backend and one application, free-one-api's channel abstraction, load balancing and UI are overhead you do not need. The gateway earns its place when you have several backends, several consumers, or a need to swap a dead channel without redeploying the caller.

Who should adopt free-one-api, and what to check first

Adopt it if you are already running reverse-engineered LLM clients and want them behind one OpenAI-shaped endpoint, with a web UI for channel management and automatic removal of channels that stop responding. The combination of load balancing, streaming support and heartbeat-based disabling is a reasonable answer to a genuinely messy problem, and pairing it with one-api as the README suggests is a coherent way to mix unofficial and official routes behind one interface.

Do not adopt it if your application needs a stable upstream, if you cannot absorb adapter breakage, or if your use case is really about official paid APIs, which the project itself redirects to one-api. Also think twice if AGPL-3.0 obligations are incompatible with how you intend to distribute or host the software.

What to verify before you commit, concretely: open the deployment documentation at free-one-api.rockchin.top or rockchinq.github.io/free-one-api and confirm the current install path and configuration keys, since the README does not state them. Then check the adapter you actually need. The README's own contributor call says adapters are numerous and unstable, so the question is not whether free-one-api works in general but whether the specific channel you plan to run has been tested against the current state of its upstream. If it has not, treat the heartbeat and auto-disable behaviour as your safety net and expect to maintain the adapter yourself.

Editorial conclusion

Adopt free-one-api if you are already running one or more reverse-engineered LLM clients and want a single OpenAI-shaped endpoint, a web UI and automatic channel disabling in front of them, and if AGPL-3.0 fits how you deploy the service. Do not adopt it if you need a supported upstream, contractual stability, or a path to paid official APIs, because the project itself points that use case at songquanpeng/one-api. Before committing, verify which adapters still work against the current upstream sites, because the README states that adapters are numerous and unstable and that the maintainer is looking for contributors to test them.

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. RockChinQ/free-one-api on GitHub