james-6-23/codex2api

Codex2API – an OpenAI‑compatible gateway for pooled Codex accounts

What it is – Codex2API is a self‑hosted service that turns a collection of Codex (OpenAI‑style) refresh‑token or access‑token accounts into a single, production‑ready API endpoint. It speaks the same OpenAI/Anthropic HTTP routes (/v1/chat/completions, /v1/images/..., /v1/models, etc.) while handling token refresh, health scoring, dynamic concurrency, rate‑limit recovery, usage‑based billing, and admin operations.

Why it matters – Many developers obtain multiple personal Codex accounts to bypass quota limits. Managing those tokens manually is error‑prone and insecure. Codex2API automates the pool, schedules requests to the healthiest accounts, and presents a unified, OpenAI‑compatible interface that any client (Codex CLI, Claude Code, the official OpenAI SDK, etc.) can call.

---

Core capabilities

Capability	What you get
Unified OpenAI‑style API	Endpoints for chat completions, responses, image/video generation, model listing, health check – all under /v1/*.
Account‑pool scheduler	Accounts are selected by health tier, concurrency limits, cooldown, recent usage; supports round_robin and remaining_quota strategies.
Admin dashboard	React + Vite UI for importing tokens, testing accounts, managing API keys, proxy pools, prompt filters, usage analytics, and system settings.
Two deployment shapes	Production mode: PostgreSQL + Redis; Lightweight mode: SQLite + in‑memory cache (single‑container).
Billing & observability	Per‑account USD cost tracking (5 h / 7 d windows), credit‑quota flags, API‑key usage logs, trend charts, and request logs.
OAuth PKCE flow	Built‑in endpoints to acquire refresh tokens via the standard OAuth PKCE exchange, avoiding manual token extraction.
Docker‑ready	Official docker‑compose.yml for production, plus variants for local source builds and SQLite‑only deployments.

---

Quick start (Docker, production mode)

# clone & enter repo
git clone https://github.com/james-6-23/codex2api.git && cd codex2api

# copy env template and edit if needed
cp .env.example .env   # set DB passwords, ADMIN_SECRET, etc.

# pull images and start the stack
docker compose pull
docker compose up -d

# watch logs
docker compose logs -f codex2api

The admin UI will be reachable at http://localhost:8080/admin/ (protected by the ADMIN_SECRET you set).

For a single‑node setup without PostgreSQL/Redis, use the SQLite compose files:

cp .env.sqlite.example .env
docker compose -f docker-compose.sqlite.yml up -d

---

How to use the API

All endpoints follow the OpenAI specification, so existing SDKs work out‑of‑the‑box. Example for chat completions:

curl https://your-host/v1/chat/completions \
  -H "Authorization: Bearer <your‑public‑api‑key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"Hello"}]}'

If no public API key is configured, the gateway skips key verification.

---

Administration

• Token import – POST /api/admin/accounts (refresh token) or /api/admin/accounts/at (access token). Supports single or batch (newline‑separated) uploads.
• File import – multipart /api/admin/accounts/import for TXT or JSON token files.
• OAuth PKCE – generate an auth URL, complete the flow in a browser, then exchange the code via /api/admin/oauth/exchange-code.
• API keys – create per‑client keys under /admin/api-keys; keys are stored in the DB and can be revoked.
• Scheduler settings – adjust SchedulerMode, MaxConcurrency, GlobalRPM, etc. via the Settings page; changes propagate to all running instances.

---

Observability & billing

• Dashboard shows request volume, latency, token health, and model usage.
• Cost tracking per account (USD) uses a 5‑hour / 7‑day sliding window; credit‑quota flags let you cap spend.
• Redis cache (or in‑memory fallback) stores recent response contexts to support continuation calls (previous_response_id).

---

When to choose which deployment

Situation	Recommended mode
Production service with many accounts, need persistence, horizontal scaling	PostgreSQL + Redis (standard compose)
Small personal use, quick test, or CI pipeline	SQLite + in‑memory (sqlite compose)
Want to modify the Go backend or React UI	Use the docker-compose.local.yml (or docker-compose.sqlite.local.yml) to build from source

---

Community & support

• Issues & contributions – see docs/CONTRIBUTING.md for PR workflow.
• Demo – a public demo is hosted at https://codex2api‑latest‑vu8j.onrender.com (password: codex2api). Use it only to explore the UI; never upload real tokens.
• Sponsors – FastAIToken, AiXor, and 星辰·AI are listed as sponsors; they provide commercial AI‑API gateway services.

---

License & disclaimer

The repository is released under the MIT license. The authors warn that the demo should not be used with real credentials and that operating a token‑pool gateway may violate the terms of service of the underlying providers.

---

Bottom line – Codex2API gives you a fully‑featured, Docker‑ready gateway that aggregates many Codex accounts, presents a standard OpenAI‑compatible API, and supplies a rich admin UI for token management, billing, and observability. It is suitable for teams that need higher throughput or want to centralise token handling without writing their own scheduler.