flow2api: a Flow account pool behind an OpenAI and Gemini compatible API

The problem flow2api actually solves

Flow is a consumer product. Its interface is a web app, its sessions are tied to browser state, and its access tokens expire. If you want to call image or video generation from a script, a batch job or another tool, you are stuck reimplementing login, token refresh, captcha handling and per-account rate limits yourself.

flow2api packages that work into one service. The README describes it as "一个功能完整的 OpenAI 兼容 API 服务，为 Flow 提供统一的接口", an OpenAI compatible API service that gives Flow a unified interface. The repository layout matches that claim: a FastAPI application in src/, a config/ directory with setting.toml, a static/ directory for the admin and test pages, and tests/.

The intended user is someone holding more than one Flow account. The project description mentions an account pool ("逆向账号池") with load balancing, automatic AT refresh, caching and proxies. A single account would not need rotation or a 429 counter. The README also notes that Flow added an extra captcha, and points at a paid solving service, so the operator is expected to pay for captcha solving on top of whatever the accounts cost.

How the account pool, token refresh and load balancing fit together

The moving parts are visible in the README's monitoring section rather than in the code. GET /api/tokens returns per-token fields including at_expires, at_expired, at_expiring_within_1h, ban_reason and consecutive_error_count. That tells you the unit of state is the individual token, and the service tracks three things about each one: when it expires, whether it is banned, and how many errors it has produced in a row.

GET /health is the public summary. It reports whether the service is alive and how many tokens are active, close to expiry, already expired, or disabled by 429 responses. So the pool is not just a list. It is a scheduler with a health model: tokens move between active, expiring, expired and rate-limited states, and the counters feed that movement.

The README states that AT is refreshed automatically when it expires, and that in personal mode an expired ST is renewed through a browser. That is the failure path the whole design rests on. A short-lived access token is cheap to rotate; a session token that has gone stale needs a real browser session, which is why there is a headed Docker variant at all.

Load balancing is described as multi-token polling with concurrency control. The README does not document the selection algorithm, so whether it is strict round robin, weighted by remaining credits, or biased away from tokens with recent errors is not something the documentation answers. The balance display, which queries VideoFX Credits, suggests credits are at least visible to the operator even if the README does not say they drive routing.

Installing flow2api with Docker and making a first request

The README recommends Docker and Docker Compose. The default compose file pulls ghcr.io/thesmallhancat/flow2api:latest, maps host port 38000 to container port 8000, and mounts ./data, ./tmp and ./config/setting.toml. Note the port mismatch: the container listens on 8000, but the published address is 38000.

git clone https://github.com/TheSmallHanCat/flow2api.git
cd flow2api
docker-compose up -d
docker-compose logs -f

The README notes that Compose already mounts ./tmp:/app/tmp, and that a cache timeout of 0 means "do not expire automatically" rather than "disable caching". If you want cache files to survive a container rebuild, keep that mount.

Once the service is up, the admin UI is at http://localhost:8000 according to the README, with username admin and password admin, and the README tells you to change the password immediately after the first login. If you started the default compose file, remember that the port you reach from the host is 38000, not 8000.

The README lists GET /health as a public health check that returns whether the service is alive along with counts of active, soon-to-expire, expired and 429-disabled tokens. A fresh install with no tokens added should show nothing active, which is the expected state before you add accounts.

For a quick functional check, the README points at http://localhost:8000/test, a built-in model test page that lists models by category (image generation, text and image to video, multi-image video, video upscaling), lets you submit a prompt and streams progress, and accepts image uploads for image-to-image or image-to-video. That page is the shortest path from install to a generated file. For metrics, GET /metrics exposes Prometheus format, and the README suggests scraping it only inside a cluster and restricting external access to /metrics at the ingress or gateway layer.

The captcha dependency is the real operational cost

The README is unusually direct here: Flow added an extra captcha, and you choose between in-browser solving and a third-party solver. The recommended third-party option is YesCaptcha, whose API key goes into the YesCaptcha API密钥 field on the system configuration page. The README also lists capmonster, ezcaptcha and capsolver as compatible with the default docker-compose.yml.

The service exposes a type setting for YesCaptcha with four values: RecaptchaV3TaskProxyless, RecaptchaV3TaskProxylessM1, RecaptchaV3TaskProxylessM1S7 and RecaptchaV3TaskProxylessM1S9. The README says M1S9 is currently recommended, and that S7 and S9 force a minScore of 0.7 and 0.9 respectively. That is a score threshold passed to the solver, and it implies you are paying per solve attempt for a probabilistic result.

