Nine engines · 11 guided categories · 1,427 prompts · a scorer that grades a shot before you pay for it
Editorial holo aesthetic — a WebGL cloud of real outputs floating in 3D space behind the headline.
Holo card cloud · Iridescent rim shader · Cobalt + paper · Zero blank-box anxiety
🚀 Try the Live Demo · Report Bug · Request Feature
The Field |
Pick the Engine |
Guided Wizard |
9engines — 2 image, 7 video ·11guided categories ·1,427prompts ·374credited creators ·460tests /6,530assertions ·0anytypesReproduce every figure:
bun testfor the tests and assertions;bun -e "const c=await import('./web/src/lib/categories.ts');console.log(new Set([...c.wizardCategories,...c.videoCategories].map(x=>x.id)).size)"for the categories;jq 'length' web/public/data/image-prompts.json web/public/data/video-prompts.jsonfor the prompt count (1,377 image + 50 video).
- Quick Start
- How It Works
- Why This Exists
- Two Platforms, One Pipeline
- Features
- Tech Stack
- Getting Started
- Architecture
- Testing
- Engineering Highlights
- Design Philosophy
- Privacy & Security
- Data Pipeline
- Documentation
- Contributing
# Web app (no API key needed — free tier included)
git clone https://github.com/DareDev256/Ultimate-Image-Video-Prompt-Generator.git
cd Ultimate-Image-Video-Prompt-Generator/web && npm install && npm run dev
# CLI tool
cd Ultimate-Image-Video-Prompt-Generator && bun install && bun run index.tsOpen localhost:3000 and start generating — the free tier gives you 25 Nano Banana Pro generations per day, no key required.
╭──────────────╮ ╭──────────────────╮ ╭───────────────────╮
│ ① CHOOSE │ │ ② BUILD │ │ ③ GENERATE │
│ │ │ │ │ │
│ Nano Banana │ ───▸ │ 11 categories │ ───▸ │ One click → │
│ GPT-Image-2 │ │ with curated │ │ assembled prompt │
│ Kling video │ │ suggestions │ │ hits the API │
╰──────────────╯ ╰──────────────────╯ ╰───────────────────╯
💡 Quick Mode — Describe your idea in one sentence and let AI expand it into a full 11-category prompt automatically. Skip the wizard entirely.
Most AI image tools give you a blank text box and wish you luck.
This project replaces the blank box with guided prompt engineering — 11 categories in the web wizard, 13 in the CLI (subject, setting, style, lighting, camera…) with curated suggestions per field, assembled into the exact format your chosen model expects. The result: prompts that are 10× more detailed than freehand, produced in a fraction of the time.
Structured enough to guide you. Flexible enough to not constrain you.
- Diversity-aware randomization — a sliding-window exclusion algorithm (not naive
Math.random()) ensures the "randomize" button always surfaces fresh suggestions. Algorithm deep-dive → - Model-aware output — the same wizard produces structured JSON for Gemini or natural language for GPT-Image-2/Kling, automatically adapting to what each model expects
- Composable architecture — 13 pure section generators (CLI) composed via
flatMap. Adding a new prompt category is one function + one array entry, zero touch points elsewhere - Actually tested — 460 tests prove invariants like "NL and JSON generators stay in sync on the same input" and "the randomizer never deadlocks regardless of pool size"
A step-by-step guided experience with theatrical animations, particle effects, and a neon UI. Choose your model, walk through 9 categories for image or 8 for video, preview your assembled prompt, and generate — all in the browser.
An interactive terminal interface for rapid prompt building with presets, templates, favorites, and image-to-prompt reverse engineering. Built on Bun with @clack/prompts.
bun run index.ts # Interactive wizard
bun run index.ts --analyze photo.png # Reverse-engineer a prompt from an image
bun run index.ts --template "Subway Flash" # Start from a built-in template
bun run index.ts --preset fashion # Use a category pack
bun run index.ts --favorites list # Manage favorite suggestions- 11 guided categories in the web wizard — Subject, Setting, Style, Lighting, Camera and Mood are shared. Image models add Color, Film Look and Vibes for a 9-step run; video models add Motion and Duration for an 8-step run. Eleven distinct categories across the two paths. (The CLI runs its own deeper 13-category schema — see Architecture.)
- Curated suggestions per field (8-10 hyper-specific options like "six thick rope braids radiating outward from skull")
- Quick Mode — describe your idea in plain English, AI expands to full structured prompt
- Diversity-aware Randomize — sliding-window exclusion algorithm tracks recent picks per field so consecutive clicks always surface fresh suggestions (see algorithm detail)
- Keyboard navigation with smart focus detection
Every other prompt tool hands you text and lets you discover whether it was any good by buying a render. This one grades it first.
Six axes, 0–5 each, out of 30 — Subject · Setting · Light · Camera · Grade · Mood. Each maps back to the wizard steps that raise it, so the score is not a grade, it is an instruction to go back to a specific step.
bun run skill/scripts/score.ts "a cat, 8k masterpiece"0/30 FLAT
The model is making most of this up. Expect a generic result.
SUBJECT ████· 4/5 ← cat
SETTING ····· 0/5
LIGHT ····· 0/5
CAMERA ····· 0/5
GRADE ····· 0/5
MOOD ····· 0/5
-2 Too short — Under 25 characters. There is no room for a shot in there.
-2 Empty tokens — 8k, masterpiece — these read as effort and steer nothing.
NEXT: SETTING
Say where this happens. A room, a street, a void — but somewhere.
Wizard steps that fix it: setting, style
The vocabulary is generated, not guessed. 598 terms, part seeded from the pattern dictionary and part mined from the 1,070 Latin-script prompts in the corpus, each weighted by log frequency so a common term outranks a rare one without swamping it. When no term matches, a broad category marker sets a floor of 2 rather than reporting zero — a prompt can specify its setting in words nobody happened to mine, and telling someone to fix the one thing they did is worse than saying nothing.
Calibrated against the corpus it grades, because a scorer that cannot separate known-good prompts from junk is not measuring anything: 85% of the 1,070 known-good prompts score workable or better (median 22/30), while every junk string in the test suite tops out at 2/30.
Empty tokens (8k, masterpiece, trending on artstation) are penalised —
capped, because five of them is the same mistake made five times, not five
mistakes. A negative prompt is rewarded, because most people skip it.
The six-axis, 0–5, four-tier shape is lifted from the COSTAR engine in prompt-craft. The axes are not: COSTAR grades text prompts, where "write a formal summary in bullet points" is excellent and describes no shot at all.
skill/ ships a Claude Code skill so an agent can search the corpus, score a
draft, and pick an engine without a browser:
ln -s "$PWD/skill" ~/.claude/skills/shot-grammarSearch returns each prompt with its author and upstream repo attached — these were written by named people, and two of the source repos carry licence terms that require the attribution to travel with the text.
Pick a model and every wizard step adapts to it. Source of truth: web/src/lib/models.ts.
Image
| Model | Free Tier | Notes |
|---|---|---|
| Nano Banana Pro (Google · Gemini 3 Pro) | ✅ 25/day | World-knowledge grounded, text-in-image SOTA, up to 4K |
| GPT-Image-2 (OpenAI) | BYOK only | Replaces DALL-E 3 — broke the arena leaderboard by 242 pts |
Video — proprietary
| Model | Notes |
|---|---|
| Seedance 2.0 (ByteDance · via fal.ai) | $0.022/sec Fast tier, multi-shot from one prompt, phoneme-level lip-sync |
| Veo 3.1 (Google DeepMind · via fal.ai) | Native 4K@60fps, synced audio, best dialogue clarity |
| Kling 3.0 (Kuaishou) | Multi-shot 3–15s, subject continuity, multi-character audio |
Video — open-source
| Model | Notes |
|---|---|
| Wan 2.6 (Alibaba · via fal.ai) | MoE architecture, ~$0.05/sec, 720p |
| HunyuanVideo (Tencent · via fal.ai) | 13B, prosumer-runnable, stable text alignment |
| LTX-Video 2.0 (Lightricks · via fal.ai) | Cheapest hosted at ~$0.04/sec, 1080p–4K |
| Mochi 1 (Genmo · via fal.ai) | 10B, Apache 2.0, strong prompt-following, self-host friendly |
- Free Tier — 25 Nano Banana Pro generations/day without an API key (server-side Gemini)
- BYOK — Bring Your Own Keys for unlimited use (keys stored in
localStorageonly, never touch the server) - A single fal.ai key unlocks every video engine except Kling
- 1,377 curated image prompts from 5 open-source repos (
songguoxs,YouMind-OpenLab,Anil-matcha,ZeroLu,ImgEdify) + 50 video prompts /feed— editorial Twitter-style timeline with model/source/category filters, intersection-observer pagination, full per-prompt attribution/blog— 5 launch posts with editorial breakdowns of standout prompts (why they work, what to swap, full 13-cat breakdown per post)/sources— full credit page with GitHub stars, top contributors per repo, and one-click feed filter by source- Pattern library — extracted patterns across lighting, cameras, moods, color grades, and styles
- Showcase — 30 editorially curated examples with full 13-category prompt breakdowns
- Per-prompt OG cards — every prompt has a shareable 1200×630 social card via
/api/og/prompt?id=N
- Live preview of assembled prompt (JSON or natural language depending on model)
- Animated generation progress with theatrical transitions
- Love It / Tweak It / Remix result actions
- Gallery to save and revisit creations
- 30 pre-generated Showcase examples + 113 AI-generated community examples
| Model | Provider | Cost | Get a Key |
|---|---|---|---|
| Nano Banana Pro | Google Gemini 3 Pro Image | ~$0.04/image (free tier 25/day) | ai.google.dev |
| GPT-Image-2 | OpenAI | ~$0.04–0.12/image | platform.openai.com |
| Seedance 2.0 | ByteDance via fal.ai | $0.022/sec (Fast) · $0.18 for 8s | fal.ai |
| Veo 3.1 | Google DeepMind via fal.ai | $0.10–0.40/sec | fal.ai |
| Kling 3.0 | Kling AI | Varies | klingai.com |
| Layer | Web App | CLI |
|---|---|---|
| Framework | Next.js 16 (App Router) | Bun runtime |
| Language | TypeScript 5 | TypeScript 5 |
| Styling | Tailwind CSS v4 | picocolors |
| Animations | Framer Motion 12 | — |
| UI | React 19 + Lucide icons | @clack/prompts |
| State | React Context + localStorage | File-based (JsonStore) |
| APIs | Gemini 3 Pro Image, GPT-Image-2, fal.ai (Seedance + Veo), Kling | Gemini Vision (analyzer) |
- Node.js 18+ (web) or Bun (CLI + web)
- API keys are optional — the free tier works out of the box:
- Google AI Studio — Gemini 3 Pro Image / Nano Banana Pro (free tier 25/day)
- OpenAI Platform — GPT-Image-2
- fal.ai — Seedance 2.0 + Veo 3.1 (single key for both)
- Kling AI — Kling 3.0 video
git clone https://github.com/DareDev256/Ultimate-Image-Video-Prompt-Generator.git
cd Ultimate-Image-Video-Prompt-Generator/web
npm install
npm run devOpen http://localhost:3000. Configure API keys at /settings or just try the free tier.
cd Ultimate-Image-Video-Prompt-Generator
bun install
bun run index.ts| Variable | Required | Scope | Description |
|---|---|---|---|
GEMINI_API_KEY |
No | Server | Enables the free tier (25 Nano Banana Pro generations/day) for users without their own keys |
User-provided API keys (Gemini, OpenAI, fal.ai, Kling) are entered in the browser at /settings and stored in localStorage only — they never touch the server.
# Or manually
cd web && npm run build && npx vercel --prodAdd GEMINI_API_KEY as an environment variable in Vercel to enable the free tier for your users.
The prompt generator uses a functional pipeline where each prompt section is an independent pure function:
flowchart LR
A[ImagePrompt] --> B["13 Section Functions<br/>(subject, hair, clothing,<br/>camera, environment...)"]
B --> C[flatMap]
C --> D{Output Format}
D -->|Nano Banana| E[Structured JSON]
D -->|GPT-Image-2 / Kling| F[Natural Language]
Sections can be composed, reordered, or extended without touching other sections. The natural language generator is just 18 lines — a flatMap over the section array.
flowchart LR
A["/ <br/>Theatrical Intro"] --> B["/create<br/>Model Selection"]
B --> C["/create/[model]<br/>Wizard Steps"]
C --> D["/preview<br/>Assembled Prompt"]
C --> Q["/quick<br/>Freeform Mode"]
D --> E["/generate<br/>API Call + Progress"]
E --> F["/result<br/>Love It / Tweak It / Remix"]
State persists across all page transitions via React Context + localStorage sync, surviving Framer Motion route animations.
Most "randomize" buttons use naive Math.random() — click three times, get the same suggestion twice. This project uses a sliding-window exclusion algorithm inspired by shuffle-play systems:
Click 1: pool=[A,B,C,D,E] recent=[] → picks C → recent=[C]
Click 2: pool=[A,B,D,E] recent=[C] → picks A → recent=[C,A]
Click 3: pool=[B,D,E] recent=[C,A] → picks E → recent=[C,A,E]
Click 4: pool=[B,D] recent=[C,A,E] → picks D → recent=[C,A,E,D]
Click 5: pool=[B] recent=[C,A,E,D]→ picks B → recent=[A,E,D,B] ← window slides
Click 6: pool=[C] recent=[A,E,D,B]→ picks C → recent=[E,D,B,C] ← C is fresh again
Graceful fallback: when every option is in the recent window (small pools), exclusion is skipped and the full pool is used — the algorithm never deadlocks regardless of pool size vs window size.
The API is designed as a progressive stack — each layer wraps the one below it, adding exactly one concern:
diversePick pure pick, no side effects ← tests, one-off sampling
↓
pickWithHistory pick + state update in one call ← eliminates temporal coupling
↓
createPicker stateful factory, per-key memory ← scripts, CLI, non-React
↓
useDiversePick React hook (useRef state) ← components
Usage examples
// ① Pure function — caller manages state
import { diversePick, pushRecent } from "@/lib/diverse-pick";
let recent: string[] = [];
const pick = diversePick(["A", "B", "C", "D", "E"], recent); // never repeats recent
recent = pushRecent(recent, pick, 4); // slide window forward
// ② Combined pick + push — impossible to forget the state update
import { pickWithHistory } from "@/lib/diverse-pick";
let history: string[] = [];
const result = pickWithHistory(["A", "B", "C", "D", "E"], history, 4);
history = result.recent; // { value: "C", recent: ["C"] }
// ③ Stateful factory — drop-in for non-React consumers
import { createPicker } from "@/lib/diverse-pick";
const pick = createPicker<string>(4);
pick("lighting.mood", ["golden hour", "overcast", "neon"]); // per-key memory
pick("camera.angle", ["low", "eye-level", "bird's eye"]); // separate history
// ④ React hook — same guarantees, React lifecycle
const pick = useDiversePick<string>(4);
// identical call signature to createPicker — one migration path| Layer | File | Concern |
|---|---|---|
| Pure algorithm | diverse-pick.ts |
diversePick · pushRecent · parseFieldKey — zero deps |
| Combined | diverse-pick.ts |
pickWithHistory — pick + state update, no temporal coupling |
| Factory | diverse-pick.ts |
createPicker — per-key state for scripts, tests, CLI |
| React binding | useDiversePick.ts |
useDiversePick — useRef state, same call signature as createPicker |
| Composition | WizardStep.tsx / Quick Mode |
buildRandomPrompt + flattenPromptToText — full 11-category assembly |
Both the wizard and Quick Mode share the identical algorithm — Quick Mode composes buildRandomPrompt with the hook's picker for zero-duplication prompt assembly across all 11 web categories in a single click. Non-React consumers use createPicker for the same guarantees without hooks.
Proven properties (71 tests)
| Property | What the tests prove |
|---|---|
| Exclusion correctness | When alternatives exist, items in the recent window are never picked |
| Graceful degradation | When every option is recent (or recent is a superset), the algorithm falls back to the full pool — never deadlocks |
| Type generality | Works with strings, numbers, and frozen readonly arrays without mutation |
| Statistical diversity | Over 100 picks from 5 options, at least 3 distinct values appear (probabilistic smoke test) |
| Window sliding | pushRecent trims to maxSize, preserves immutability, handles edge windows (size=1, size=100) |
| Integration | Sliding window + picker composed together: no 3 consecutive identical picks over 12-round sequences |
| Key derivation | buildRandomPrompt derives output keys from field key prefixes (not category IDs), falling back to category.id only for empty categories |
| Round-trip fidelity | buildRandomPrompt → flattenPromptToText preserves all non-empty values through the pipeline, including unicode |
All three API routes (/api/generate/nano-banana, openai, kling) share a centralized validation layer (web/src/lib/validation.ts):
- Prompt length limit (10,000 chars) to prevent oversized payloads
- Control character stripping (null bytes, C0/C1 range)
- API key format validation (alphanumeric + limited special chars, max 256 chars)
- Upstream error sanitization — third-party error details are never leaked to the client
All types, section generators, and output formatters are documented with TSDoc — including @example blocks, {@link} cross-references, and field-level descriptions for every property in the ImagePrompt type tree.
📁 Project Structure
.
├── .todoignore # Excludes node_modules etc. from code-debt scanning
├── web/ # Next.js web app
│ ├── src/
│ │ ├── app/
│ │ │ ├── page.tsx # Theatrical intro screen
│ │ │ ├── create/ # Model selection → wizard → preview → generate → result
│ │ │ ├── gallery/ # Saved creations
│ │ │ ├── showcase/ # 30 pre-generated examples
│ │ │ ├── settings/ # API key configuration
│ │ │ └── api/generate/ # API routes (nano-banana, openai, kling)
│ │ ├── components/
│ │ │ ├── wizard/ # WizardStep, WizardProgress
│ │ │ ├── effects/ # Canvas particle system
│ │ │ └── inspiration/ # Gallery panel, search, filters, cards
│ │ ├── context/ # WizardContext (state + persistence), SoundContext
│ │ ├── hooks/ # useLocalStorage, useDiversePick, useFavorites, useFreeTier, usePatterns, useInspirationData
│ │ └── lib/ # Categories, diverse-pick, validation, sounds
│ └── public/data/ # Prompt library, patterns, showcase metadata
│
├── src/ # CLI tool (Bun)
│ ├── index.ts # Entry point with arg parsing
│ ├── analyzer/ # Gemini Vision — reverse-engineer prompts from images
│ ├── cli/ # Terminal UI (prompts, display, menus, args)
│ ├── core/ # 13 categories (1,019 lines), preset packs, templates
│ ├── generators/ # Composable section pipeline
│ │ ├── sections.ts # 13 pure section generators
│ │ ├── natural.ts # Natural language assembly (flatMap pipeline)
│ │ └── json.ts # JSON output with recursive cleanup
│ ├── lib/ # Shared utilities
│ │ ├── json-store.ts # Generic typed JSON file storage
│ │ └── nested.ts # Dot-notation path traversal utilities
│ ├── storage/ # Config, presets, favorites (via JsonStore)
│ └── types/ # ImagePrompt interface (12 nested types)
│
├── scripts/ # Data pipeline (fetch, extract, translate, generate)
└── docs/ # Design documents and plans
bun test399 tests across 17 test files:
| Module | Tests | Coverage |
|---|---|---|
| Section generators | 56 | All 13 pure functions — edge cases, dedup, fallback precedence |
| Template→pipeline integration | 36 | Every template through NL+JSON generators, merge behavior, data integrity |
| Diversity-aware randomization | 71 | diversePick exclusion, full-pool fallback, superset recent, statistical diversity proof, probabilistic fairness, pigeonhole coverage, reference equality semantics, duplicate filtering, large pool (1000 opts), pushRecent sliding window + immutability + boundary cases, pickWithHistory combined pick+push (5 tests), createPicker per-key isolation + sequential non-repeat (4 tests), parseFieldKey parsing (3 tests), buildRandomPrompt key derivation + merge behavior, empty-suggestions contract, field iteration order, flattenPromptToText empty/unicode/whitespace-only/insertion-order, window eviction proof, per-field history isolation, build→flatten round-trip, full-cycle multi-category simulation |
| Cross-cutting invariants | 24 | NL/JSON consistency, cleanObject edge cases, pipeline purity, parseArgs boundaries |
| CLI argument parser | 22 | All 15 flags, shorthands, pack splitting, subcommands |
| Input validation & sanitization | 22 | Prompt length/type/control-char stripping, API key format/injection defense |
| Pack/template registry | 18 | Composition, dedup, always-core invariant, uniqueness |
| Category data integrity | 16 | Unique names/emojis, field keys, suggestion validity |
| Gemini analyzer | 14 | Error paths, MIME detection, markdown stripping |
| Nested path utilities | 13 | Dot-notation get/set, missing paths, intermediate creation |
| Display text wrapping | 11 | Word boundaries, unicode, edge cases |
| JsonStore persistence | 11 | File I/O, defaults, deep-clone isolation, roundtripping |
| Prompt building | — | Ordering, nesting cleanup, unicode, JSON/NL consistency |
The stuff under the neon paint.
| Area | What | Why it matters |
|---|---|---|
Zero any types |
Entire codebase uses unknown at serialization boundaries with type narrowing |
Catches bugs at compile time that any would silently pass through — especially in the JSON serializer where nested data arrives as unknown |
| Composable pipeline | 13 section generators are pure functions composed via flatMap |
Adding a new prompt section is one function + one array entry — no touch points in existing code |
| Diversity-aware randomization | Sliding-window exclusion algorithm (detail) shared between wizard, Quick Mode, and headless consumers | diversePick → pickWithHistory → createPicker layered API: pure function, combined pick+push, and stateful factory. 71 tests prove exclusion, graceful degradation, probabilistic fairness, pigeonhole coverage, per-key isolation, merge correctness, and round-trip fidelity (proven properties) |
| Centralized input validation | Shared validation.ts with prompt sanitization, key format checks, and length limits |
One place to audit, one place to fix — not scattered across 3 API routes |
| Single-source model registry | MODEL_NAMES, MODEL_COLORS, isValidModel in lib/models.ts + useCopyToClipboard hook |
Adding a model or changing brand colors is a 1-file change — replaces 4× duplicated metadata maps and 3× clipboard boilerplate |
| Temporal coupling elimination | pickWithHistory combines pick + state update in one call; createPicker wraps it in a stateful factory |
Impossible to forget the state update step — callers can't use diversePick without also calling pushRecent |
| Data-driven preset parsing | Replaced 5-branch else if chain with a PRESET_FLAGS lookup map |
Adding a new preset is a one-line map entry instead of a new branch |
| 460 tests / 6,530 assertions | Every generator, every template, every CLI flag, cross-format consistency checks, web-side validation & diversity logic | Not just coverage — tests document invariants like "NL and JSON generators stay in sync on the same input" |
Remember when websites had loading screens, particle effects, and sound design? This is that energy — with modern engineering underneath.
This project embraces the Flash Site Era aesthetic (2002–2006) — when websites were experiences, not just pages:
- Theatrical Loading — Animated intro with progress bar and skip option
- Glossy Everything — Buttons with gradients, shadows, and glow effects
- Particle Systems — Canvas-based floating particles with GPU acceleration
- Sound Design — 5 named sounds (click, whoosh, hover, success, processing) — off by default, opt-in via settings, preference persisted in
localStorage - Over-the-top Transitions — Page slides, scale animations, staggered reveals
- Neon Palette — Cyan
#00d4ff, pink#ff00aa, green#00ff88, gold#ffd700 - Typography — Orbitron (headings) + Exo 2 (body)
🧩 Challenges & Solutions
| Challenge | Solution |
|---|---|
| State loss during page transitions | Framer Motion unmounts components on route change. Solved with React Context + localStorage sync to persist wizard state across animated transitions. |
| Keyboard nav vs. text input | Arrow keys conflicted with suggestion field typing. Implemented focus detection to disable shortcuts during input, re-enable on blur. |
| Canvas particle performance | Frame drops on lower-end devices. Reduced particle count, added requestAnimationFrame throttling and will-change GPU hints. |
| Multi-model prompt formats | Each AI model expects different formats. Built a unified generation interface with model-specific adapters (JSON for Nano Banana, natural language for GPT-Image-2/Kling). |
| Randomize repeats same values | Naive Math.random() frequently repeats the same suggestion. Implemented a sliding-window exclusion algorithm (diversePick) that tracks recent picks per field and excludes them from the candidate pool — with graceful fallback when the pool is smaller than the window. |
| Type safety at serialization boundaries | cleanObject recursively processes prompt data of unknown shape. Replaced any with unknown + type narrowing to catch bugs at compile time instead of runtime. |
- API keys stored in
localStorageonly — never sent to any server - No server-side storage of prompts or images
- Direct API calls from your browser (except free tier)
- Server-side input validation: prompt length limits, control character stripping, API key format checks
- Rate limiting on free tier (10 generations/day per client)
- HTTP security headers on all routes: HSTS, X-Frame-Options (DENY), X-Content-Type-Options, Referrer-Policy, Permissions-Policy
- Upstream API errors are sanitized — third-party error details are never leaked to the client
The scripts/ directory contains a full pipeline for refreshing and expanding the prompt library:
| Script | What it does |
|---|---|
fetch-prompts.ts |
Fetches image + video prompts from upstream repos |
fetch-nano-banana-prompts.ts |
Fetches 5,600+ prompts from YouMind-OpenLab |
extract-patterns.ts |
Mines the corpus to build 240 patterns (lighting, cameras, moods, etc.) |
translate-titles.ts |
Extracts English titles from bilingual EN/ZH content |
batch-generate-inspiration.py |
Batch-generates preview images via Gemini 3 Pro |
update-prompts-with-generated.py |
Writes generated image paths back into prompt JSON |
backfill-origin.ts |
Stamps upstream repo + licence onto every prompt (idempotent) |
build-shot-grammar-terms.ts |
Builds the scorer's 598-term vocabulary from the corpus |
fetch → translate → extract patterns → generate images → update JSON
1,421 of the 1,427 prompts carry a named author, across 374 distinct creators,
credited down to the individual handle, surfaced on each card, in the OG image,
and at /sources with live repo
metadata. The counts below are generated from the shipped data, not maintained
by hand:
| Prompts | Upstream | Licence |
|---|---|---|
| 1,180 | YouMind-OpenLab/awesome-nano-banana-pro-prompts | CC BY 4.0 |
| 76 | ImgEdify/Awesome-GPT4o-Image-Prompts | MIT |
| 69 | ZeroLu/awesome-gpt-image | MIT |
| 52 | Anil-matcha/Awesome-GPT-Image-2-API-Prompts | No stated licence |
| 50 | songguoxs/awesome-video-prompts | No stated licence |
CC BY 4.0 notice. The 1,180 prompts from YouMind-OpenLab are used under Creative Commons Attribution 4.0 International, which permits commercial use with attribution. Changes were made: titles were translated from Chinese to English, 240 style patterns were extracted from the corpus, and preview images were generated for a subset. YouMind-OpenLab does not endorse this project.
Where no licence is stated, the material is used with full attribution while the authors are asked to add one. If you are one of them and would rather your prompts were not included, open an issue and they will be removed.
An earlier version of this section credited @songguoxs with 1,180 image prompts. That was wrong — those entries come from the YouMind-OpenLab corpus via
fetch-nano-banana-prompts.ts, and the table above is the corrected attribution. songguoxs is credited for the video set, which is theirs.
- API Reference — Generation endpoints, CLI commands, validation rules, and error codes
- Diversity-Aware Randomization — Algorithm deep-dive, 4-layer architecture, API reference (
diversePick→pickWithHistory→createPicker), complexity analysis, usage examples, design decisions, and 15 proven invariants (71 tests) - Contributing Guide — Code style, component patterns, and PR process
See CONTRIBUTING.md for guidelines. Bug reports, feature suggestions, and pull requests are welcome.
Built with caffeine and nostalgia for the early 2000s web.
399 tests. Zero any types. Maximum vibes.