Skip to main content

OpenAI SDK Integration

The OpenAI SDK is the reference integration path used in the Quickstart, but the same pattern applies to any provider the gateway supports - only the URL segment and headers change. See Other Providers for the full list of supported providers and their URL segments.

Copy-paste examples for other languages: Python · PHP · Node.js · Go.

Configuration​

Two things change from a direct OpenAI integration:

  1. baseURL points at your Observra Gateway instead of https://api.openai.com/v1, with /openai as the provider segment.
  2. A Gateway Key is added, via a header, alongside your unchanged OpenAI API key.
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.observra.in/openai/v1",
  apiKey: process.env.OPENAI_API_KEY, // unchanged - your own OpenAI key
  defaultHeaders: {
    "X-Gateway-Key": process.env.OBSERVRA_GATEWAY_KEY,
  },
});

const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Summarize this in one sentence." }],
});

Everything else - streaming, tool calls, function calling, structured outputs - works exactly as it does calling OpenAI directly, because the gateway is a transparent proxy when the client and upstream protocols match (see Routing & Providers).

Alternative ways to pass the Gateway Key​

If your environment can't set a custom header, the gateway also accepts:

  • Authorization: Bearer <gateway-key> instead of apiKey + X-Gateway-Key (note: this is a different bearer than your OpenAI key - the OpenAI SDK's own Authorization header carries your OpenAI key, so use X-Gateway-Key in the common case to avoid collision).
  • A compound bearer: Authorization: Bearer <gateway-key>||<provider-key> if you want to pass both credentials in one place.
  • A body fallback field (gateway_key) for clients that can't set headers at all.

See Gateway Authentication for the full precedence order.

Streaming​

Set stream: true as usual:

const stream = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Count to five." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

The gateway relays SSE chunks as they arrive and extracts token/usage metrics from the same stream without altering what your client receives.

What the gateway does not change​

  • Your OpenAI API key is forwarded upstream on every request; Observra never stores or logs it.
  • Response bodies are not persisted by default - only metadata (tokens, cost, latency, status). Full payload capture is opt-in per Environment.
  • Error responses from OpenAI pass through unchanged; the gateway also records the failure as an observation with status: "failed" and the error message.

Trace correlation​

If you're already instrumented with OpenTelemetry, sending a traceparent header on your OpenAI calls lets you correlate the resulting observation with your broader trace - see Trace Context.