Async GPU Job Queue — a free slice

Queue → worker → poll → serve: the async backbone of a self-hosted AI image app. Runnable on your laptop in two minutes — zero infrastructure.

You can't call a 20-second GPU job straight from a web request — it times out. This slice is the pattern that fixes it: queue the job, let a worker run it, poll until it's done, serve the result. It runs on your laptop with zero infrastructure (SQLite + a stub worker) — no GPU, no API key, no cloud.

_{Same character, three scenes — output of the full kit's 2-stage engine. This slice ships the transport around that engine.}

What this is (and isn't)

	This free slice	The full kit
Async queue → worker → poll → serve	✅ real, runnable	✅
RunPod serverless dispatch	📖 code you can read (src/lib/runpod.ts)	✅ real GPU
Worker	🔌 stub (placeholder image)	✅ 2-stage pipeline
2-stage character consistency (Z-Image → Qwen-Image-Edit)	concept only	✅ full engine
Database / storage	SQLite / local files	Postgres / GCS
Runs with zero infra	✅	needs cloud setup

The engine — building a 2-stage prompt, casting one base face, then editing from that base so the same character holds across scenes — is the paid part. This slice is the transport around it, in full, so you can read exactly how a GPU app stays deployable.

Quickstart (zero infra)

npm install
cp .env.example .env          # DATABASE_URL is a local SQLite file
npx prisma db push            # create the SQLite schema
npm run dev                   # http://localhost:3000

Type a prompt → Generate. Watch it go queued → processing → completed while the request itself returned instantly. The result is a stub placeholder; watch the terminal for the worker's completion log.

How it flows

flowchart LR
    A[Browser] -->|POST /api/generate| B[Create Job row<br/>status=queued]
    B --> C[Hand to worker<br/>return job id immediately]
    C -.->|full kit| D[RunPod serverless GPU]
    C -->|this slice| E[Stub worker<br/>renders placeholder]
    E --> F[Write result to storage<br/>status=completed]
    A -->|GET /api/status/:id<br/>poll| F

Loading

Read these four files in order — that's the whole pattern:

1. src/app/api/generate/route.ts — queue the job, return immediately.
2. src/lib/runpod.ts — how the full kit dispatches to real serverless GPU.
3. src/lib/worker.ts — the stub standing in for that GPU worker.
4. src/app/api/status/[jobId]/route.ts — the poll the client waits on.

The full kit

This slice is the transport. The full kit is the product around it:

• The 2-stage consistency engine — a text-to-image model casts one base face, then an image-edit model re-scenes from that base as the reference. Same character, any scene — people, anime, animals, robots. Not a seed trick.
• Real GPU deploy — the runpod.ts you just read, live: RunPod serverless (scale-to-zero) plus the IaC scripts that build templates and endpoints.
• Cost & margin optimization — slim runtime image, model baked into the container, cold-start tuning. The chapter that keeps a GPU app from quietly losing money.
• A full app, not a demo — character wizard, gallery, Google login, credits + Stripe subscriptions, mobile-first UI, Cloud Run deploy.
• A written, AI-first course — each lesson is a paste-ready instruction for an AI coding agent (Claude Code, Cursor). The agent writes the code; you review and ship.

→ Own the stack. Keep the margin. — ownstackhq.com $249 one-time (founding price, first 50 builders) · lifetime kit updates · no subscription.

License

MIT — for this slice. Use the queue pattern however you like.