Skip to main content

Overview

Build a minimal Next.js application using the App Router that accepts a prompt, routes requests through the ModelRunner server proxy, and displays the generated output.
You will keep your ModelRunner key on the server and route all client requests through the proxy. The client never sees secrets.

Prerequisites

  • Node.js 18+
  • Next.js 13.4+ (App Router)
  • ModelRunner account and API key
Find your key in your ModelRunner account. Store it as MODELRUNNER_KEY in your environment.

Steps

1

Create a Next.js app

Use the official Next.js starter with the App Router.
2

Install the ModelRunner client and proxy

3

Add environment variable

Create a .env.local file at the project root.
Do not commit .env.local. Next.js ignores it by default via .gitignore.
4

Add the proxy route (App Router)

Create a route under app/api/modelrunner/proxy/route.ts that re-exports the proxy handlers.
5

Configure the client to use the proxy

Set the proxy URL so client calls route through your server. Place this config in a client-side entry point (e.g., app/page.tsx) before making calls.
6

Build the UI: simple prompt form

Replace the home page with a form that calls the client (which uses the proxy) and renders results.
7

Run the app

Visit http://localhost:3000. Enter a prompt and submit. You should see the API response or an image.

Verification and troubleshooting

  • 401 Unauthorized: Confirm MODELRUNNER_KEY is set and your server restarted.
  • CORS issues: Calls are server-to-server. Ensure your browser calls /api/modelrunner, not the external API directly.
  • Unexpected response shape: Log result and adjust rendering. Some models return arrays or nested objects.
You can call the client from a Server Action for form submissions. Ensure modelrunner.config and secret usage remain server-only.

Reference

See the JavaScript client guide for more usage patterns.

JavaScript Client

Install and use the ModelRunner JS/TS SDK.

API Reference

Explore endpoints and request/response formats.