OpenAI Responses API

The OpenAI Responses endpoint exposes the OpenAI Responses API through Neon AI Gateway. Use it with the OpenAI SDK's responses.create() method by changing only the baseURL. Base URL https ///openai/v1...

The OpenAI Responses endpoint exposes the OpenAI Responses API through Neon AI Gateway. Use it with the OpenAI SDK's responses.create() method by changing only the baseURL.

Base URL: https://<branch-host>/openai/v1

This endpoint is also reachable at the longer /ai-gateway/openai/v1/responses path. Both behave identically and neither is deprecated. See Shorter paths for the full list of aliases.

If you're using an OpenAI-compatible client that accepts a base URL, set it to either https://<branch-host>/openai/v1 or https://<branch-host>/ai-gateway/openai/v1. The request and response shapes are the standard OpenAI Responses API shape.

Setup

Set these environment variables. See Get started for how to obtain them.

Bash

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

Supported models

This endpoint accepts OpenAI models only:

Model ID	Notes
`gpt-6-astra`
`gpt-5-6-sol`
`gpt-5-6-terra`
`gpt-5-6-luna`
`gpt-5-5`
`gpt-5-5-pro`	Requires this endpoint
`gpt-5-4`
`gpt-5-4-mini`
`gpt-5-4-nano`
`gpt-5-3-codex`	Requires this endpoint
`gpt-5-2`
`gpt-5-1`
`gpt-5`
`gpt-5-mini`
`gpt-5-nano`

Sending a non-OpenAI model ID returns 400 model "<model-id>" is not available on the openai_responses endpoint.

Basic request

TypeScript (OpenAI SDK)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const response = await client.responses.create({
  model: 'gpt-5-4',
  input: [{ role: 'user', content: 'What is Neon?' }],
});

console.log(response.output_text);

Python (OpenAI SDK)

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ['NEON_AI_GATEWAY_TOKEN'],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

response = client.responses.create(
    model='gpt-5-4',
    input=[{'role': 'user', 'content': 'What is Neon?'}],
)

print(response.output_text)

cURL

curl -X POST "$NEON_AI_GATEWAY_BASE_URL/openai/v1/responses" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-4",
    "input": [{"role": "user", "content": "What is Neon?"}]
  }'

Streaming

TypeScript (OpenAI SDK)

const stream = await client.responses.create({
  model: 'gpt-5-4',
  input: [{ role: 'user', content: 'Explain database branching.' }],
  stream: true,
});

for await (const event of stream) {
  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta);
  }
}

Python (OpenAI SDK)

with client.responses.stream(
    model='gpt-5-4',
    input=[{'role': 'user', 'content': 'Explain database branching.'}],
) as stream:
    for event in stream:
        if event.type == 'response.output_text.delta':
            print(event.delta, end='', flush=True)

cURL

curl -X POST "$NEON_AI_GATEWAY_BASE_URL/openai/v1/responses" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-4",
    "input": [{"role": "user", "content": "Explain database branching."}],
    "stream": true
  }'

Image generation with Vercel AI SDK

The @neon/ai-sdk-provider package re-exports the OpenAI provider's Responses image-generation tool as neon.tools.imageGeneration(). Use it with OpenAI-routed models such as gpt-5-mini.

Use streamText, not generateText: image results are returned as tool-result parts, and a full base64 image reliably runs into size limits on a non-streaming response.

TypeScript

import { neon } from '@neon/ai-sdk-provider';
import { streamText } from 'ai';

const result = streamText({
  model: neon('gpt-5-mini'),
  messages: [{ role: 'user', content: 'Create a simple Neon database mascot.' }],
  tools: {
    image: neon.tools.imageGeneration({
      outputFormat: 'jpeg',
      size: '1024x1024',
      partialImages: 3,
    }),
  },
});

return result.toUIMessageStreamResponse();

AI SDK generateImage() is not supported by AI Gateway; image generation is available only through this Responses tool.

Error handling

Status	Message	Cause
`400 Bad Request`	`unknown model "<model-id>"`	Model ID not in the catalog
`400 Bad Request`	`model "<model-id>" is not available on the openai_responses endpoint`	Non-OpenAI model sent to this endpoint

For authentication, quota, and upstream errors, see Troubleshooting.

Next steps

Models: full model catalog and which models require this endpoint
Chat completions: use any model via the unified OpenAI-compatible endpoint
Authentication: credential scopes and branch binding

Need help?

Join our Discord Server to ask questions or see what others are doing with Neon. For paid plan support options, see Support.