Quickstart

The Vercel AI SDK is a collection of tools to help you build AI-powered user interfaces.

In this quickstart tutorial, you'll build a simple sample AI-powered slogan generator with a streaming user interface. Along the way, you'll learn key guides and techniques that are fundamental to using the SDK in your own projects.

If you are unfamiliar with the concepts of Prompt Engineering and HTTP Streaming, you can optionally read these documents first.

💡

The below example uses a completion API and the useCompletion hook. If you want to see a chat example (using ChatGPT 3.5-turbo), see a chat guide (opens in a new tab).

Build your app

Before we raise a frothy seed round and build a billion dollar business, we need to set-up our project. We've written some code to get you started — follow the instructions below to download the code and run the app.

Prerequisites

Before you start, make sure you have the following:

Node.js 18+ installed on your local development machine.
An OpenAI API key.

If you haven't obtained your OpenAI API key, you can do so by signing up (opens in a new tab) on the OpenAI website.

Create an Application

We'll start by creating a new Next.js application. This command will create a new directory named my-ai-app and set up a basic Next.js application inside it.

pnpm dlx create-next-app my-ai-app

Navigate to the newly created directory:

cd my-ai-app

Install Dependencies

Next, we'll install ai and openai, OpenAI's official JavaScript SDK compatible with the Vercel Edge Runtime.

pnpm install ai openai

Configure OpenAI API Key

Create a .env.local file in your project root and add your OpenAI API Key. This key is used to authenticate your application with the OpenAI service.

touch .env.local

Edit the .env.local file:

.env.local

OPENAI_API_KEY=xxxxxxxxx

Replace xxxxxxxxx with your actual OpenAI API key.

Create an API Route

Create a Next.js Route Handler, app/api/completion/route.ts. This handler will be using the Edge Runtime to generate a text completion via OpenAI, which will then be streamed back to Next.js.

Here's what the route handler should look like:

app/api/completion/route.ts

import OpenAI from 'openai';
import { OpenAIStream, StreamingTextResponse } from 'ai';
 
// Create an OpenAI API client (that's edge friendly!)
const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});
 
// Set the runtime to edge for best performance
export const runtime = 'edge';
 
export async function POST(req: Request) {
  const { prompt } = await req.json();
 
  // Ask OpenAI for a streaming completion given the prompt
  const response = await openai.completions.create({
    model: 'text-davinci-003',
    stream: true,
    temperature: 0.6,
    max_tokens: 300,
    prompt: `Create three slogans for a business with unique features.
 
Business: Bookstore with cats
Slogans: "Purr-fect Pages", "Books and Whiskers", "Novels and Nuzzles"
Business: Gym with rock climbing
Slogans: "Peak Performance", "Reach New Heights", "Climb Your Way Fit"
Business: ${prompt}
Slogans:`,
  });
  // Convert the response into a friendly text-stream
  const stream = OpenAIStream(response);
  // Respond with the stream
  return new StreamingTextResponse(stream);
}

In the above code, the openai.completions.create method gets a response stream from the OpenAI API. We then pass the response into the OpenAIStream provided by this library. Then we use StreamingTextResponse to set the proper headers and response details in order to stream the response back to the client.

Wire up a UI

Finally, create a client component with a form to collect the prompt from the user and stream back the completion.

app/page.tsx

'use client'
 
import { useCompletion } from 'ai/react';
 
export default function SloganGenerator() {
  const { completion, input, handleInputChange, handleSubmit } = useCompletion();
 
  return (
    <div className="mx-auto w-full max-w-md py-24 flex flex-col stretch">
      <form onSubmit={handleSubmit}>
        <input
          className="fixed w-full max-w-md bottom-0 border border-gray-300 rounded mb-8 shadow-xl p-2 dark:text-black"
          value={input}
          placeholder="Describe your business..."
          onChange={handleInputChange}
        />
      </form>
      {completion ? (
        <div className="whitespace-pre-wrap my-4">{completion}</div>
      ) : (
        <div>Enter a business description and click enter to generate slogans.</div>
      )}
    </div>
  );
}

This component utilizes the useCompletion hook, which will, by default, use the POST route handler we created earlier. The hook provides functions and state for handling user input and form submission. The useCompletion hook provides multiple utility functions and state variables:

completion - This is the current completion result, a string value representing the generated text.
input - This is the current value of the user's input field.
handleInputChange and handleSubmit - These functions handle user interactions such as typing into the input field and submitting the form, respectively.
isLoading This boolean indicates whether the API request is in progress or not.

Running the Application

To start your application, use the command:

pnpm run dev

Now your application is up and running! Test it by entering a business description and see the AI-generated slogans in real-time.

Nice! You've built a streaming slogan generator using the Vercel AI SDK. Remember, your imagination is the limit when it comes to using AI to build apps, so feel free to experiment and extend the functionality of this application further. In the next section of the tutorial, we're going to pivot our little company to chat.

Introduction Concepts