Developer integration

OpenAI SDK

Use the official OpenAI SDK with a custom Albatross base URL.

Protocol: Responses · Chat Completions
Support status: Verified locally with Node.js SDK 7.9.0

Configure the client

Set the base URL to the Gateway /v1 address. Set retries to zero during initial acceptance so one client action maps to one observable request. In a local example project with Node.js and pnpm installed, run the installation and environment commands in the same terminal (macOS/Linux shell; adapt export syntax on Windows). Save the client initialization as albatross-openai.mjs in that project and append one example from a later section; examples are alternatives, not commands to run independently. Then run the file from that project directory. Exported variables last only for that terminal and its children. After editing the file or environment, rerun Node to apply the changes.

Run in terminal · example project · install dependency

pnpm add openai@7.9.0

Run in the same terminal · macOS/Linux shell

export ALBATROSS_BASE_URL="https://staging-gateway.bulakua.com/v1"
export ALBATROSS_API_KEY="<ALBATROSS_API_KEY>"
export ALBATROSS_MODEL="<ALBATROSS_MODEL>"

File content · example project/albatross-openai.mjs

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ALBATROSS_API_KEY,
  baseURL: process.env.ALBATROSS_BASE_URL,
  maxRetries: 0,
});

Run in the same terminal · example project

node albatross-openai.mjs

Create a Response

Append to albatross-openai.mjs · Non-streaming

const response = await client.responses.create({
  model: process.env.ALBATROSS_MODEL,
  input: "Reply with: connected",
  store: false,
});

console.log(response.output_text);

Append to albatross-openai.mjs · Streaming

const stream = await client.responses.create({
  model: process.env.ALBATROSS_MODEL,
  input: "Reply in one sentence.",
  store: false,
  stream: true,
});

let completed = false;
for await (const event of stream) {
  if (event.type === "response.output_text.delta") process.stdout.write(event.delta);
  if (event.type === "response.failed") {
    throw new Error(event.response.error.code + ": " + event.response.error.message);
  }
  if (event.type === "response.completed") {
    completed = true;
    console.log(event.response.usage);
  }
}

if (!completed) throw new Error("Stream ended before response.completed");

Continue after a tool call

Responses calls are stateless. The next request must include the original input, the actual response.output items, the matching function_call_output, and the same tool definitions.

Always send store: false.
Do not use previous_response_id, conversation, or item_reference.
Preserve item id, call_id, reasoning, and encrypted_content exactly as returned.
Validate tool names, arguments, permissions, output, and timeout in your application.

Append to albatross-openai.mjs · Tool round-trip

const input = [{ role: "user", content: "Look up order A-42" }];
const tools = [{
  type: "function",
  name: "get_order",
  description: "Look up an order",
  parameters: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
}];

const first = await client.responses.create({
  model: process.env.ALBATROSS_MODEL,
  input,
  tools,
  store: false,
  include: ["reasoning.encrypted_content"],
});
const call = first.output.find((item) => item.type === "function_call");
if (call) {
  const second = await client.responses.create({
    model: process.env.ALBATROSS_MODEL,
    input: [...input, ...first.output, {
      type: "function_call_output",
      call_id: call.call_id,
      output: JSON.stringify({ status: "ready" }),
    }],
    tools,
    store: false,
    include: ["reasoning.encrypted_content"],
  });
  console.log(second.output_text);
}

Chat Completions

Append to albatross-openai.mjs · Node.js

const completion = await client.chat.completions.create({
  model: process.env.ALBATROSS_MODEL,
  messages: [{ role: "user", content: "Hello" }],
});

console.log(completion.choices[0]?.message.content);

Acceptance checklist

Non-streaming and streaming text
Function or custom tool round-trip
A valid terminal event and usage
401 display with an invalid synthetic key
Cancellation before the terminal event

Switch models with one OpenAI SDK client

Configure the Gateway /v1 base URL and API key once. Pass a different exact alias in each Responses or Chat Completions request.

Append to albatross-openai.mjs · multi-model selection

const models = { fast: '<ALBATROSS_TEXT_FAST_ALIAS>', quality: '<ALBATROSS_TEXT_QUALITY_ALIAS>' };
const response = await client.responses.create({ model: models.fast, input: 'Quick status', store: false });
const detailed = await client.responses.create({ model: models.quality, input: 'Detailed analysis', store: false });
const chat = await client.chat.completions.create({ model: models.quality, messages: [{ role: 'user', content: 'Summarize' }] });