Skip to content
Free$1 of credit for every new organization
All articles

Guide

Using the Vercel AI SDK in a Next.js app

Stream answers from any Usefully model into a Next.js page with the Vercel AI SDK's OpenAI-compatible provider. Route handler, client and environment setup.

· 3 min read · Usefully team


The Vercel AI SDK is a popular way to add streaming AI features to a Next.js app. It talks to models through providers, and because Usefully is OpenAI-compatible, the SDK's OpenAI provider works with a different base URL. That gives your Next.js app every model on Usefully, with failover and one balance, without a new dependency.

1. Install and configure

npm install ai @ai-sdk/openai

Add your key to .env.local. It's a server-only variable: no NEXT_PUBLIC_ prefix, so it never reaches the browser.

USEFULLY_API_KEY=your-key-here

Create the provider once and import it wherever you need a model:

import { createOpenAI } from "@ai-sdk/openai";

export const usefully = createOpenAI({
  baseURL: "https://api.usefully.info/v1",
  apiKey: process.env.USEFULLY_API_KEY,
});

2. A streaming route handler

Use the provider's .chat() model so requests go to /v1/chat/completions, which every Usefully model supports:

import { streamText } from "ai";
import { usefully } from "@/lib/usefully";

export async function POST(req: Request) {
  const { question } = await req.json();

  const result = streamText({
    model: usefully.chat("anthropic/claude-sonnet-5-5"),
    system: "You are a concise assistant. Answer in under 150 words.",
    prompt: question,
    maxOutputTokens: 400,
  });

  return result.toTextStreamResponse();
}

Option names change between AI SDK major versions (older versions call the output cap maxTokens). Check the version you have installed.

3. Read the stream in the page

"use client";
import { useState } from "react";

export default function Ask() {
  const [answer, setAnswer] = useState("");

  async function ask(question: string) {
    setAnswer("");
    const res = await fetch("/api/ask", { method: "POST", body: JSON.stringify({ question }) });
    const reader = res.body!.getReader();
    const decoder = new TextDecoder();
    for (;;) {
      const { done, value } = await reader.read();
      if (done) break;
      setAnswer((a) => a + decoder.decode(value, { stream: true }));
    }
  }

  return (
    <form action={(f) => ask(String(f.get("q")))}>
      <input name="q" placeholder="Ask something" />
      <p>{answer}</p>
    </form>
  );
}

For full chat UIs, the AI SDK's React hooks work with the same route; return the response type the hook expects for your SDK version.

Switching models

Because every model goes through the same provider, trying another is a one-string change: usefully.chat("openai/gpt-5-mini") or usefully.chat("google/gemini-2.5-flash"). Keep the model ID in an environment variable and you can switch without a deploy.

Production notes

  • Keep the key on the server. Route handlers and server actions only.
  • Set an output cap on every call. It bounds both cost and latency.
  • Use a separate key per environment, with a daily spend limit on preview and staging deployments.
  • Errors: if the provider fails mid-stream, the stream ends early. Show what arrived and offer a retry.
  • Serverless timeouts: make sure your function's maximum duration covers a long answer plus failover, or the platform will cut the stream off first.

Why go through Usefully at all

You could point the AI SDK at each provider directly, with one provider package and one key per vendor. Going through Usefully trades that for a single provider configuration. Every model, from Anthropic, OpenAI or Google, is reached with the same usefully.chat() call, billed from one prepaid balance at the provider's list price, and recorded in one set of logs with its tokens, cost and latency. If a provider serving your model fails, the request moves to another one before your route handler sees an error.

Using web search in the same app

Web search uses the same key. A server action or route handler can call POST /v1/search with fetch, pass the results into the prompt, and stream the answer with streamText. Because both calls draw on the same balance and appear in the same Logs, you can see the full cost of an answer, search included, in one place. The search guide lists the request fields.

Testing locally

Use a separate development key in .env.local, with a small daily spend limit, and keep production keys only in your hosting provider's environment settings. Preview deployments should get their own key too, so a busy branch can't spend production's budget.

Pick a model on the models page, and see the quickstart for other SDKs. Your first organization gets $1 of free credit: sign up.

More articles

Get started

Your first request is five minutes away.

  • $1 of free credit to start
  • No card, no subscription
  • Keep the SDK you already use
  • Real people at support@usefully.info
Using the Vercel AI SDK in a Next.js app · Usefully