Skip to content
IQ

OpenAI · Node

The OpenAI Node/TypeScript SDK accepts baseURL and apiKey on the client constructor. Swap the base URL and your existing call sites route through the gateway. This recipe ships a runnable TypeScript file that you can drop into a fresh pnpm init project with openai installed.

Drop-in switch

const client = new OpenAI({
  baseURL: "https://gateway.iq-routing.com/v1",
  apiKey: process.env.IQ_API_KEY,
});

IQ_API_KEY holds your gateway key (gw_live_xxxxxxxx). See Authentication for how to generate one and where to store it.

Everything below this line (client.chat.completions.create, client.models.list) routes through the gateway. The gateway does not implement /v1/embeddings, so leave embedding calls pointed at your provider.

Verify it routes

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.iq-routing.com/v1",
  apiKey: process.env.IQ_API_KEY!,
  timeout: 60_000,
  maxRetries: 0,
});

const response = await client.chat.completions
  .create({
    model: "auto",
    messages: [{ role: "user", content: "Summarise: routing-aware gateway." }],
    max_tokens: 64,
  })
  .withResponse();

console.log("X-Request-Id:", response.response.headers.get("x-request-id"));
const telemetry = JSON.parse(response.response.headers.get("x-iq-routing") ?? "{}");
console.log("Model picked:", telemetry.chosen_model);
console.log("Provider:", telemetry.chosen_provider);
console.log("Cache hit:", telemetry.cache_hit);
console.log(response.data.choices[0].message.content);

Run with IQ_API_KEY=... npx tsx verify.ts. The gateway emits two response headers per request: X-Request-Id (the correlation handle) and x-iq-routing (a JSON-encoded telemetry blob with the chosen model, provider, complexity tier, cache-hit flag, latencies, and cost). The body is the standard OpenAI chat completion shape.

Using capability aliases

Pass cap:<name> in the model field to request a capability; inspect the response model to see which model answered and manage your organization's overrides at /settings/capabilities.

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "https://gateway.iq-routing.com/v1",
  apiKey: process.env.IQ_API_KEY!,
});

const completion = await openai.chat.completions.create({
  model: "cap:reason-heavy",
  messages: [{ role: "user", content: "Plan the migration in three phases." }],
});

The resolved provider plus model surface in the x-iq-routing response header (a JSON-encoded payload with chosen_provider and chosen_model fields, among others), so the SDK consumer can inspect which concrete model handled the request via .withResponse(). Decode the header with JSON.parse(response.response.headers.get("x-iq-routing")). See the capability aliases docs for the full list of default mappings and how to override them. You can override the default capability mapping for your org in the dashboard at /settings/capabilities.

Common gotchas

A missing or invalid Authorization header returns 401 before the request reaches routing -- no provider call is made and nothing is billed. See the API reference for the full set of status codes and error body shapes.

The gateway allows up to 600 seconds per provider attempt and 1800 seconds across the fallback loop; streaming limits cover upstream stream readiness rather than the full token stream, so set an explicit client timeout if you need a shorter limit.

When every upstream provider in the fallback chain is exhausted before that ceiling is hit, the gateway returns 503 with an overloaded_error type in the response body, and no Retry-After header -- back off on your own schedule for that case.

The SDK's maxRetries defaults to 2. The gateway's rate-limit and daily-budget 429s carry a Retry-After header set to the exact cooldown; monthly-budget and spend-ceiling 429s do not. SDK-side retries on top of that just burn calls inside the same cooldown window. Set maxRetries: 0 and let your own queue handle backoff.

Streaming uses the standard stream: true flag. The gateway forwards the chunked SSE; the X-Request-Id arrives on the response headers before the first chunk, so you can log the correlation handle even on a streamed response.

If you use the SDK in a Next.js streaming route handler, use the Node runtime by setting runtime: "nodejs" on the route.

Try this in the playground

Run this snippet against your gateway key →