diff --git a/docs/docs.json b/docs/docs.json index 2e7b990055..0912d04b7e 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -192,6 +192,7 @@ "getting-started/integration-method/hyperbolic", "getting-started/integration-method/mistral", "getting-started/integration-method/nebius", + "getting-started/integration-method/neon", "getting-started/integration-method/novita", { "group": "Nvidia", diff --git a/docs/getting-started/integration-method/neon.mdx b/docs/getting-started/integration-method/neon.mdx new file mode 100644 index 0000000000..ffdd146cd0 --- /dev/null +++ b/docs/getting-started/integration-method/neon.mdx @@ -0,0 +1,130 @@ +--- +title: "Neon AI Gateway Integration" +sidebarTitle: "Neon AI Gateway" +description: "Log Neon AI Gateway requests in Helicone by routing them through the Helicone Gateway. Neon serves an OpenAI-compatible endpoint, so the standard proxy headers apply." +"twitter:title": "Neon AI Gateway Integration - Helicone OSS LLM Observability" +--- + +[Neon AI Gateway](https://neon.com/docs/ai-gateway/overview) is an OpenAI-compatible inference endpoint provided by Neon. A single Neon credential gives access to models from OpenAI, Google, Meta, Databricks, and Alibaba. + + + Neon AI Gateway is in beta. It requires a paid Neon plan and a project in the AWS US East (Ohio) region (`aws-us-east-2`). + + +Neon is not one of Helicone's registered providers, so it is not selectable in the [AI Gateway](/gateway/overview) model registry. Route it through the [Helicone Gateway](/getting-started/integration-method/gateway) instead, which proxies any OpenAI-compatible host you name in a header. + +## Gateway integration + + + + Log into [Helicone](https://www.helicone.ai) or create an account, then generate an [API key](https://helicone.ai/developer). + + + In the Neon Console, select your branch, open **Credentials** under **APP BACKEND**, and create a credential with the `ai_gateway:invoke` scope. See [AI Gateway authentication](https://neon.com/docs/ai-gateway/authentication). + + + Each Neon branch has its own gateway host, shown in the Neon Console as `NEON_AI_GATEWAY_BASE_URL` and written below as `https://`. There is no shared Neon hostname to point at. + + +```bash +HELICONE_API_KEY="" +NEON_AI_GATEWAY_TOKEN="nt_live_..." +NEON_AI_GATEWAY_BASE_URL="https://" +``` + + + +Replace the Neon branch host with `https://gateway.helicone.ai` and pass the branch host in `Helicone-Target-Url`: + +`$NEON_AI_GATEWAY_BASE_URL/v1/chat/completions` -> `https://gateway.helicone.ai/v1/chat/completions` + +``` +Helicone-Auth: `Bearer ${HELICONE_API_KEY}` +Helicone-Target-Url: `${NEON_AI_GATEWAY_BASE_URL}` +Authorization: `Bearer ${NEON_AI_GATEWAY_TOKEN}` +``` + + + + +## Example + + + + +```bash +curl --request POST \ + --url https://gateway.helicone.ai/v1/chat/completions \ + --header "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \ + --header "Helicone-Auth: Bearer $HELICONE_API_KEY" \ + --header "Helicone-Target-Url: $NEON_AI_GATEWAY_BASE_URL" \ + --header "Content-Type: application/json" \ + --data '{ + "model": "gpt-5-mini", + "messages": [{ "role": "user", "content": "What is the capital of France?" }] + }' +``` + + + + +```typescript +import OpenAI from "openai"; + +const openai = new OpenAI({ + apiKey: process.env.NEON_AI_GATEWAY_TOKEN, + baseURL: "https://gateway.helicone.ai/v1", + defaultHeaders: { + "Helicone-Auth": `Bearer ${process.env.HELICONE_API_KEY}`, + "Helicone-Target-Url": process.env.NEON_AI_GATEWAY_BASE_URL, + }, +}); + +const completion = await openai.chat.completions.create({ + model: "gpt-5-mini", + messages: [{ role: "user", content: "What is the capital of France?" }], +}); +``` + + + + +```python +import os +from openai import OpenAI + +client = OpenAI( + api_key=os.environ["NEON_AI_GATEWAY_TOKEN"], + base_url="https://gateway.helicone.ai/v1", + default_headers={ + "Helicone-Auth": f"Bearer {os.environ['HELICONE_API_KEY']}", + "Helicone-Target-Url": os.environ["NEON_AI_GATEWAY_BASE_URL"], + }, +) + +completion = client.chat.completions.create( + model="gpt-5-mini", + messages=[{"role": "user", "content": "What is the capital of France?"}], +) +``` + + + + +Streaming works the same way: add `stream: true` and Neon forwards `text/event-stream` responses through the gateway. + +## Rate limits on Neon branch hosts + +Neon branch hosts are not on Helicone's [approved domain list](/getting-started/integration-method/gateway#approved-domains), and each Neon branch has a different hostname, so requests fall under the unapproved-domain limits of 10,000 requests per day and 1 request per second. To lift those limits for your branch hosts, contact engineering@helicone.ai or ask on [Discord](https://discord.gg/zsSTcH2qhG). + +If you need higher throughput before a domain is approved, use a [manual logger](/getting-started/integration-method/manual-logger-typescript) instead. It logs requests asynchronously and leaves the call path to Neon untouched. + +## Models + +Neon uses short model IDs such as `gpt-5-mini`, `gemini-3-flash`, and `qwen3-next-80b-a3b-instruct`. List what your branch can reach with `GET $NEON_AI_GATEWAY_BASE_URL/v1/models`, or browse the [Neon model catalog](https://neon.com/docs/ai-gateway/models). Model IDs, pricing, and capabilities are also published as the [`neon` provider on Models.dev](https://models.dev/providers/neon/). + + + Cost calculation is not enabled for Neon branch hosts, so requests logged this way show token counts without a cost figure. Helicone's automated mapper still resolves the request and response schema, which can take up to 24 hours to appear in the UI. + + +For more on the headers used above, see [Helicone Headers](https://docs.helicone.ai/helicone-headers/header-directory#utilizing-headers).