Skip to main content
Stanzo requires several API keys to function properly. This guide walks you through setting up all required environment variables for both local development and production deployment.

​
Required API Keys

Stanzo integrates with three external services that require API keys:
  • Deepgram - Real-time speech-to-text transcription
  • Google Gemini - AI-powered claim extraction from debate transcripts
  • Perplexity - Fact-checking and verification of claims

​
Local Development Setup

1

Create environment files

Create two separate environment files in your project root:.env.local - For Next.js environment variables:
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
.env - For Convex environment variables (managed separately):
# This file is for reference only
# Actual Convex env vars are set via `npx convex env set`
Next.js and Convex use different environment variable systems. Next.js reads from .env.local, while Convex environment variables must be set using the Convex CLI.
2

Get Deepgram API Key

Deepgram provides real-time speech-to-text transcription for debate audio.
  1. Sign up at deepgram.com
  2. Navigate to your API Keys section
  3. Create a new API key
  4. Set it in Convex:
npx convex env set DEEPGRAM_API_KEY your_deepgram_api_key_here
The Deepgram API key is used in convex/deepgramToken.ts:12 to mint temporary client tokens for browser-based transcription.
3

Get Google Gemini API Key

Google Gemini powers the claim extraction system that identifies factual statements in debate transcripts.
  1. Visit Google AI Studio
  2. Create a new API key
  3. Set it in Convex:
npx convex env set GEMINI_API_KEY your_gemini_api_key_here
Used in convex/claimExtraction.ts:119 with the gemini-2.5-flash model to extract verifiable claims from debate transcripts.
4

Get Perplexity API Key

Perplexity provides real-time fact-checking capabilities with source citations.
  1. Sign up at perplexity.ai
  2. Navigate to API settings
  3. Generate a new API key
  4. Set it in Convex:
npx convex env set PERPLEXITY_API_KEY your_perplexity_api_key_here
Used in convex/factCheck.ts:107 with the sonar model to verify claims and provide corrections with citations.
5

Set Convex URL

After deploying your Convex backend, set the deployment URL in your Next.js environment:
  1. Run npx convex dev to get your development URL, or npx convex deploy for production
  2. Copy the deployment URL (e.g., https://your-deployment.convex.cloud)
  3. Add to .env.local:
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
The NEXT_PUBLIC_ prefix is required for this variable to be accessible in the browser. This URL is used in src/app/providers.tsx:7 to initialize the Convex client.
6

Configure Convex Site URL (optional)

For authentication to work properly, set your site URL in Convex:
npx convex env set CONVEX_SITE_URL http://localhost:3000
For production:
npx convex env set CONVEX_SITE_URL https://your-domain.com
This is used in convex/auth.config.ts:4 for the authentication provider configuration.

​
Environment Variable Reference

​
Next.js Environment Variables

Set these in .env.local:
VariableRequiredDescriptionExample
NEXT_PUBLIC_CONVEX_URLYesConvex deployment URLhttps://happy-animal-123.convex.cloud

​
Convex Environment Variables

Set these using npx convex env set VARIABLE_NAME value:
VariableRequiredDescriptionUsed In
DEEPGRAM_API_KEYYesDeepgram API key for speech-to-textconvex/deepgramToken.ts
GEMINI_API_KEYYesGoogle Gemini API key for claim extractionconvex/claimExtraction.ts
PERPLEXITY_API_KEYYesPerplexity API key for fact-checkingconvex/factCheck.ts
CONVEX_SITE_URLRecommendedYour application URL for authconvex/auth.config.ts

​
Verifying Your Setup

After setting all environment variables, verify your setup:
1

Check Convex environment variables

npx convex env list
You should see all four Convex variables listed (keys will be partially hidden for security).
2

Check Next.js environment

Start the development server and check the browser console:
npm run dev
The Convex client should initialize without errors.
3

Test API integrations

Create a test debate and verify:
  • Audio transcription works (Deepgram)
  • Claims are extracted from transcript (Gemini)
  • Claims are fact-checked (Perplexity)
Never commit API keys to version control. Ensure .env.local and .env are in your .gitignore file.

​
Production Deployment

For production deployments (e.g., Vercel):
  1. Set NEXT_PUBLIC_CONVEX_URL in your hosting platform’s environment variables
  2. Deploy your Convex backend with npx convex deploy --prod
  3. Set all Convex environment variables in production: 
    npx convex env set DEEPGRAM_API_KEY your_key --prod
npx convex env set GEMINI_API_KEY your_key --prod
npx convex env set PERPLEXITY_API_KEY your_key --prod
npx convex env set CONVEX_SITE_URL https://your-domain.com --prod
The --prod flag ensures environment variables are set in your production Convex deployment, not development.

Build docs developers (and LLMs) love

Get started for freeTalk to us