image2api/README.en.md

image2api

Multi-provider AI image / video generation gateway — one OpenAI-compatible API, seven platforms aggregated, a ready-to-run operations system

_{Live instance (brand): Vivid AI · vividai.run}

简体中文 | English

Live Demo · Features · Deploy · API · Community

---

📖 Table of Contents

• Overview
• Screenshots
• Features
• Supported Models / Providers
• OpenAI-Compatible API
• Deployment
• Tech Stack
• Repository Layout
• Roadmap
• Community / Contact
• License

✨ Overview

image2api wraps the image / video capabilities of Adobe Firefly, OpenAI, Runway, Grok, Leonardo, Krea and Imagine into a single OpenAI-compatible API. Behind it, multi-account pools are scheduled automatically — out of quota → switch account, auth expired → refresh or kill, transient errors → retry, tokens proactively renewed before they expire — to deliver a stable service.

It's more than an API proxy: it ships with credit billing, CDK top-ups, referral rewards, a user system, an admin console, and a modern generation frontend, so a single command turns it into a fully operational AI generation site — the author's live instance Vivid AI · vividai.run (brand) is built on this project.

💡 Both frontend and backend are fully open-source (MIT) — Go + Vue 3, free to fork and self-host.

At a glance 🔌 OpenAI-compatible · 🤖 7 platforms, 10+ models · 🔁 auto failover / token keep-alive · 💳 credits + agent pricing · 🎨 generation frontend + admin console · 🐳 one-command deploy + auto HTTPS

🖼️ Screenshots

Playground	Dashboard
Accounts	Logs

🚀 Features

🎨 Generation

• Images + videos in one place, with image-to-image / reference frames (first frame, last frame, style reference)
• Multiple resolutions (1K / 2K / 4K), aspect ratios and video durations — configured and priced per model
• 7 providers, 10+ models, enable / disable / re-price from the admin console, no code changes

🔌 OpenAI Compatible

• Text-to-image /v1/images/generations · image-to-image /v1/images/edits (multipart ref upload) · video /v1/videos (Sora-style async: create → poll → /content) · /v1/models
• Strict OpenAI params: size sets the aspect ratio, quality the resolution tier — just swap base_url + api_key into an existing OpenAI SDK
• Image results returned inline as base64 — nothing stored server-side, privacy-friendly

🔁 Account Pools + Smart Failover

• Round-robin scheduling across the pool; one bad account doesn't break the whole
• Out of quota → switch · auth expired → refresh & retry / kill · transient → retry same account ×3 · bad params → fail fast
• Pre-deducted credits: atomic debit before generation, auto-refunded on failure, no over-spend under concurrency

🔐 Automatic Token Keep-alive

• Single-use rotating tokens (Krea / Imagine) are renewed proactively 10 minutes before expiry; new tokens persisted automatically
• Adobe cookies exchanged for fresh tokens on a schedule; bare JWTs killed on expiry
• Daily quota recovered at each provider's reset time, then re-probed for the real balance

💳 Billing & Operations

• Credit-based (pre-deduct + refund on failure), priced per model / resolution / duration
• Agent pricing: a user can be set as an "agent" role and models can carry agent prices; agent users (including their API key calls) are billed at the agent price, falling back to the normal price when unset
• CDK redeem codes · referral rewards · email sign-up / verification code / password reset
• Three roles: regular user / agent / admin (single)

🖥️ User Frontend (Vue 3)

• Playground · creations gallery · generation logs (with failure reasons / source tags)
• API docs · API key management · referral · about, light / dark theme

🛠️ Admin Console

• Overview dashboard (trends / DAU / top failures / top spenders)
• Model management (normal + agent price) · account management (bulk import / dedup / quota) · site-wide logs · user management (set as agent) · CDK · showcase · site config

🧰 Engineering highlights: tls-client (Chrome JA3/JA4 fingerprint) reliably passes Cloudflare · media stored in S3/RustFS, served through an authenticated proxy with retention cleanup · self-healing maintenance loop (quota recovery / credential refresh / orphan-job cleanup with refunds) · one-command Docker deploy with acme.sh auto HTTPS.

