Setup
Which API keys OpenShorts needs, and what each one powers
Three providers, three different jobs — Gemini for moment picking, ElevenLabs for dubbing, fal.ai for AI Shorts — plus Upload-Post for publishing, and how to swap Gemini for a model you already run.
Three keys, three different jobs
OpenShorts is free software with paid ingredients. You can run the whole stack without paying a subscription, but three providers do work that the repo does not do locally:
- Gemini — moment detection, layout choice per scene, hook lines, titles, virality scoring, and the thumbnail image stage. This is the one that matters most: without a language model of some kind the pipeline cannot pick clips.
- ElevenLabs — AI dubbing into 30+ languages. Optional. If you never dub, you never need it.
- fal.ai — the AI Shorts side of the app: AI actors, generated images, lip-sync. Optional, and separate from the clip generator.
A fourth integration is optional and easy to miss: Upload-Post, which is what makes the social auto-publishing buttons work. No key, no publishing.
Where the keys go
Keys are read from your .env file next to the clone. The variable names per provider are documented in .env.example and in the README's Environment Variables section — use those names rather than guessing, because the project has renamed integrations between releases (the thumbnail model, for instance, is configured separately from the main text model).
Treat .env as a secret. It sits inside your clone, so if you push your copy of the repo anywhere, that file goes with it unless you ignore it.
Running without a Google key
The moment-picking stage talks to any OpenAI-compatible endpoint, which means you can replace Gemini with a model you already run:
LLM_BASE_URL=http://host.docker.internal:11434/v1
LLM_MODEL=your-local-model
OLLAMA_CONTEXT_LENGTH=16384
LLM_BASE_URL— the base URL of the endpoint. Ollama, LM Studio, vLLM, llama.cpp, LocalAI and OpenRouter all speak this dialect.LLM_MODEL— the model name as the endpoint expects it.LLM_API_KEY— only if your endpoint checks one. For a local Ollama, it is unnecessary.LLM_SCORE_BATCHandLLM_TIMEOUT— how many transcript segments go into one request, and how long a request may take before it is abandoned.
From inside a container, localhost is the container itself. On Docker Desktop, host.docker.internal reaches the host; on Linux you add a host-gateway entry to the compose file instead. Ollama also needs a larger context window than its default for this workload — hence OLLAMA_CONTEXT_LENGTH=16384 in the example above.
What you give up: Flash-Lite is fast and reads scene structure well, and a small local model is blunter about which moment is actually the good one. What you keep: transcripts, audio and frames never leave the machine.
What each key really costs you
Self-hosting moves the bill from a subscription to per-call API charges, so the numbers worth knowing before you start:
- Minutes are not the cost — tokens are. A one-hour podcast means a long transcript to score, plus per-scene frame analysis. Short, talk-heavy sources are the cheap end; long videos with many scene changes are the expensive end.
- Dubbing is the expensive optional step. It is charged per character by ElevenLabs, and it is per target language — dubbing one clip into five languages is five bills.
- AI Shorts is metered per video. The project's own cost estimate is around $0.65 per video in Low Cost mode and around $2 in Premium, because the actors and images are generated per clip.
- The Gemini stage has a free tier that is enough to evaluate the pipeline on a handful of short videos before you decide whether the per-call cost is acceptable at your volume.
If those per-call numbers make you hesitate, compare them against the hosted alternative before you buy a GPU: the self-hosted vs cloud page runs the arithmetic, and the install guide covers the hardware side.
Checking that a key actually works
Set DEBUG_LOGS=true and run one short clip. The pipeline log shows each stage — transcription, moment scoring, layout, render — with the model calls and their failures in the open, which is faster than reading three dashboards to find out which provider rejected you.
If a stage silently does nothing, the usual cause is a key that loaded in the dashboard but not in the container, or a key pasted into .env while the container was already running. docker compose up -d --force-recreate picks up env changes.