Client configuration

You configure the SDK in two places: options you pass to new Glexir(), which apply to every request, and request options you pass as the last argument of any method, which apply to one call.

import Glexir from "@glexir/sdk";

const glexir = new Glexir({
  apiKey: process.env.GLEXIR_API_KEY,
  timeout: 60_000, // 60 s per attempt
  maxRetries: 3,
});

const response = await glexir.responses.create(
  { model: "gpt-5.4", input: "Name three planets." },
  { timeout: 20_000 }, // this call only
);
console.log(response.output_text);

Constructor options

All options are optional.

Environment variables

The constructor reads two variables when the matching option is not passed:

Values are trimmed, and an empty value counts as unset. An option you pass always wins over the variable.

The SDK reads process.env only when a global process exists. In browsers and on edge runtimes without it, pass apiKey explicitly, and baseURL if you need a non-default URL.

export GLEXIR_API_KEY=glx_live_...

With GLEXIR_API_KEY set, new Glexir() needs no arguments.

Base URL

The SDK sends requests to production, https://api.glexir.com/v1, by default. The default is exported as DEFAULT_BASE_URL. You don't need to set a base URL to use Glexir.

Set baseURL, or GLEXIR_BASE_URL, only to point the client somewhere else:

import Glexir from "@glexir/sdk";

const glexir = new Glexir({
  apiKey: process.env.GLEXIR_API_KEY,
  baseURL: "http://localhost:8787/v1", // local gateway
});

The client resolves the base URL in this order: the baseURL option, then GLEXIR_BASE_URL, then DEFAULT_BASE_URL. Method paths are appended to it, so glexir.models.list() calls <baseURL>/models.

Timeouts

timeout applies to each attempt separately. With the defaults (10 minutes, 2 retries), a call that keeps timing out can take about 30 minutes plus backoff before it throws APIConnectionTimeoutError. Lower timeout or maxRetries if you need a tighter bound, or pass an AbortSignal (see below).

For non-streaming calls the timeout covers the whole response, including the body. For streams (stream: true, responses.stream(), chat.completions.stream()) and files.content(), the timer stops once response headers arrive; after that, only your signal can stop the request.

Headers

Every request carries these headers:

Headers are applied in this order, later ones winning: SDK headers, then defaultHeaders, then per-request headers. In per-request headers, a null value removes a header.

import Glexir from "@glexir/sdk";

const glexir = new Glexir({
  apiKey: process.env.GLEXIR_API_KEY,
  defaultHeaders: { "x-team": "search" },
});

// Adds x-trace and drops x-team for this call only.
await glexir.models.retrieve("gpt-5.4", {
  headers: { "x-trace": "abc123", "x-team": null },
});

Per-request options

Every method takes a RequestOptions object as its last argument.

import Glexir from "@glexir/sdk";

const glexir = new Glexir({ apiKey: process.env.GLEXIR_API_KEY });

const controller = new AbortController();
setTimeout(() => controller.abort(), 5_000);

const embedding = await glexir.embeddings.create(
  { model: "text-embedding-3-small", input: "hello" },
  { signal: controller.signal, maxRetries: 0, idempotencyKey: "embed-hello-1" },
);
console.log(embedding.data[0]?.embedding.length);

responses.parse() and chat.completions.parse() take ParseOptions, which is RequestOptions plus a validate function. See Responses.

Raw responses and request IDs

Every method returns an APIPromise<T>. Await it to get the parsed body. The request starts as soon as you call the method, even if you never await the result.

The gateway's request ID is attached to parsed JSON objects as _request_id. It is non-enumerable, so it does not show up in JSON.stringify or Object.keys. It is not attached to string results (for example srt transcripts) or streams.

import Glexir from "@glexir/sdk";

const glexir = new Glexir({ apiKey: process.env.GLEXIR_API_KEY });

const model = await glexir.models.retrieve("gpt-5.4");
console.log(model._request_id); // "req_..."

const { data, response, requestId } = await glexir.models.retrieve("gpt-5.4").withRawResponse();
console.log(data.id, response.status, response.headers.get("content-type"), requestId);

const raw: globalThis.Response = await glexir.models.retrieve("gpt-5.4").asResponse();
console.log(raw.status);

Client properties

A client exposes its resolved settings as read-only properties: apiKey, baseURL (without a trailing slash), timeout and maxRetries. The resources are properties too: responses, conversations, chat, audio, embeddings, files, batches and models. See Overview.

To change settings, create another client. Clients are cheap to create and hold no connections of their own.

Low-level requests

The client also has untyped methods for calling a path directly. They go through the same headers, retries, timeouts and error mapping as the typed methods. Prefer the typed methods; use these only for an endpoint the SDK does not wrap yet.

import Glexir from "@glexir/sdk";
import type { Model } from "@glexir/sdk";

const glexir = new Glexir({ apiKey: process.env.GLEXIR_API_KEY });

const model = await glexir.get<Model>("/models/gpt-5.4");
const url = glexir.buildURL("/files", { purpose: "batch", limit: 5 });
// "https://api.glexir.com/v1/files?purpose=batch&limit=5"

options accepts the per-request options above plus query (an object), body (sent as JSON), multipart: true (send body as multipart/form-data), stream: true (parse server-sent events into a Stream) and binary: true (return the raw Response). Query arrays are sent as key[]=value and nested objects as key[sub]=value. undefined and null values are left out.