AI Routes in Next.js: Server Handlers and Streaming
By Darus S Alfatah · 2025-09-17 · Tutorial · 8 menit
Author note: In Next.js, call AI from a server route, not from a client component.
Server-Side by Default
Next.js makes it easy to expose logic to the browser, which is exactly the wrong place for an API key. Use a route handler that runs on the server, reads the key from the environment, and returns only what the client needs.
Send the minimum response: the answer text, maybe a token count. Internal metadata should stay in logs.
Validating Requests
Check that the payload is well formed, that message count and length are within limits, and that the requested model is on your allowlist. Letting clients choose any model invites abuse of the most expensive option.
Return clear error codes so the client can distinguish user error from provider failure.
Streaming
Return a readable stream and disable caching for that route. Streaming keeps the first token fast and avoids timeouts on long answers, which matters on serverless platforms with execution limits.
Handle mid-stream failures by appending a visible marker so the client can offer a retry instead of showing a silently truncated answer.
Serverless Limits
Watch the maximum duration. If a request may exceed it, move heavy work to a background job and notify the client when finished. For interactive chat, keeping answers short is usually the simplest fix.
Cold starts add latency; keep dependencies minimal in the AI route.
Cost Control
Log tokens per route and per user, then add a monthly budget alert. Without measurement, a single popular page can quietly become the largest line item.
Cache identical requests at the edge only if the content is not user-specific.
Frequently Asked Questions
Edge or Node runtime? Node for full SDK support; edge for simple low-latency calls.
Can I call the model from a client component? Only through your own route, never with a key.
How do I prevent abuse? Authentication, rate limits, and an input size cap.
Do I need a database? Only for persistence of history or quotas.
How do I test it? Mock the provider in unit tests and run one real call manually.
Conclusion
Next.js is a good home for AI features if you keep secrets server-side, validate input, stream answers, and respect platform limits.
Operational Details
Add structured logging with request ids so a user complaint can be traced to a specific call. Log the model name, latency, and token counts, but never the API key or full personal data.
Set a timeout slightly below your platform limit so your code can return a controlled error instead of being killed mid-response. A controlled error is easier to retry and easier to explain.
Finally, keep prompts in version-controlled files. When behaviour changes after an edit, comparing versions is the fastest way to find the cause.
Handling Repeated Failures
If the provider returns errors repeatedly, stop retrying and show a fallback message. Automated retries during an outage multiply cost and delay the moment when someone notices the problem.
Alert on error rate rather than on individual failures, otherwise notifications become noise nobody reads.
An example route handler: Create app/api/chat/route.ts that calls the gateway from the server. The client component only calls your own endpoint.
Frequently Asked Questions
Can beginners follow this tutorial?
Yes. The steps are explained in order with code examples, suitable for beginners and experienced developers alike.
Is BankAI’s endpoint compatible with the library I already use?
Yes, BankAI is 100% OpenAI-compatible, so libraries such as the OpenAI SDK and LangChain work without code changes beyond the Base URL and API key.
Where do I get an API key to follow this tutorial?
You get the API key (and Secret Token) after registering and completing payment in the BankAI dashboard.