🤖 Supported Models / Providers

Provider	Models (examples)	Type
Adobe Firefly	firefly-image-5 · firefly-gpt-image-2 · flux-kontext-max · firefly-video · firefly-ray · gemini-veo31	Image / Video
OpenAI	gpt-image-2	Image
Runway	runway-gen4-turbo · nano-banana-2 (Nano Banana 2)	Video / Image
Grok (grok.com)	grok-video (imagine text/image-to-video)	Video
Leonardo.ai	seedream-4.5	Image
Krea.ai	flux-klein-2	Image
Imagine.art	imagine-1.5 · imagine-1.5pro	Image

Models are enabled and priced dynamically from the admin console — add or remove anytime.

🔌 OpenAI-Compatible API

# Text-to-image — pure OpenAI params: size→aspect ratio, quality→tier (low/medium/high→1K/2K/4K)
curl https://your-domain/v1/images/generations \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a cute cat on a desk, studio lighting",
    "size": "1024x1024",
    "quality": "high"
  }'

# Image-to-image — multipart reference upload (multiple via image[])
curl https://your-domain/v1/images/edits \
  -H "Authorization: Bearer sk-xxxx" \
  -F model="seedream-4.5" -F prompt="make it cyberpunk" -F image=@input.png

Images return OpenAI-style { "created": ..., "data": [{ "b64_json": "..." }] } (raw base64, no data: prefix, nothing stored server-side). Video is async: POST /v1/videos → poll GET /v1/videos/{id} until completed → GET /v1/videos/{id}/content for the mp4. Full parameters are documented on the in-app /docs page.

🚀 Deployment

Both frontend and backend are open-source. Docker one-command is recommended; you can also build from source with Go 1.26+.

