Get started with Neon AI Gateway

To set up Neon AI Gateway with an AI coding assistant, install the Neon Platform (neon) and Neon AI Gateway skills:

npx skills add neondatabase/agent-skills -s neon -s neon-ai-gateway

1. Get access

   You need a project in the AWS us-east-2 region. Foundation model access requires a paid Neon plan, and it's enabled automatically once you're on one, no separate sign-up step needed.

2. Create a credential

   In the Neon Console, select your branch, click Credentials under APP BACKEND, then click Create credential and check ai_gateway:invoke. Copy the credential before closing — it's shown only once.

   Or use the API:

   curl -X POST "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/credentials" \
     -H "Authorization: Bearer $NEON_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"scopes": ["ai_gateway:invoke"], "principal_type": "user"}'

   Using neon.ts?

   ---

   If your project has a neon.ts file, declare preview: { aiGateway: true } and run neon deploy. Credentials are provisioned and pulled into your local .env automatically — no manual creation needed. See Authentication for details.

   Store the credential as an environment variable:

   export NEON_AI_GATEWAY_TOKEN=nt_live_...

3. Find your branch host

   Your branch's AI Gateway host is available in the Neon Console on the AI Gateway page, or via the Neon API. It follows this format:

   br-<name>-api.ai.<cell>.<region>.aws.neon.tech

   For example:

   export NEON_AI_GATEWAY_BASE_URL=https://br-winter-pond-aptw82ef-api.ai.c-2.us-east-2.aws.neon.tech

   This is different from your database connection string.

4. Install dependencies

   The quickstart uses the OpenAI SDK because the chat completions endpoint is OpenAI-compatible. It works with any model in the catalog, including GPT and Gemini.

   npmyarnpnpmpip

   npm install openai dotenv

5. Make your first request

   The chat completions endpoint is OpenAI-compatible. Set baseURL to your branch host and apiKey to your credential. No other changes needed.

   TypeScriptPythoncURL

   import OpenAI from 'openai';
   import 'dotenv/config';
   
   const client = new OpenAI({
     apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
     baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
   });
   
   const response = await client.chat.completions.create({
     model: 'gpt-5-mini',
     messages: [{ role: 'user', content: 'Hello!' }],
   });
   
   console.log(response.choices[0].message.content);

6. Stream a response

   Add stream: true to receive a streamed response. Your existing streaming code works without changes. The gateway forwards text/event-stream responses from the upstream provider.

   TypeScriptPythoncURL

   import OpenAI from 'openai';
   import 'dotenv/config';
   
   const client = new OpenAI({
     apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
     baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
   });
   
   const stream = await client.chat.completions.create({
     model: 'gpt-5-mini',
     messages: [{ role: 'user', content: 'Write a haiku about serverless databases.' }],
     stream: true,
   });
   
   for await (const chunk of stream) {
     process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
   }

7. Swap models

   Change the model field to use a different provider. No other code changes required.

   // OpenAI
   model: 'gpt-5-mini'
   
   // Google
   model: 'gemini-3-flash'
   
   // Alibaba
   model: 'qwen3-next-80b-a3b-instruct'

   See Models for the full list of available model IDs.

   Using the AI SDK?

   ---

   For TypeScript apps and agents, use @neon/ai-sdk-provider with the Vercel AI SDK. It reads NEON_AI_GATEWAY_BASE_URL and NEON_AI_GATEWAY_TOKEN, then routes each catalog model to the best AI Gateway endpoint for that provider.

Next steps

• Models: full model catalog and which endpoint to use per provider
• Chat completions: detailed reference for the unified endpoint
• Authentication: credential scopes, branch binding, and rotation