Integration guide
Connect NordAI to your app
Base URL and API key can use it — routers, gateways, IDE extensions, agent frameworks and your own backend. Follow the four steps below, then pick your client for the exact settings.1. Prerequisites
Before connecting, make sure you have:
- A NordAI account with a verified email address. Unverified accounts cannot call the gateway.
- An active plan or wallet balance. Free-plan accounts have a hard daily quota; prepaid accounts are charged per token from the wallet balance.
- A client that supports OpenAI-compatible endpoints: a custom base URL plus a bearer API key. Almost every AI router, IDE extension and agent framework does.
- One or more model ids from the NordAI catalogue, e.g.
nordai-claude-opus-5.
2. Create an API key
1Open the API keys page
2Create the key
my-router), optionally restrict it to specific model ids or set tighter per-minute / monthly limits than your plan, then press Create.3Copy it immediately
nord_sk_… is shown once. Only a SHA-256 hash is stored, so a lost key must be revoked and replaced. Store it in your secret manager or .env file — never commit it to git.NORDAI_API_KEY=nord_sk_your-key-here3. Configure your client
Every OpenAI-compatible client needs exactly three values. Set them in your client's provider / channel configuration:
Base URL: https://api.nordai.id/v1API Key: nord_sk_…Model: nordai-claude-opus-5 (pick from GET /v1/models)That is the whole contract: POST {base-url}/chat/completions with Authorization: Bearer nord_sk_…. Streaming (stream: true) works over SSE with no extra configuration. Tool / function calling is forwarded unchanged.
Copy model ids exactly
Model ids are lower-case and resolved case-insensitively server-side, but always copy them fromGET /v1/models — inventing an id (e.g. a different capitalisation or an older name such as nordai-opus-55) returns 404 model_not_found, which panels often misreport as an authentication failure.Full model catalogue
curl https://api.nordai.id/v1/models
# then {"models":[{"id":"nordai-claude-opus-5","display_name":"NordAI Claude Opus 5",...}, ...]}For the models your account (or a specific key) may actually call, use GET /v1/me/models with your key — it respects plan tier and key restrictions.
4. Verify the connection
One request, three things to check:
curl -s https://api.nordai.id/v1/chat/completions \
-H "Authorization: Bearer $NORDAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"nordai-claude-opus-5","messages":[{"role":"user","content":"ping"}],"max_tokens":16}'- HTTP 200 and a
choices[0].message.content— connected. The responsemodelfield echoes the id that served you. - Header
X-NordAI-Request-Idis your trace id for support; keep it if anything looks wrong. - The request appears within seconds in Dashboard Usage with its token counts.
A 401 means the key is wrong or revoked; 403 model_not_allowed means the key or plan does not include that model; 429 means you hit a rate or quota limit — see the error table in the API reference.
Per-client guides
Exact settings for the clients people ask about most.
AI router panels (One-API, New-API, LiteLLM proxy…)
The most common failure: API Type = “Responses API”. NordAI implements the Chat Completions protocol only. A panel set to Responses API probes POST /v1/responses, an endpoint NordAI does not have, and reports the false error “API key unauthorized” even though the key is fine. Always pick Chat Completions (some panels label it “OpenAI Chat” or just “OpenAI”).
Name: NordAI Prefix: nordai # model ids become nordai/nordai-claude-opus-5 in your panel API Type: Chat Completions ← NOT "Responses API" Base URL: https://api.nordai.id/v1 (must end in /v1) API Key: nord_sk_… (a key from dashboard/api-keys, not a device token) Model ID: nordai-claude-opus-5 (optional; or leave empty and import from /v1/models)
Checklist when “Check” fails
- “API key unauthorized” — 90% of the time this is API Type = Responses API. Switch to Chat Completions and re-check. If it still fails, verify the key starts with
nord_sk_, was copied whole (no spaces), and is still active on the API keys page. - 404 / “model not found” during check — the Model ID field must be a NordAI id such as
nordai-claude-opus-5, notgpt-4. Get valid ids fromGET https://api.nordai.id/v1/models. - Connection timeout — some panels reject self-signed or unusual TLS; NordAI uses a standard Cloudflare certificate, so a timeout usually means the Base URL is missing
/v1or the panel cannot reach the internet. - Model list is empty — import models manually: ids follow
nordai-<name>(e.g.nordai-claude-opus-5,nordai-deepsek-4-1-flash). The full catalogue is atGET /v1/models.
After the channel is added
Run one test chat from the panel on a NordAI model. Expect HTTP 200 and content in choices[0].message.content. Then the request shows up within seconds in Dashboard Usage — that is the confirmation that routing, key and billing are all live end to end.
Cursor / Cline / Continue / any IDE extension
Provider: OpenAI-compatible / Custom Base URL: https://api.nordai.id/v1 API Key: nord_sk_… Model: nordai-claude-opus-5
LiteLLM (Python)
import os
from litellm import completion
os.environ["OPENAI_API_KEY"] = "nord_sk_…"
resp = completion(
model="openai/nordai-claude-opus-5",
api_base="https://api.nordai.id/v1",
messages=[{"role": "user", "content": "hi"}],
)The openai/ prefix tells LiteLLM to speak the OpenAI protocol against your api_base.
OpenAI SDK (Python / Node)
# Python
from openai import OpenAI
client = OpenAI(base_url="https://api.nordai.id/v1", api_key="nord_sk_…")
# Node
import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://api.nordai.id/v1", apiKey: "nord_sk_…" });
const r = await client.chat.completions.create({
model: "nordai-claude-opus-5",
messages: [{ role: "user", content: "hi" }],
});Vercel AI SDK
import { createOpenAI } from "@ai-sdk/openai";
const nordai = createOpenAI({
baseURL: "https://api.nordai.id/v1",
apiKey: process.env.NORDAI_API_KEY,
});
await streamText({ model: nordai("nordai-claude-opus-5"), prompt: "…" });n8n / Make / no-code tools
Use the built-in OpenAI node, set "Base URL" (or "Override URL") to https://api.nordai.id/v1, paste your nord_sk_… key as the credential, and type the model id manually. No-code tools that hide the base URL need an HTTP Request node hitting https://api.nordai.id/v1/chat/completions directly with the bearer header.
Streaming & tools
Add "stream": true for server-sent events; chunks arrive as data: {...} lines ending with data: [DONE]. Tool definitions in tools are forwarded unchanged, and tool calls come back in choices[0].message.tool_calls exactly like the OpenAI protocol.
curl -N https://api.nordai.id/v1/chat/completions \
-H "Authorization: Bearer $NORDAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"nordai-claude-opus-5","stream":true,"messages":[{"role":"user","content":"count to 3"}]}'Retries are safe with an Idempotency-Key header: a repeated key returns 409 duplicate_request and is never billed twice.
Troubleshooting
| Symptom | Fix |
|---|---|
401 authentication_required | Key missing, mistyped or revoked. Re-copy from the dashboard; check there is no trailing space in the env var. |
403 model_not_allowed | The model id is not in your plan or the key's allowed list. Call GET /v1/me/models with the same key to see what it may use. |
403 email_unverified | Verify your email from the dashboard banner, then retry. |
429 …_limit_reached | Rate or quota limit. details.reset_at says when access resets; prepaid accounts need a wallet top-up instead. |
404 not_found on /chat/completions | Your base URL is missing /v1 (or doubled). The full URL must be https://api.nordai.id/v1/chat/completions. |
| Streaming never emits chunks | A proxy in front of your app is buffering SSE. Disable response buffering for text/event-stream, or test directly with curl -N first. |
502/503 upstream_unavailable | Transient gateway-side failure. Retry with backoff; the request was not charged. |
Still stuck? Send X-NordAI-Request-Id of a failing call via Dashboard Support.