Prerequisite: a domain A-record pointing to this host, with ports 80 / 443 open to the internet (required for Let's Encrypt verification).

Option 1: Docker, one command (recommended)

Requires Docker + Docker Compose. A single command brings up Postgres + Redis + RustFS + backend + frontend, and auto-issues / renews the HTTPS certificate (built-in acme.sh).

cp .env.docker.example .env   # fill in DOMAIN / ACME_EMAIL / POSTGRES_PASSWORD / S3_SECRET_KEY
sh install.sh                 # = docker compose up -d --build

Open https://<your-domain>/; watch cert progress with docker compose logs -f acme. With DOMAIN=localhost a self-signed cert is used (local testing).

Option 2: Manual install — bring your own PostgreSQL / Redis / RustFS / Nginx (click to expand)

Provide your own PostgreSQL · Redis · RustFS (or any S3) · Nginx, Go 1.26+ for the backend and Node 18+ for the frontend.

# 1. Create an empty database (the backend auto-migrates on start)
createdb vivid_ai

# 2. Configure and build the backend from source
cat > backend/.env <<'EOF'
APP_ENV=production
HTTP_ADDR=127.0.0.1:6666
POSTGRES_DSN=host=127.0.0.1 user=postgres password=YOUR_PASSWORD dbname=vivid_ai port=5432 sslmode=disable TimeZone=Asia/Shanghai
REDIS_ADDR=127.0.0.1:6379
RUSTFS_ENDPOINT=http://127.0.0.1:9000
RUSTFS_BUCKET=vivid-ai
RUSTFS_ACCESS_KEY=YOUR_AK
RUSTFS_SECRET_KEY=YOUR_SK
CORS_ORIGINS=https://your-domain
COOKIE_SECURE=true
EOF
cd backend && go build -o bin/api ./cmd/api && ./bin/api   # listens on 127.0.0.1:6666

# 3. Build the frontend (output in frontend/dist)
cd frontend && npm install && npm run build

Nginx reverse proxy (issue the certificate yourself with certbot / acme.sh):

server {
    listen 443 ssl;
    server_name your-domain;
    ssl_certificate     /path/fullchain.pem;
    ssl_certificate_key /path/privkey.pem;
    root /path/to/frontend/dist;
    index index.html;
    client_max_body_size 50m;
    proxy_read_timeout 600s;            # video generation can take a while

    location /assets/ { expires 1y; add_header Cache-Control "public, max-age=31536000, immutable"; }
    location / { try_files $uri $uri/ /index.html; add_header Cache-Control "no-cache"; }
    location ^~ /admin/api/ { proxy_pass http://127.0.0.1:6666; }
    location ^~ /images/    { proxy_pass http://127.0.0.1:6666; }
    location = /health      { proxy_pass http://127.0.0.1:6666; }
    location ^~ /v1/        { proxy_pass http://127.0.0.1:6666; add_header Cache-Control "no-store" always; }
}

See backend/.env.example for the full set of environment variables.

🧱 Tech Stack

Layer	Technology
Backend	Go · gin · gorm (PostgreSQL) · go-redis · tls-client (Chrome fingerprint)
Frontend	Vue 3 · Vue Router · Vite · Tailwind CSS v4
Infrastructure	PostgreSQL · Redis · RustFS (S3-compatible) · Nginx · acme.sh

📦 Repository Layout

backend/                       Backend source (Go)
├── cmd/
│   ├── api/                   Service entry point (main)
│   └── marklabel/             Ops helper (mark accounts on demand)
├── internal/
│   ├── bootstrap/             App wiring, scheduled maintenance startup
│   ├── config/                Env-var configuration loading
│   ├── http/
│   │   ├── handler/           HTTP handlers (v1-compatible API, admin, auth…)
│   │   ├── middleware/        Auth / request-id middleware
│   │   └── router/            Route registration
│   ├── model/                 GORM data models
│   ├── provider/              Upstream provider clients
│   │   ├── adobe/             Adobe Firefly (tls-client fingerprint)
│   │   ├── chatgpt/           OpenAI (incl. PoW / turnstile)
│   │   ├── runway/            Runway video + Nano Banana image
│   │   ├── grok/              Grok (grok.com, spoofed statsig, video)
│   │   ├── leonardo/          Leonardo
│   │   ├── krea/              Krea
│   │   └── imagine/           Imagine.art
│   ├── repo/                  Data-access layer (users / models / accounts / logs / CDK…)
│   ├── service/               Business logic (scheduling, billing, account pools, keep-alive, maintenance)
│   └── storage/               RustFS / S3 media storage
├── Dockerfile                 Multi-stage build (compile source → slim runtime image)
└── .env.example               Backend env-var template

frontend/                      Frontend source (Vue 3 + Vite)
├── src/
│   ├── views/                 Pages (playground / accounts / models / logs / overview / users…)
│   ├── components/            Reusable components (modals / selectors / lightbox…)
│   ├── layouts/               Public / admin layouts
│   ├── utils/                 Utility functions
│   └── api.js · auth.js …     API client, auth, theme, credits, etc.
├── Dockerfile                 Nginx static hosting + cert watcher
└── default.conf.template      Nginx site template (reverse proxy + caching)

docker-compose.yml             Docker orchestration (Postgres / Redis / RustFS / backend / frontend / acme)
install.sh                     One-command deploy script (= docker compose up -d --build)
.env.docker.example            Deployment env-var template

🗺️ Roadmap

• More upstream providers
• Usage analytics / export
• Multi-language UI (i18n)
• Webhook / async callbacks

💬 Community / Contact

🌐 Website	vividai.run
👥 QQ Group	1106849765 · Join
🐧 QQ	1114639355 · Add
🛒 Shop	pay.ldxp.cn/shop/chiyi
✉️ Email	vividairun@gmail.com

⭐ Star History

If you find this useful, give it a ⭐ — uncomment the line above after creating the repo to show the Star History chart.

📄 License

This project (frontend + backend) is open-source under the MIT license — free to use, modify, commercialize and redistribute.

If this project helps you, a ⭐ Star is much appreciated!