www222fff/muse2api
www222fff/muse2api has 372 GitHub stars and 105 forks. GitHot measured +1 stars in 24 hours. Last checked 2026-11-17 02:07 UTC. Last push 2026-11-01.
Measured star growth
- in 24h
- +1
- in 7 days
- Update delayed
- in 15 days
- Update delayed
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
OpenAI-compatible async gateway for muse.ai with pluggable drivers (mock / browser-CDP / http)
Developer ToolsREADME.md
Originalmuse2api
English | 中文
An async gateway that exposes the muse.ai web app as an OpenAI-compatible API
Contents
- Overview
- Status
- Architecture
- Project layout
- Quick start
- API examples
- Configuration
- Roadmap
- Contributing
- Disclaimer
- Star History
Overview
muse2api turns muse.ai's chat, text-to-image and text-to-video features into standard OpenAI endpoints (/v1/chat/completions, /v1/images/generations, ...). Existing OpenAI SDKs and clients such as ChatGPT-Next-Web, LobeChat or Cherry Studio work by just changing their base_url.
The project focuses on clean engineering and easy collaboration:
- Pluggable drivers: how we reach upstream is abstracted behind a
MuseDriverinterface. There are currently a mock driver and a browser (CDP) driver, plus a reserved slot for a direct-protocol (HTTP) driver. They are fully independent of each other. - Strict layering: the protocol layer, service layer, account pool and drivers each have a single responsibility and can be developed and tested on their own.
- Fully async: built on FastAPI + asyncio; the CDP client uses
websockets, so no request ever blocks a thread. - Account pool: multiple scheduling strategies, per-account concurrency limits, cooldown after failures, automatic removal of expired sessions, and automatic failover to another account.
- Offline development: the mock driver needs no account and makes no network calls, so front-end and protocol work can move forward independently.
Status
Current: the mock-driver test suite passes locally (81 tests, no network access) and CI runs on every push to main; the browser driver and the direct-protocol driver still need live testing against a real muse.ai account.
| Module | Status | Notes |
|---|---|---|
| OpenAI protocol layer (chat streaming/non-streaming, images, videos, models) | ✅ Implemented | Multi-turn chat, system prompts, image input, model aliases |
| Account pool (scheduling / cooldown / invalidation / failover) | ✅ Implemented | lru, round_robin and affinity strategies |
| Background tasks (video) | ✅ Implemented | Create a task, then poll for the result; unfinished tasks are marked interrupted after a restart |
| Admin API (account CRUD, renewal, reset, status) | ✅ Implemented | Accepts cookie dicts, raw Cookie header strings and EditThisCookie JSON, plus bulk import via /admin/accounts/import; per-account quota snapshot at /admin/accounts/{id}/quota |
| Mock driver | ✅ Implemented | Offline fake data |
| Browser driver (Chromium + CDP) | 🧪 Needs live testing | Full chat, image and video flows are written |
| Session renewal / keepalive | 🧪 Needs live testing | Plain HTTP, on by default every 10 min; also wakes the account's VM so the first request is not slowed by a cold start |
| Direct HTTP protocol driver | 🚧 Reserved | Returns 501 |
/v1/images/edits (reference images) |
✅ Implemented | Images are references for a new image; mask is rejected |
/v1/responses |
🚧 Reserved | Returns 501 |
| Streaming heartbeats (SSE keepalive) | ✅ Implemented | Opt-in with MUSE2API_STREAM_HEARTBEAT_INTERVAL; sends : keepalive comments while waiting for the first token |
| Automatic media cleanup | ✅ Implemented | MUSE2API_MEDIA_RETENTION_DAYS (default 14, 0 disables); hourly background pruning |
| SSRF guard for server-side image fetches | ✅ Implemented | Private and loopback URLs are rejected |
| Web dashboard, request log, multiple API keys | ✅ Implemented | Dashboard at /dashboard; key CRUD at /admin/keys; per-request log and aggregates |
| Quota lookup | ✅ Implemented | Browser driver reads Settings → Usage (plan, weekly %, reset, extra allowance; en / zh-CN / zh-TW) on an idle tab, cached 30 min; mock driver returns a fake snapshot; http driver not wired up |
| VM wake confirmation | ✅ Implemented | After a wake (keepalive or /admin/accounts/{id}/renew) the session is polled until the VM is RUNNING; an account whose VM is seen down gets no video for 10 min |
| Cookie import browser extension | ✅ Implemented | MV3 popup in src/muse2api/web/extension/, downloadable from the dashboard |
| Storage backends (SQLite / Redis) | 🚧 Reserved | Accounts still use a JSON store; the request log is SQLite |
| Prometheus metrics | 🚧 Reserved | Basic aggregates exist at /admin/stats |
Architecture
flowchart TB
clients["OpenAI SDK / chat clients<br/>HTTP · Bearer key"]
subgraph api["api/ — protocol"]
api_routes["routes · validation · auth · SSE"]
end
subgraph services["services/"]
svc["Gateway (failover) · TaskManager"]
end
subgraph accounts["accounts/"]
acc["Account pool<br/>strategies · cooldown · renewal"]
end
subgraph core["core/"]
core_inner["Model aliases<br/>prompt conversion · media storage"]
end
subgraph drivers["drivers/ — MuseDriver interface (only layer that talks to upstream)"]
direction LR
d_mock["mock<br/>offline fake data"]
d_browser["browser<br/>Chromium + CDP"]
d_http["http<br/>direct protocol (reserved)"]
end
subgraph upstream["upstream/"]
u["muse.ai URLs · cookie names · session API"]
end
musedotai["muse.ai"]
clients --> api --> services
services --> accounts & core
accounts & core --> drivers
drivers --> upstream --> musedotai
How a chat request is handled: the route resolves the model alias and merges the multi-turn messages into a single prompt, then hands it to the Gateway. The Gateway leases an account from the pool and asks the driver for a text stream. On failure, the account's state is updated according to the error type: accounts with an expired session are taken offline, accounts out of quota cool down, and other errors cause a short cooldown. As long as nothing has been sent to the client yet, the request is retried on another account.
For streaming requests, the first chunk is fetched before returning 200. Errors such as "no account available" or "upstream authentication failed" therefore come back with a proper HTTP status code instead of a stream that breaks halfway.
See docs/ARCHITECTURE.md for the full design.
Project layout
muse2api/
├── src/muse2api/
│ ├── app.py # FastAPI app factory and lifespan
│ ├── config.py # Settings (environment variables / .env)
│ ├── errors.py # Error hierarchy → HTTP status + OpenAI error body
│ ├── api/
│ │ ├── deps.py # Auth and dependency injection
│ │ ├── schemas.py # OpenAI request models
│ │ └── routes/ # chat / images / videos / media / models / admin / responses
│ ├── services/
│ │ ├── gateway.py # Runs driver calls on pooled accounts, retries on another account
│ │ ├── tasks.py # Background long-running tasks
│ │ └── container.py # Service wiring
│ ├── accounts/ # Account model, JSON store, pool, session keepalive
│ ├── core/ # Model registry and aliases, prompt conversion, media storage
│ ├── drivers/
│ │ ├── base.py # MuseDriver interface and data types
│ │ ├── mock.py
│ │ ├── browser/ # cdp.py / chromium.py / dom.py / driver.py
│ │ └── http/ # Reserved
│ └── upstream/muse.py # Upstream constants and session renewal
├── tests/ # Mock-driver tests, no network access
├── docs/ARCHITECTURE.md
├── TODO.md # Task board for contributors
├── Dockerfile · docker-compose.yml · .env.example
└── CONTRIBUTING.md
Quick start
Run locally
git clone https://github.com/www222fff/muse2api.git
cd muse2api
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
cp .env.example .env # defaults to MUSE2API_DRIVER=mock, no account needed
python -m muse2api # listens on http://127.0.0.1:18610 by default
If MUSE2API_API_KEY is not set, a key is generated on first start and saved to data/api_key.
Docker
cp .env.example .env
docker compose up -d --build
Use a real account (browser driver)
- Install Chromium or Chrome and set
MUSE2API_DRIVER=browserin.env. - Export the cookies from a browser that is logged in to muse.ai. At least
hatch_sessandhatch_native_auth_deviceare required;hatch_gwandhatch_vmlare passed through when present. Import all muse.ai cookies, including__Host-ones. - Import the account through the Admin API (see the example below).
API examples
Every /v1/* endpoint requires the header Authorization: Bearer <API_KEY>. The /admin/* endpoints use MUSE2API_ADMIN_KEY, which defaults to the API key when unset.
Chat (streaming)
curl http://localhost:18610/v1/chat/completions \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}],"stream":true}'
OpenAI Python SDK
from openai import OpenAI
client = OpenAI(base_url="http://localhost:18610/v1", api_key="<API_KEY>")
resp = client.chat.completions.create(
model="muse-chat",
messages=[{"role": "user", "content": "Write a short poem about autumn"}],
)
print(resp.choices[0].message.content)
Multi-turn conversations
Chat is stateless by default: each request opens a new muse.ai thread and sends the full messages history, so clients never share a thread. Pass a stable user to keep one conversation on one thread; follow-ups then send only the new user turn, which is faster. The key is scoped by API key, so two keys sending the same user stay apart. Each account serves MUSE2API_ACCOUNT_MAX_CONCURRENCY conversations at once (default 4), one tab each, and keeps MUSE2API_WARM_THREADS started threads (default 2) so a new conversation answers in about 5s instead of 20-40s. Each muse.ai account runs on one cloud VM, and conversations on the same account slow each other down: measured on one account, one request at a time took about 5s, three at once about 20s each, and ten at once 33-95s with a timeout. More tabs per account do not help; for about 10 people use 3 or more accounts, which the pool spreads requests across.
Text to image
curl http://localhost:18610/v1/images/generations \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"prompt":"A cyberpunk street on a rainy night","size":"16:9","response_format":"url"}'
Transparent background
muse.ai only returns flat RGB images, so "background":"transparent" cuts the subject out locally (BiRefNet + edge colour estimation) and returns an RGBA PNG. Requires pip install -e '.[matting]'; the model (~930MB) is downloaded to ~/.u2net on first use. Expect ~30s extra per image on CPU.
curl http://localhost:18610/v1/images/generations \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"prompt":"A red fox sitting","background":"transparent"}'
Image from reference images
"image" takes one reference image or a list of up to 4 (data URL, http(s) URL or bare base64). They are attached to the muse.ai message like a chat upload, and the prompt says how to use them, e.g. put a product on a model, or "the same fox, now wearing a red scarf" to keep the subject and scene. /v1/images/edits does the same with OpenAI-style multipart uploads, so client.images.edit() works; mask (inpainting a region) is not supported.
curl http://localhost:18610/v1/images/generations \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"prompt":"A model wearing exactly this hoodie, studio photo","image":"data:image/jpeg;base64,..."}'
curl http://localhost:18610/v1/images/edits \
-H "Authorization: Bearer $KEY" \
-F "image[][email protected]" -F "prompt=The same fox, now wearing a red scarf"
Image as an async task
A sync image call (page load plus generation) can take longer than a reverse proxy allows; Cloudflare cuts it after about 100 s with HTTP 524. Add "async": true to get a task back, then poll it. Results are always stored as media URLs.
curl http://localhost:18610/v1/images/generations \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"prompt":"A red fox sitting","async":true}' # -> {"id":"task_xxx","object":"image.task",...}
curl http://localhost:18610/v1/images/generations/task_xxx -H "Authorization: Bearer $KEY"
Text to video (async task)
# Create a task; returns {"id": "task_xxx", "status": "queued", ...}
curl http://localhost:18610/v1/videos \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"prompt":"Maple leaves falling in a light breeze","duration":5,"size":"16:9"}'
# Poll the task; on success, result.url points to the video
curl http://localhost:18610/v1/videos/task_xxx -H "Authorization: Bearer $KEY"
Import an account
curl http://localhost:18610/admin/accounts \
-H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{"label":"acc1","cookies":{"hatch_sess":"...","hatch_native_auth_device":"..."}}'
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /healthz · /readyz |
Liveness · readiness (driver state and available accounts) |
| GET | /v1/models |
Model list, including aliases such as gpt-4o and dall-e-3 |
| POST | /v1/chat/completions |
Chat, streaming and non-streaming |
| POST | /v1/images/generations · GET /v1/images/generations/{id} |
Text to image (optional image references), returns url or b64_json; "async": true returns a task to poll |
| POST | /v1/images/edits |
Multipart image/image[] files + prompt, OpenAI-compatible |
| POST | /v1/videos · GET /v1/videos/{id} |
Create a video task · query a task |
| GET | /v1/media/{name} |
Download generated media |
| GET/POST/PATCH/DELETE | /admin/accounts[/{id}] |
Account CRUD |
| POST | /admin/accounts/import |
Bulk account import with per-entry error reporting |
| POST | /admin/accounts/{id}/renew · /reset |
Renew session · reset account state |
| GET | /admin/accounts/{id}/quota[?refresh=1] |
Quota snapshot (cached 30 min; refresh=1 reads it again; 409 account_busy when every tab is busy) |
| GET | /admin/extension.zip |
The cookie-import Chrome extension |
| GET | /admin/status · /admin/tasks |
Service status · task list |
| GET/POST/PATCH/DELETE | /admin/keys[/{id}] |
Client API keys (create returns the key once; PATCH renames / revokes) |
| GET | /admin/requests · /admin/stats?window=1h|24h|7d |
Request log (filters: key_id, account_id, status=2xx|4xx|5xx, path, since, hide_polls) · aggregates |
| GET | /dashboard |
Web dashboard (asks for the admin key in the browser) |
| POST | /v1/responses |
Reserved, currently returns 501 |
Dashboard, API keys and request log
Open http://localhost:18610/dashboard and enter the admin key; it is kept in the browser's local storage and sent as a Bearer token to /admin/*. The page shows request volume, error rate and latency, the account pool (enable/disable, renew, reset), a live request log, and API key management.

Each account card shows its quota (usage bar, plan, reset date, age of the reading, with a Quota button to read it again), when its session cookie expires, and whether its VM was confirmed running after the last wake. Import hàng loạt (bulk import) takes one label | cookie string per line.

Cookie-import extension
The muse.ai session cookies are httpOnly, so page scripts cannot read them; a small Chrome / Edge extension (Manifest V3, in src/muse2api/web/extension/) can.
- On the dashboard's Accounts page, click Tải extension (download extension). It downloads
muse2api-extension.zip, also served atGET /admin/extension.zip. Unzip it. - Open
chrome://extensions, turn on Developer mode and click Load unpacked on the unzipped folder. - Sign in to muse.ai in that browser.
- Open the extension popup, enter the gateway URL (e.g.
http://localhost:18610) and the admin key, optionally a label, and click import.
The extension reads the muse.ai cookies with their expiry and posts them to POST /admin/accounts. Its only fixed host permission is muse.ai; it asks for the gateway's origin when you save it, and never stores the cookies. See its README for details.
Besides the admin key and MUSE2API_API_KEY (still accepted, logged as legacy), /v1/* accepts any non-revoked key created on the dashboard or with POST /admin/keys {"name": "..."}. Keys look like m2a-... and are shown once; data/keys.json stores only their SHA-256 hash and an 8-character prefix. Every /v1/* request (except /v1/media/* downloads) is recorded in data/requests.db (SQLite) with its key, model, account, status, latency and client IP (CF-Connecting-IP / X-Forwarded-For aware). Task status polls are flagged so the dashboard and stats can leave them out.
Configuration
All settings come from environment variables (prefix MUSE2API_) or a .env file. See .env.example for the full list. The most common ones:
| Variable | Default | Description |
|---|---|---|
MUSE2API_DRIVER |
mock |
Driver: mock / browser / http |
MUSE2API_HOST · MUSE2API_PORT |
127.0.0.1 · 18610 |
Listen address and port |
MUSE2API_API_KEY |
auto-generated | Key for /v1/* endpoints |
MUSE2API_ADMIN_KEY |
same as API key | Key for /admin/* endpoints |
MUSE2API_REQUEST_LOG_RETENTION_DAYS |
14 |
Days of request history kept in data/requests.db |
MUSE2API_MEDIA_RETENTION_DAYS |
14 |
Days generated media files are kept in data/media; 0 disables automatic cleanup |
MUSE2API_STREAM_HEARTBEAT_INTERVAL |
0 |
SSE : keepalive comment interval (seconds) while waiting for the first stream token; 0 disables |
MUSE2API_PUBLIC_BASE |
empty | Public base URL used in media links; derived from the request when empty |
MUSE2API_POOL_STRATEGY |
lru |
Account scheduling: lru / round_robin / affinity |
MUSE2API_MAX_FAILOVER |
2 |
Maximum number of retries on another account |
MUSE2API_ACCOUNT_MAX_CONCURRENCY |
4 |
Parallel requests per account (browser driver: one tab each, about 300 MB of memory per tab) |
MUSE2API_WARM_THREADS |
2 |
Pre-started threads kept per account. A new muse.ai thread takes 20-40s to answer its first message, a started one about 5s, so chats that need a new thread go into a warm one. Each costs one extra short message of quota; needs a concurrency of at least 2 |
MUSE2API_CHROMIUM_PATH |
auto-detected | Path to the browser executable |
MUSE2API_KEEPALIVE_ENABLED |
true |
Periodically renew sessions and wake each account's VM in the background |
MUSE2API_KEEPALIVE_INTERVAL |
600 |
Seconds between keepalive rounds |
MUSE2API_WAKE_CONFIRM_S |
20 |
Seconds to wait for a woken VM to report RUNNING |
MUSE2API_QUOTA_CACHE_S |
1800 |
How long a quota reading is reused before muse.ai is asked again |
MUSE2API_MATTING_MODEL |
birefnet-general |
Model for background: "transparent" (birefnet-general-lite is faster) |
Roadmap
All reserved modules and outstanding work are tracked in TODO.md, in four groups:
- Verification and live testing (do first): get the tests passing, test the browser driver against real accounts, and verify image/video generation and session renewal.
- Drivers: direct HTTP protocol driver, conversation thread reuse, quota-aware scheduling.
- Protocol:
/v1/responses, mask-based inpainting, emulated tool calling. - Accounts, admin and operations: storage backends, per-key rate limits, Prometheus metrics.
Each task lists its location, approach and definition of done. Places marked TODO(contributors) in the code are the reserved extension points.
Contributing
You are welcome to pick up any task in TODO.md. Please open an issue describing what you plan to do before you start; see CONTRIBUTING.md for conventions.
pytest # all tests use the mock driver
ruff check . # lint
Disclaimer
This project is for learning and technical research only. Please comply with muse.ai's terms of service and local laws. Never commit or publish account cookies.