AI Overview
The four AI studios, where each runs, mock and live modes, configuration, and the code map.
What is included
Flare ships four studios in the workbench, a private media library and public landing pages for each studio. Every studio shares one credit ledger, one task table and one queue.
| Studio | Endpoint | Runs on | Default price |
|---|---|---|---|
| Images | POST /api/ai/images | OpenAI GPT Image 2.5 Flare | 20 credits an image |
| Video | POST /api/ai/videos | Provider adapter, polled on Queues | 6, 12 or 23 credits a second at 480P, 720P or 1080P |
| Voice | POST /api/ai/speech | OpenAI GPT-4o Mini TTS · Queues | 5 credits per 1,000 characters, rounded up |
| Chat | POST /api/chat | OpenAI GPT-6 Luna · SSE | 1 credit a message |
| Summaries | POST /api/summary | OpenAI GPT-6 Luna · Queues | 5 credits |
| Prompt enhancement | POST /api/ai/prompt/enhance | OpenAI GPT-6 Luna | Free, 20 a minute per user |
Outputs go to R2 under {userId}/ai/{assetId} and are listed in /app/library. Read Images, Video and voice, Chat and summaries and Credits and cost control for each part.
Mock and live modes
AI_MODE decides whether providers are called:
| Environment | Default | Override |
|---|---|---|
Local development (APP_ENV=development) | mock: deterministic images, sample video and audio written to local R2 | AI_MODE=live pnpm dev |
| Deployed Worker | live | AI_MODE=mock as a Worker variable |
Mock mode needs no account or key and makes no provider calls. For live OpenAI calls, set OPENAI_API_KEY in apps/web/.dev.vars, then run AI_MODE=live pnpm dev. D1, R2 and Queues stay local. In PowerShell:
$env:AI_MODE = 'live'
pnpm devWorkers AI is optional. To test its models locally, first run wrangler login, then also set WORKERS_AI_REMOTE=true (PowerShell: $env:WORKERS_AI_REMOTE = 'true'). This connects the AI binding to your Cloudflare account and consumes Neurons. OpenAI does not need that switch or a remote AI binding.
Provider keys
| Secret | Purpose |
|---|---|
OPENAI_API_KEY | Default chat, summaries, prompt enhancement, images and speech. Missing media credentials hide the corresponding models; text calls report configuration errors instead of silently using another provider. |
DASHSCOPE_API_KEY | Separate video adapter and the retained alternative image/speech models. |
DASHSCOPE_HOST | Optional regional or workspace host for that adapter. |
Keep local keys in ignored apps/web/.dev.vars. For deployment, put them in root .env, run pnpm muse:doctor, review pnpm muse:deploy --plan, then use pnpm muse:deploy --yes when ready to publish; the CLI uploads the keys as Worker secrets. Never commit keys or expose them through client variables. See deployment.
Provider interfaces and the openaiText, openaiImages and openaiSpeech adapters live in packages/ai. Runtime selection lives in apps/web/src/modules/ai/mode.ts. Workers AI remains available as an explicit alternative. Video keeps its separate provider; review the video and speech lifecycle notes.
Configuration
packages/config/src/index.ts holds the defaults:
| Setting | Default | Effect |
|---|---|---|
quotas.welcomeCredits | 30 | Granted once after email verification |
quotas.chatCredits / quotas.summaryCredits | 1 / 5 | Chat and summary prices |
ai.maxActiveTasks | 2 | Unfinished generations one user may hold |
ai.maxAttempts | 3 | Attempts before a task fails and returns its credits |
ai.dailyBudgetUsd | 10 | Estimated upstream spend allowed per UTC day; 0 turns the cap off |
ai.refundOnContentRefusal | true | Whether a provider content refusal returns credits |
ai.minGrossMargin | 0.3 | Margin every model price must keep at your cheapest credit price |
ai.uploadLimit | 200 | Reference images kept per user |
Model prices live in the catalogs: packages/ai/src/catalog.ts (images), video.ts and speech.ts.
Code map
| Location | Responsibility |
|---|---|
packages/ai | Catalogs, provider interfaces, OpenAI, Workers AI and other adapter clients, the image engine, mock media, error classes. Pure TypeScript with no Worker imports. |
apps/web/src/modules/ai | Pricing, reservation, mode selection, task jobs, the library and asset streaming |
apps/web/src/server/routes/ai.ts | Chat, summary, studio, upload and library endpoints |
packages/db/src/ai.ts | AI tasks, leases, reservations, releases and the daily spend query |
apps/web/src/server/queue.ts, jobs.ts | Queue consumer and the five-minute recovery |
apps/web/src/modules/workbench | Studio pages (image.tsx, video.tsx, voice.tsx, ai.tsx) and library.tsx |
apps/web/src/modules/public | Public /ai/image, /ai/video, /ai/voice and /ai/chat pages |
Verify
pnpm test:unitandpnpm test:workerscover pricing, reservations, leases, retries and refunds in mock mode.- Locally, generate in each studio, refresh, and confirm the library, the usage page and the balance agree.
- For a live check, use your own account and a small budget. Do not run batch or cost tests against the public demo, and never paste keys into issues.
Model quality, provider quotas and production costs depend on your own accounts and remain your acceptance test.