OpenAI SDK

In this guide, you will point the official OpenAI SDK at AISIX AI Gateway instead of sending requests directly to an upstream provider. This flow fits applications that already use the OpenAI-compatible chat-completions format and need to keep that client code mostly unchanged.

The example authenticates to AISIX with a caller API key, sends requests to the AISIX proxy API root, uses an AISIX model alias, and receives OpenAI-compatible chat-completions responses. The upstream provider can still be changed behind the gateway when the configured model alias and provider support that request shape.

Prerequisites

• A running AISIX gateway that your application can reach.
• A configured model alias that accepts OpenAI-compatible chat-completions requests.
• A caller API key allowed to use that model alias.
• Install Node.js 20 LTS or newer with npm.

If AISIX is already deployed for your organization, obtain the gateway URL, model alias, and caller API key from the team that manages it. Otherwise, follow the Open-Source AISIX Gateway Quickstart or AISIX Cloud Quickstart, or contact API7 for Hybrid Cloud access.

Configure the SDK

Create a small Node.js project, install the SDK, and point it at the AISIX proxy API root.

Install the SDK

Create a small demo project:

mkdir aisix-openai-demo && cd aisix-openai-demo
npm init -y

Install the OpenAI SDK in the demo project:

npm install openai

Set the caller API key, model alias, and gateway base URL:

export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-mini"
export AISIX_BASE_URL="http://127.0.0.1:3000/v1"

Create the Chat Example

Use the .mjs extension so Node treats top-level await and import as ES modules without extra configuration.

openai-sdk-example.mjs

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AISIX_API_KEY,
  baseURL: process.env.AISIX_BASE_URL,
});

const response = await client.chat.completions.create({
  model: process.env.AISIX_MODEL ?? "gpt-4o-mini",
  messages: [{ role: "user", content: "Say hello from AISIX." }],
});

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

Run the Example

Run the chat example from the demo project:

node openai-sdk-example.mjs

You should see a short assistant response. The exact text depends on the upstream model.

When the gateway can resolve gpt-4o-mini and the upstream provider is reachable, the SDK returns a standard OpenAI chat-completions object with an assistant message. AISIX resolves the model alias and injects the stored provider credential before calling the upstream provider.

Streaming Responses

The same baseURL works for streaming.

openai-sdk-streaming.mjs

import OpenAI from "openai";

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

const stream = await client.chat.completions.create({
  model: process.env.AISIX_MODEL ?? "gpt-4o-mini",
  messages: [{ role: "user", content: "Stream a short greeting." }],
  stream: true,
});

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

Run the streaming example from the demo project:

node openai-sdk-streaming.mjs

You should see streamed text printed to the terminal.

Production Setup Pattern

In most deployments, application code needs only the gateway base URL, caller API key, and AISIX model alias. Upstream credentials, provider base URLs, upstream model IDs, routing policies, rate limits, guardrails, and observability hooks stay behind the gateway.

This separation lets you rotate provider credentials, change upstream model IDs, or add gateway policy without changing the SDK call site.

If the SDK Request Fails

First check the caller API key, gateway base URL, and AISIX model alias with a direct request to the gateway. Then use the same values in the SDK.

If the SDK still sends traffic directly to OpenAI, check baseURL. It must point to the AISIX proxy API root, not to the upstream OpenAI API URL.

If AISIX returns 404, the requested model alias is not configured. If AISIX returns 403, the caller API key exists but is not allowed to use that alias.

Next Steps

You have now called AISIX from an OpenAI SDK client. From here, review OpenAI-Compatible API for proxy behavior. For SSE responses and tool definitions, see Streaming and Tool Calling. If your application expects Claude-style requests, continue with Anthropic SDK.