Kenhuang Academy
  • English

      • Installation

      Requirements

      • Node.js 22+ (tested on 22 / 24 / 26; follow current LTS in production)
      • pnpm (official quickstart default; npm / bun / yarn also work)
      • At least one secret: AI_GATEWAY_API_KEY (Gateway) or a vendor key such as OPENAI_API_KEY

      AI SDK 7 is ESM-only. Next.js App Router apps are usually already ESM. For a plain Node script, set "type": "module" in package.json or use .mjs. require('ai') fails.

      Official App Router quickstart:

      pnpm create next-app@latest my-ai-app
cd my-ai-app

      Choose App Router and Tailwind if prompted. See this site’s Next.js tutorial for framework details.

      Install AI SDK packages

      pnpm add ai @ai-sdk/react zod
      PackageRole
      aiCore: streamText / generateText. The Gateway provider ships in this package.
      @ai-sdk/reactReact hooks such as useChat
      zodTool inputSchema and structured output

      For direct OpenAI (not Gateway strings), also install:

      pnpm add @ai-sdk/openai

      Configure secrets

      Create .env.local at the project root (Next.js loads it; do not commit it):

      # Vercel AI Gateway (official quickstart default)
AI_GATEWAY_API_KEY=xxxxxxxxx

# If you use @ai-sdk/openai directly
OPENAI_API_KEY=sk-...

      Gateway reads AI_GATEWAY_API_KEY by default. Direct OpenAI reads OPENAI_API_KEY.

      Temporary PowerShell:

      $env:AI_GATEWAY_API_KEY = "xxxxxxxxx"

      Secrets belong in route handlers, Server Actions, and Node scripts only. Never prefix them with NEXT_PUBLIC_.

      Two ways to name a model (do not mix them up)

      1. Gateway (default global provider) — a string, no vendor package:

      import { generateText, gateway } from 'ai';

await generateText({
  model: 'openai/gpt-4.1-mini', // or gateway('anthropic/claude-sonnet-4.5')
  prompt: 'Say hello in one sentence.',
});

      gateway('anthropic/claude-sonnet-4.5') is equivalent to the string form. You can also import { gateway } from '@ai-sdk/gateway'.

      2. Direct OpenAI — install @ai-sdk/openai:

      import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

await generateText({
  model: openai('gpt-5.1'), // example ID from official docs; IDs change
  prompt: 'Say hello in one sentence.',
});

      Gateway "openai/gpt-4.1-mini" is not openai('gpt-4.1-mini'). The first routes through Gateway; the second hits the OpenAI API. Mixing them connects the wrong backend or yields “model not found”.

      Plain Node (no Next.js)

      mkdir ai-script && cd ai-script
pnpm init
pnpm add ai

      Add "type": "module" to package.json. Use the same generateText API. Chat UI is what needs @ai-sdk/react and React.

      Suggested layout

      my-ai-app/
├── .env.local          # secrets, gitignored
├── app/
│   ├── api/chat/route.ts
│   └── page.tsx        # 'use client' + useChat
├── package.json
└── tsconfig.json

      See the TypeScript and Next.js tutorials for language and App Router conventions.

      Troubleshooting

      ERR_REQUIRE_ESM / require is not defined?
      The project is not ESM. Add "type": "module", or use import only under Next.js app/.

      Node too old?
      node -v must be ≥ 22.

      Gateway 401?
      Check the filename .env.local, restart pnpm dev, and confirm the key is an AI Gateway key.

      Direct OpenAI timeouts?
      You may need a proxy, Gateway, or local Ollama (see Providers).

      Next

      评论