Overview
Learn about the built-in AI features powered by the Vercel AI SDK.
The Pro Next.js Prisma starter kit ships an organization-scoped chat powered by AI SDK 7 and the direct OpenAI provider. It includes text streaming, tRPC conversation history, model selection and usage-based credits.
Chatbot
Prompting
Architecture
The AI system is built with a hybrid architecture to support high-performance streaming while maintaining a type-safe tRPC API for CRUD operations.
| Feature | Technology | Reason |
|---|---|---|
| Streaming responses | API Route | tRPC doesn't support streaming |
| Chat CRUD | tRPC | Type-safe, cached queries |
| State management | Vercel AI SDK | useChat hook handles streaming |
Configuration
Add your OpenAI API key to the .env file to enable the AI features.
OPENAI_API_KEY=sk-...Getting Your API Key Create an API key at
OpenAI Platform
. Make sure to keep it secure and never commit it to version control.
Use an OpenAI server key
OPENAI_API_KEY must contain a secret key created in the OpenAI
Platform. OpenAI keys commonly begin with sk-. A value beginning
with pk_test_ is a Stripe publishable test key and cannot
authenticate an OpenAI request. Keep the OpenAI key server-only and never add
a NEXT_PUBLIC_ prefix.
ChatGPT and API billing are separate
A ChatGPT Plus, Pro or Team subscription does not include OpenAI API usage. The OpenAI Platform project that owns the key must have API billing enabled, available credit and a budget that permits requests.
Shipped Provider
The repository installs @ai-sdk/openai and configures OpenAI models in config/billing.config.ts. Anthropic, Google, Mistral and other provider packages are not included. Install and configure another provider package before using it in custom code.
See the AI SDK provider directory for provider-specific installation and configuration.
Verify the Integration
After adding OPENAI_API_KEY, restart the development server and verify the
complete chat flow:
- Create or select an organization with a positive credit balance.
- Open AI Chatbot, create a new chat and send a short prompt with GPT-4o Mini.
- Confirm assistant text streams into the page.
- Reload the chat and confirm both messages were persisted.
- Open Settings → Credits and confirm a usage transaction was recorded.
An HTTP 200 from /api/ai/chat alone does not prove generation succeeded.
Streaming responses send their headers before the provider has finished. If no
assistant text appears, verify the server-side key, OpenAI quota and access to
the selected model, then inspect the server logs for the provider error.
No assistant response
Use the provider error in the development server log to identify the failing layer:
| Provider error | Meaning | What to check |
|---|---|---|
invalid_api_key or HTTP 401 | OpenAI rejected the credential | Create a server key in the intended OpenAI Platform project, replace OPENAI_API_KEY and restart the development server |
insufficient_quota or HTTP 429 with a quota message | The key is valid but its project cannot spend | Enable API billing, add credit and confirm the project budget allows requests |
model_not_found or HTTP 404 | The project cannot use the selected model | Select a model listed in config/billing.config.ts that is available to the project |
insufficient_credits or HTTP 402 from Achromatic | The organization does not have enough application credits | Add credits in the application, then retry the message |
OpenAI API keys are scoped to a project. When you create a replacement key, verify that the selected project is the same project where API billing and the budget are configured. Never paste a real key into an issue, support message or client-side environment variable. Rotate any key that has been shared.
Provider errors are sanitized
The shipped route logs the original provider failure on the server and sends a reviewed quota, credential, model, rate-limit or generic message through the UI stream. Raw provider responses stay out of the browser because they can contain sensitive request details.