Pindeck uses two AI providers: OpenRouter for vision-language model (VLM) analysis, and fal.ai for cinematic image variation generation. Both are required for the full AI pipeline to work.
Both OPENROUTER_API_KEY and FAL_KEY must be set in Convex Project Settings → Environment Variables. Setting them in .env.local has no effect on backend Convex functions.
OpenRouter (image analysis)
When an image is approved or uploaded, Pindeck sends it to a Vision Language Model via OpenRouter to extract structured metadata.| Field | Description |
|---|
title | Short, descriptive title |
description | Concise image description |
tags | 5–10 specific descriptive tags |
colors | 5 hex color codes representing the palette |
visual_style | Medium or aesthetic (e.g. 35mm Film, CGI, VHS) |
category | One of 24 predefined categories (e.g. Film, Commercial, Fashion) |
group | Project type context (e.g. Music Video, Commercial, Film) |
project_name | Recognized project name, if applicable |
moodboard_name | Moodboard label, if the image is a reference |
Default model
The default VLM is qwen/qwen3-vl-8b-instruct. You can override it by setting OPENROUTER_VLM_MODEL in Convex Project Settings.Any multimodal model available on OpenRouter that accepts image_url inputs in the chat completions API will work. Check OpenRouter’s model list to find models that fit your budget and quality requirements. Larger models generally produce more accurate metadata extraction.
Provider routing
Set OPENROUTER_PROVIDER_SORT to control how OpenRouter routes requests across providers:| Value | Behavior |
|---|
price | Routes to the cheapest available provider |
throughput | Routes to the provider with the highest throughput |
latency | Routes to the lowest-latency provider |
Error handling
If analysis fails (network error, model error, or missing API key), the image aiStatus is set to failed. You can re-run analysis from the Edit Image modal in Pindeck without re-uploading the image.Environment variables
| Variable | Required | Description |
|---|
OPEN_ROUTER_KEY | Yes | Your OpenRouter API key. OPENROUTER_API_KEY is also accepted as a fallback — set either one. |
OPENROUTER_VLM_MODEL | No | VLM model override; defaults to qwen/qwen3-vl-8b-instruct |
OPENROUTER_PROVIDER_SORT | No | Routing preference: price, throughput, or latency |
fal.ai (variation generation)
After AI analysis completes (or when triggered directly from Discord), Pindeck calls fal.ai to generate cinematic image variations using the Nano Banana Pro edit model.Model
Pindeck uses fal-ai/nano-banana-pro/edit. Each variation is generated with:
- Source image — the original or approved image URL
- Prompt — constructed from the variation mode and optional custom detail
- Aspect ratio — one of
16:9, 9:16, 1:1, 4:3, 3:4
- Resolution — 2K
- Output format — PNG
Variation modes
| Mode | Description |
|---|
shot-variation | Different camera angle of the same subject; cycles through 16 shot types when no detail is provided |
action-shot | Dramatic action or performing moment; same person |
coverage | Environmental detail or object shot; no people |
b-roll | Same location, no people; establishing or ambient |
style-variation | Same person in a different scene, outfit, and location |
subtle-variation | Later in the same scene; same person, different beat |
Variation count
You can request 1–12 variations per run. Each variation is generated in parallel. The default count when triggering from Discord is controlled by DISCORD_GENERATE_DEFAULT_COUNT in the bot’s environment.Group-aware prompting
Prompts are automatically prefixed based on the image’s group field:
Music Video → “Later in the music video. …”Commercial → “Later in the commercial. …”Film / TV Series / Web Series → “Later in the scene. …” (for action shots)
Error handling
Individual generation failures are logged but do not stop the rest of the batch. If every variation in a run fails, the parent image aiStatus is set to failed. You can retry generation from the Edit Image modal or via /images generate in Discord.Environment variables
| Variable | Required | Description |
|---|
FAL_KEY | Yes | Your fal.ai API key |