@fastcar/image-proxy

FastCar Koa based image API workbench with a local CORS proxy.

The browser page still lets you enter the upstream API Base URL and API Key. The server does not store either value. Requests go through /proxy, and the real upstream URL is passed in the X-Proxy-Target header.

Install

Run once with npx:

npx @fastcar/image-proxy

Or install globally:

npm install -g @fastcar/image-proxy
image-proxy

Open:

http://localhost:3000/

Usage Option 1: CLI

Start with the default port:

image-proxy

Use a custom port:

image-proxy --port 8080

Use a custom host:

image-proxy --host 127.0.0.1 --port 8080

Start with HTTPS and local certificate files:

image-proxy --https --port 3443 --key ./cert/key.pem --cert ./cert/cert.pem

Start with COS direct-upload signing enabled:

node dist/app.js \
  --port 3000 \
  --cos-domain "https://your-cos-service.example" \
  --cos-appid "your-appid" \
  --cos-secret-key "your-32-byte-secret" \
  --cos-upload-dir "/generated-images" \
  --cos-sign-mode 3 \
  --cos-sign-ttl-seconds 300

CLI options:

--port <number>   Server port. Default: 3000
--host <host>     Bind host. Default: 0.0.0.0
--https           Start an HTTPS server
--key <path>      HTTPS private key path, required with --https
--cert <path>     HTTPS certificate path, required with --https
--cos-domain <url>               COS service domain
--cos-appid <appid>              COS appid
--cos-secret-key <secret>        COS secret key
--cos-upload-dir <path>          COS upload directory. Default: /generated-images
--cos-sign-mode <number>         COS sign mode. Default: 3
--cos-sign-ttl-seconds <number>  COS sign TTL. Default: 300

Usage Option 2: PM2

Install dependencies and start as a background PM2 process:

npm install
npm run up

Stop:

npm run down

Other PM2 commands:

npm run pm2:status
npm run pm2:logs
npm run pm2:restart
npm run pm2:delete

To customize PM2 port or HTTPS, edit ecosystem.config.cjs:

env: {
  IMAGE_PROXY_PORT: "3443",
  IMAGE_PROXY_HOST: "0.0.0.0",
  IMAGE_PROXY_HTTPS: "1",
  IMAGE_PROXY_SSL_KEY: "D:/cert/key.pem",
  IMAGE_PROXY_SSL_CERT: "D:/cert/cert.pem",
}

Then restart:

npm run pm2:restart

How It Works

When the page is opened from the local server, API requests are sent to the same-origin proxy:

index.html -> /proxy -> upstream API

The frontend sends:

X-Proxy-Target: https://your-api.example/v1/images/generations
Authorization: Bearer <your-api-key>

The proxy forwards the request method, headers, body, and upstream response. This avoids browser CORS checks against the upstream API.

COS Upload

Generated result images are uploaded by the browser directly to COS. The local server only exposes /api/cos/sign, which returns a temporary read/write sign scoped to one generated object key under the configured upload directory. The browser never receives COS credentials.

Set these environment variables before starting the server, or pass the matching startup arguments shown above:

COS_DOMAIN=https://your-cos-service.example
COS_APPID=your-appid
COS_SECRET_KEY=your-32-byte-secret
COS_UPLOAD_DIR=/generated-images
COS_SIGN_TTL_SECONDS=300
COS_SIGN_MODE=3

COS_DOMAIN, COS_APPID, and COS_SECRET_KEY are required. COS_UPLOAD_DIR, COS_SIGN_TTL_SECONDS, and COS_SIGN_MODE are optional. The default sign mode is 3 (1 read + 2 write), scoped to the exact object key returned by /api/cos/sign.

Creator Layout

The workbench uses a prompt-first creator layout:

• Use the large prompt box and style chips for the main creative direction.
• Use "优化提示词" with a configured text reasoning provider/model to stream an improved prompt from the current text and reference images; click "采用优化" to overwrite the prompt box.
• Upload reference screenshots from the main card when you need image-to-image guidance.
• Open "高级设置" only when changing API profiles, models, size, quality, output format, or history limits.
• Keep "继续上一轮" enabled to merge previous successful generation records into the next prompt.
• Click "新建创作" to clear the current session context, prompt, references, and preview while keeping API settings and image history.
• Successful creations are saved as local sessions; the first-round prompt is used as the short session title.

Notes

• /proxy accepts absolute http or https target URLs only.
• The server does not persist the API Base URL or API Key.
• Do not expose this service publicly without authentication or network restrictions, because it is intentionally a full proxy.
• HTTPS only protects browser-to-proxy traffic; upstream API security still depends on the upstream endpoint.