OpenAI

caution

The @sap-ai-sdk/openai package is experimental and may change at any time without prior notice.

If you do not need OpenAI-specific features such as the Responses API, consider using the @sap-ai-sdk/orchestration package instead, which provides a stable interface for chat completion and other AI tasks on SAP AI Core.

caution

This package reuses the types from the official openai npm package.

The Azure OpenAI API shape differs from the core OpenAI API shape, and SAP AI Core applies additional platform-specific constraints. As a result, the static types for request parameters and responses are not always an exact match for what is defined at the type-level.

The @sap-ai-sdk/openai package is a thin wrapper around the official openai npm package, pre-configured for Azure OpenAI deployments on SAP AI Core. It handles deployment resolution, authentication, and SAP-specific headers automatically. Because SAP AI Core routes requests via the deployment URL, the model parameter is removed from all request signatures.

If you need a stable Azure OpenAI integration without recent OpenAI-specific features, consider using the @sap-ai-sdk/foundation-models package instead. It provides SAP's own client layer, based on a more stable API contract.

For full API reference, see the official OpenAI documentation.

Installation

npm install @sap-ai-sdk/openai openai

Prerequisites

See the prerequisites section.

Client Initialization

Use the SapOpenAi.createClient() method to create a pre-configured client. Pass a model name string or a deployment identifier object via the deployment option:

import { SapOpenAi } from '@sap-ai-sdk/openai';

// By model name (shorthand)
const client = await SapOpenAi.createClient('gpt-5.4');

// By model name and version
const client = await SapOpenAi.createClient({
  deployment: { modelName: 'gpt-5.4', modelVersion: '2025-04-14' }
});

// By deployment ID
const client = await SapOpenAi.createClient({
  deployment: { deploymentId: 'DEPLOYMENT_ID' }
});

Use the resourceGroup property to target a specific resource group. The resource group defaults to default:

const client = await SapOpenAi.createClient({
  deployment: { modelName: 'gpt-5.4', resourceGroup: 'my-resource-group' }
});

To use a custom SAP AI Core destination, pass the destination option:

const client = await SapOpenAi.createClient({
  deployment: { modelName: 'gpt-5.4' },
  destination: { destinationName: 'DESTINATION_NAME' }
});

Making Requests

SapOpenAi exposes three endpoints supported by SAP AI Core: chat, embeddings, and responses. The model parameter is omitted from all request signatures — the deployment URL determines the model.

Chat Completions

const response = await client.chat.completions.create({
  messages: [{ role: 'user', content: 'What is the capital of France?' }]
});

Use the parse() method for structured output with a Zod schema:

import { zodResponseFormat } from 'openai/helpers/zod';
import { z } from 'zod';

const CapitalResponse = z.object({ capital: z.string() });

const response = await client.chat.completions.parse({
  messages: [{ role: 'user', content: 'What is the capital of France?' }],
  response_format: zodResponseFormat(CapitalResponse, 'capital_response')
});

Embeddings

const embeddingClient = await SapOpenAi.createClient({
  deployment: 'text-embedding-3-small'
});

const response = await embeddingClient.embeddings.create({
  input: 'Hello, world!'
});

Responses API

const response = await client.responses.create({
  instructions: 'You are a helpful assistant.',
  input: 'What is the capital of France?'
});

Use the parse() method for structured output with a Zod schema:

import { zodTextFormat } from 'openai/helpers/zod';
import { z } from 'zod';

const CapitalResponse = z.object({ capital: z.string() });

const response = await client.responses.parse({
  instructions: 'You are a helpful assistant.',
  input: 'What is the capital of France?',
  text: { format: zodTextFormat(CapitalResponse, 'capital_response') }
});

Low-Level Config

Use the createOpenAiConfig() function to get an AzureClientOptions object for direct instantiation of AzureOpenAI. This is useful when you need endpoints not exposed by SapOpenAi:

import { AzureOpenAI } from 'openai';
import { createOpenAiConfig } from '@sap-ai-sdk/openai';

const config = await createOpenAiConfig('gpt-5.4');
const client = new AzureOpenAI(config);

Token Provider

Use the createTokenProvider() function when you need an azureADTokenProvider-compatible function for custom AzureOpenAI configurations. It is used internally by createOpenAiConfig().

import { AzureOpenAI } from 'openai';
import { createTokenProvider } from '@sap-ai-sdk/openai';

const client = new AzureOpenAI({
  baseURL: 'https://my-deployment-url',
  apiVersion: '2024-10-21',
  azureADTokenProvider: createTokenProvider()
});