Anvia Docs

@anvia/openai adapts the OpenAI SDK into Anvia's provider-neutral interfaces. It supports the Responses API (default), Chat Completions API, embeddings, image generation, audio generation, and transcription.

Install

pnpm add @anvia/openai

The OpenAI SDK (openai) is a transitive dependency.

Quick Start

import { AgentBuilder } from "@anvia/core";
import { OpenAIClient } from "@anvia/openai";

const client = new OpenAIClient({ apiKey });
const model = client.completionModel("gpt-5.5");

const agent = new AgentBuilder("support", model)
  .instructions("Answer clearly.")
  .build();

const response = await agent.prompt("What is Anvia?").send();
console.log(response.output);

Client Configuration

type OpenAIClientOptions = {
  apiKey?: string;         // required unless `client` is provided
  baseUrl?: string;        // custom endpoint (OpenAI-compatible proxies)
  headers?: Record<string, string>;
  completionApi?: "responses" | "chat";  // default: "responses"
  client?: OpenAI;         // pre-configured OpenAI SDK instance
};

Provider clients only use explicit constructor values. They do not read environment variables.

// Standard OpenAI
const client = new OpenAIClient({ apiKey });

// OpenAI-compatible proxy
const client = new OpenAIClient({
  baseUrl: "https://my-proxy.com/v1",
  apiKey,
});

// Chat Completions API instead of Responses
const client = new OpenAIClient({
  apiKey,
  completionApi: "chat",
});

// Pre-configured SDK instance
const client = new OpenAIClient({ client: existingOpenAIInstance });

Completion Models

Responses API (default)

const model = client.completionModel("gpt-5.5");

Returns an OpenAIResponsesCompletionModel that uses the Responses API.

Chat Completions API

const client = new OpenAIClient({ apiKey, completionApi: "chat" });
const model = client.completionModel("gpt-5.5");

Returns an OpenAIChatCompletionModel. Also used automatically when baseUrl is set (for OpenAI-compatible proxies that only support chat completions).

Streaming and Non-Streaming

Both models support:

// Non-streaming
const response = await model.completion(request);

// Streaming
for await (const event of model.streamCompletion(request)) {
  console.log(event);
}

Embedding Models

const embeddingModel = client.embeddingModel("text-embedding-3-small");

// With options
const embeddingModel = client.embeddingModel("text-embedding-3-large", {
  dimensions: 1024,
  maxBatchSize: 512,
});

const embeddings = await embeddingModel.embedTexts(["hello", "world"]);

Option	Default	Purpose
`dimensions`	model default	Output embedding dimensions
`maxBatchSize`	`512`	Texts per API call
`user`	--	End-user identifier for abuse monitoring

Image Generation

const imageModel = client.imageGenerationModel("gpt-image-1");

const result = await imageModel.generate({
  prompt: "A diagram of an agent runtime",
});

// result.images[0] is Uint8Array (PNG)

Model constants: GPT_IMAGE_1, GPT_IMAGE_2, DALL_E_2, DALL_E_3.

Audio Generation (Text-to-Speech)

const audioModel = client.audioGenerationModel("tts-1");

const result = await audioModel.generate({
  text: "Welcome to Anvia.",
});

// result.audio is Uint8Array

Model constants: TTS_1, TTS_1_HD.

Transcription

const transcriptionModel = client.transcriptionModel("whisper-1");

const result = await transcriptionModel.transcribe({
  audio: audioBuffer,
});

console.log(result.text);

Model constant: WHISPER_1.

Model Listing

const models = await client.listModels();
console.log(models.data.map((m) => m.id));

Fetches the configured /models endpoint and returns a normalized ModelList.

Namespaced Exports

All classes are also available under an openai namespace:

import { openai } from "@anvia/openai";

openai.OpenAIClient;
openai.OpenAIEmbeddingModel;
openai.OpenAIImageGenerationModel;
// etc.

Error Handling

Constructor throws when neither client nor apiKey is supplied
listModels() throws ModelListingError when the provider request fails
Model operations throw OpenAI SDK errors directly

Models for model name conventions
Compatible Gateways for OpenAI-compatible endpoints
OpenAI Reference for full API types
Getting Started for a first agent walkthrough