Next.js app with Google Gemini: AI launch checklist
Next.js apps call Google Gemini with your own API key, from server code, so Google Gemini's own limits are your safety net. Of the 20 checks before you charge users, Next.js handles 0, partly handles 3, and leaves 17 to you.
Checked 12 Nov 2026 against each platform's docs; every fact links to its source.
How AI calls work in Next.js
- Built-in AI
- None unless you choose one. You call providers from route handlers or server actions with their SDKs or the AI SDK; Vercel AI Gateway is optional (same budgets, logs and reporting as v0).
- Who pays
- Each provider directly (or AI Gateway Credits at provider list price with no markup).
Keys and secrets
- Where secrets live
- Vercel project environment variables (Production / Preview / Development); .env files locally, which create-next-app adds to .gitignore.
- Server-side by default?
- 'By default, environment variables are only available on the server.'
- How keys end up in the browser
- Prefixing an AI key with NEXT_PUBLIC_, which Next.js inlines into the JavaScript sent to the browser at build time; or committing .env.
The 20 checks, in Next.js
What Next.js does for you, and what to ask it (or your coding agent) to add. Tick them off in the interactive checklist.
Cost and abuse
- You add it
A spending cap per user
Ask Claude Code or Cursor: 'In every route handler or server action that calls the provider, sum the user's cost today from ai_costs and return an error over $2.' If you use AI Gateway, add a project budget as a backstop.
- Partly
Rate limits on every AI endpoint
Add a Vercel WAF rate-limit rule on your AI routes (all plans; one rule on Hobby) and have the agent add a per-user limit in code backed by Redis or Postgres.
- Partly
AI keys only on the server
Next.js keeps non-NEXT_PUBLIC_ variables on the server and inlines NEXT_PUBLIC_ ones into the browser bundle, so have the agent grep for NEXT_PUBLIC_ on any AI key and keep every provider call in route handlers or server actions.
- You add it
Retries capped, with a timeout
Have the agent set an explicit retry cap (2) and a timeout on every SDK call and remove client-side retries.
- You add it
A budget alert at each AI provider
Set a hard limit at each provider (OpenAI 'Enforce a hard limit', Anthropic spend limits, Gemini project spend cap, OpenRouter key limit, fal alerts); Vercel Spend Management only covers Vercel's own metered usage.
Charging for AI use
- You add it
Every AI call charged or deliberately free
Have the agent list every provider call site, including background jobs and moderation, and mark each as charged or free on purpose.
- You add it
Credits deducted on the server, after success
Have the agent deduct credits in the same database transaction that saves the result, inside the route handler, with no client-writable balance.
- You add it
Failed AI calls refunded
Have the agent refund reserved credits with a reason on provider errors, timeouts, refusals and empty or invalid outputs.
- You add it
One charge per request, even on a double click
Have the agent add a client-generated request id with a unique constraint and return the saved result on repeats.
A record of every AI result
- You add it
Each AI result stored with its feature, model, prompt version and settings
Have the agent create ai_results with feature, model id reported by the provider, prompt version, params, input, user_id and provider request id (AI Gateway's logs help but aren't tied to your users).
- You add it
Retries and corrections saved next to the original, never over it
Have the agent store retries and edits as new versioned rows linked to the original.
- You add it
What users do next with each AI result, recorded on the server
Have the agent add an ai_events table and a server action called from the existing Retry, Edit, Copy and Export buttons.
What worked, for whom, at what cost
- You add it
Worked first time, per feature, model and prompt version
Have the agent add an admin page with worked-first-time per feature, model and prompt version.
- You add it
A cost record for every AI step
Have the agent save an ai_costs row per call from the provider's usage field and one price table (or AI Gateway Generation Lookup).
- You add it
Wasted AI spend and real cost per result, per feature
Have the agent build the wasted-spend and cost-per-working-result query from ai_costs and ai_events.
- You add it
Who the AI fails for
Have the agent save input traits on each result and split worked-first-time by them.
Switching safely
- Partly
Prompts in version control, with version labels
The app is already a git repo; have the agent move inline prompts into prompts/*.ts with version labels saved on each result.
- You add it
Model and prompt switchable by a flag
Have the agent read model id and prompt version from a Vercel environment variable or database setting per feature, with a user-id-hashed split.
- You add it
Real past requests to replay before a change
Have the agent write a script that replays 50 anonymised past requests through any model and prompt version and saves results and cost.
- You add it
A plan for model shutdowns
Have the agent centralise model ids in one config and write MODELS.md with each provider's retirement dates.
Google Gemini limits to set before launch
- Tier spend caps
- Billing-account level: Tier 1 $250, Tier 2 $2,000, Tier 3 $20,000 to $100,000+. At the cap, 'service is paused for all projects linked to that billing account' until the 1st (hard stop).
- Prepay
- Prepay is the default for new users (minimum $5). At $0 balance 'all API keys in all projects linked to that billing account will stop working simultaneously' (HTTP 402). A 'Monthly auto-charge limit' caps automatic reloads.
- Project spend cap
- Experimental: https://aistudio.google.com/spend → 'Monthly spend cap' → 'Edit spend cap' (project editor/owner/admin). About 10 minutes of billing latency can overshoot it.
- Alerts
- AI Studio billing page doesn't mention alerts. Google Cloud console → Billing → Budgets & alerts: alerts-only budgets 'don't automatically cap' spending; default thresholds 50%, 90%, 100%; can be scoped to a project or service.
- Spend rate
- Rolling 10-minute spend limit: Tier 1 $10, Tier 2/3 $200, returning 429 RESOURCE_EXHAUSTED.
- Key scoping
- Every key belongs to a Google Cloud project (create at https://aistudio.google.com/apikey). Since May 28, 2026 new AI Studio keys are 'auth' keys bound to a service account and restricted to the Generative Language API by default, with fast leaked-key enforcement. Restrict older keys with 'Restrict to Gemini API only'; add IP application restrictions in https://console.cloud.google.com/apis/credentials. Unrestricted standard keys are rejected; unrestricted dormant keys blocked since May 7, 2026. Google says 'Never expose keys client-side in production.'
- Rate limits
- Per project, not per API key: RPM, TPM, RPD (RPD resets at midnight Pacific). Free; Tier 1 (billing linked); Tier 2 ($100 cumulative Google Cloud spend + 3 days); Tier 3 ($1,000 + 30 days). View at https://aistudio.google.com/rate-limit. Failed 400/500 requests aren't charged but count against quota.
- Where usage shows
- AI Studio Dashboard → Usage (https://aistudio.google.com/usage) and Billing (https://aistudio.google.com/billing) for balance and transactions; spend cap counts all keys in a project. Per-key or per-model breakdown in AI Studio not described; Cloud Billing reports group by SKU filtered to Gemini API. Up to 24 hours delay.
aistudio.google.com ↗aistudio.google.com ↗aistudio.google.com ↗docs.cloud.google.com ↗
Mistakes Next.js apps make at launch
AI key prefixed with NEXT_PUBLIC_.
Next.js inlines NEXT_PUBLIC_ values into JavaScript sent to the browser; Vercel reported over 17k v0 deployments blocked in July 2025 for exposed secrets and NEXT_PUBLIC_ misuse.
An unauthenticated or forgotten AI route.
Vercel Community thread (2026): unexpected Anthropic and OpenAI usage traced to a likely leftover dev route; keys had to be rotated.
Relying on an alert instead of a hard stop.
OpenAI spend alerts don't stop traffic unless 'Enforce a hard limit' is on; Vercel Spend Management checks every few minutes and doesn't cap provider bills.
Questions
How do AI calls work in a Next.js app with Google Gemini?
Next.js apps call Google Gemini with your own API key, from server code, so Google Gemini's own limits are your safety net.
Can Next.js cap AI spending per user?
You add it. Ask Claude Code or Cursor: 'In every route handler or server action that calls the provider, sum the user's cost today from ai_costs and return an error over $2.' If you use AI Gateway, add a project budget as a backstop.
Where should the Google Gemini key live in Next.js?
Partly. Next.js keeps non-NEXT_PUBLIC_ variables on the server and inlines NEXT_PUBLIC_ ones into the browser bundle, so have the agent grep for NEXT_PUBLIC_ on any AI key and keep every provider call in route handlers or server actions.
How do I stop one user running up my Google Gemini bill?
Add a per-user daily cap in your own code, checked before every AI call. Then set a limit at Google Gemini as a backstop: Experimental: https://aistudio.google.com/spend → 'Monthly spend cap' → 'Edit spend cap' (project editor/owner/admin). About 10 minutes of billing latency can overshoot it.