This is the part that decides whether flow2api is worth running. Every token refresh that hits a captcha becomes a paid API call to a third party. If solving fails, the token goes through the error path counted by consecutive_error_count and eventually shows up as disabled. The README does not document retry budgets, backoff, or what happens to a token that fails captcha repeatedly beyond the counters it exposes.

If you want in-browser solving instead, the README provides docker-compose.headed.yml, which starts Xvfb plus Fluxbox inside the container and sets ALLOW_DOCKER_HEADED_CAPTCHA=true. It says only the application port is exposed and no remote desktop port is provided. The README also notes that the personal browser mode now starts headed by default, and that PERSONAL_BROWSER_HEADLESS=true switches it back to headless temporarily.

Where flow2api is the wrong tool

The honest limitation is that this is an unofficial bridge to a consumer product. Nothing in the README describes a contract with Flow, and the repository has no releases listed, so there is no versioned upgrade path to follow. When Flow changes its captcha or its endpoints, the fix lands as a commit on main, and the documentation gives no changelog to tell you what broke. The README already records one such change (the added captcha), which is evidence that this class of breakage happens.

It is also a poor fit if you cannot supply accounts. The load balancer, the token pool and the 429 counters all assume multiple accounts exist. A single account turns the whole rotation layer into dead weight and leaves you with the captcha cost anyway.

Finally, flow2api is not a model. It does not train anything, and the model names it exposes are Flow's own, such as gemini-3.0-pro-image-landscape and the veo_3_1_t2v family. If your requirement is a stable, documented, supported image API with an uptime commitment, this is the wrong layer to build on. It is a way to reach models through accounts you already have, not a replacement for a commercial endpoint.

How it differs from a direct Gemini API integration

The obvious alternative is calling Google's Gemini API directly. The difference is not the model names, since flow2api deliberately mirrors Gemini's request shape: the README says it supports generateContent and streamGenerateContent, systemInstruction, and contents.parts.text, inlineData and fileData, and it claims /models/{model}:generateContent has been verified with a real token returning candidates[].content.parts[].inlineData.

So the choice is about the credential, not the payload. A direct integration uses an API key issued to you, with documented quotas and a published price list. flow2api uses Flow account sessions, rotated across a pool, with captcha solving billed separately and account state tracked by the service. You get the same request format and a different cost structure: no per-call API price, but accounts to maintain and a solver to pay.

The other difference is operational surface. A direct integration has no admin UI, no /health token summary and no /metrics to scrape, because there is no pool to watch. flow2api adds that surface precisely because the credential it uses is fragile. If your tokens never expire and never get rate limited, that surface is overhead.

The related searches for this project also surface Sora2api, Grok2api, Chatgpt2api and AIClient2API, which follow the same pattern of putting a consumer product behind a compatible API. The distinction between them is which upstream they wrap and which request format they imitate, not the architecture.

Maintenance, upgrades and what the MIT licence does not cover

The repository is not archived, and the last push was on 2026-09-22. There are no releases listed, so the practical upgrade path is pulling the image tag or pulling main and rebuilding. The default compose file uses ghcr.io/thesmallhancat/flow2api:latest, which means docker-compose pull followed by docker-compose up -d will move you to whatever was pushed most recently, with no version pin to roll back to. If you want reproducibility, pin a digest or build from a specific commit yourself.

Upgrade cost is dominated by state migration, not code. The compose file mounts ./data and ./config/setting.toml, so token state and configuration live outside the container and survive a rebuild. The README's warning about a cache timeout of 0 and the ./tmp mount is the one place where an upgrade can silently change behaviour: if you drop the tmp mount, cache files are lost on rebuild, and if you set the timeout to 0 expecting it to disable caching, you get the opposite.

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That covers the code in this repository. It does not cover Flow's terms of service, the accounts you point at it, or the captcha solving service you pay. Those are separate agreements, and the README does not discuss them. Treat the MIT grant as a statement about the source, not about the legality or stability of the upstream access path.

Editorial conclusion

Adopt flow2api if you already hold Flow accounts and want them behind one OpenAI compatible endpoint with rotation and a local admin UI; skip it if you have no accounts, no captcha solver, or want a supported commercial API with a service level agreement. Before pointing anything at it, open http://localhost:8000, change the admin password, set the captcha type, and check GET /health to confirm how many tokens are active and how many are already expired.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. TheSmallHanCat/flow2api on GitHub