Skip to main content
Use this page when you want a small Next.js chat app that feels real, but still keeps your Phaseo API key on the server. Goal: Run a browser chat app that discovers models and sends responses through server-side routes. Outcome: A working local chat interface with no Phaseo credentials exposed to the browser.

Build a Next.js web chat app on top of Phaseo Gateway.

Open in Cursor

​
Sample project

​
What this app does

  • fetches available models from GET /v1/models
  • submits chat turns through POST /v1/responses
  • keeps the API key on the server
  • gives you a simple starting point for a real product without OAuth complexity

​
Key files

  • app/api/models/route.ts
  • app/api/responses/route.ts
  • app/components/ChatClient.tsx
  • lib/gateway.ts

​
Why the sample is structured this way

​
1. The browser does not call Phaseo directly

The UI talks to your own Next.js routes first. Those routes call Phaseo on the server. This gives you:
  • server-side secret handling
  • one place to manage headers and request payloads
  • an easier upgrade path if you later add auth, rate limits, or logging

​
2. Model discovery is separated from generation

Keep model listing and chat generation in separate routes so each part stays easy to understand:
  • one route for listing models
  • one route for running the chat request

​
3. The UI owns interaction state only

The React client handles:
  • input state
  • loading state
  • error presentation
  • rendered messages
The server route handles the AI call. The browser just handles the user experience.

​
Prerequisites

  • Node.js and one supported package manager
  • a Phaseo API key

​
Run the sample

Set:
  • PHASEO_API_KEY
  • NEXT_PUBLIC_GATEWAY_URL
Then run:
Open http://localhost:3000.

​
Check your work

  • The model picker loads models from the server route.
  • Sending a message produces one assistant response.
  • The browser network panel does not expose PHASEO_API_KEY.
  • A failed gateway request appears as a useful error state in the UI.

​
How to make it your own

  • switch the default model to your chosen production target
  • add streaming if your UX needs token-by-token output
  • add auth later if the app becomes multi-user
  • swap the server route internals to the TypeScript SDK later if you want a higher-level client

​
When to use a different starting point

  • use the Node quickstart when you want a script or backend smoke test, not a UI
  • use the Python quickstart when the first integration lives in a worker, CLI, or backend service
Last modified on July 26, 2026