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
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.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_KEYis 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
resultand adjust rendering. Some models return arrays or nested objects.
Using server actions instead of API route
Using server actions instead of API route
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.

