Skip to content

@anvia/openai API reference ​

The package exports OpenAIClient, model option/handle types, known and extensible model-ID types, media model constants, typed reasoning controls, and the same surface under the openai namespace.

Client ​

ts
import type OpenAI from 'openai'
import type { CompletionModelControls, ModelContextLimits } from '@anvia/core/completion'

type OpenAIClientOptions =
  | {
      apiKey: string
      baseUrl?: string
      headers?: Record<string, string>
      client?: never
    }
  | {
      client: OpenAI
      apiKey?: never
      baseUrl?: never
      headers?: never
    }

class OpenAIClient {
  constructor(options: OpenAIClientOptions)

  completionModel<
    const ModelId extends OpenAICompletionModelId,
    const Controls extends CompletionModelControls = OpenAIControlsFor<ModelId>,
  >(options: {
    modelId: ModelId
    api?: 'responses' | 'chat'
    contextLimits?: ModelContextLimits
    controls?: Controls
  }): OpenAICompletionModel<Controls>

  decisionModel(options: OpenAIDecisionModelOptions): OpenAIDecisionModelHandle

  embeddingModel(options: {
    modelId: OpenAIEmbeddingModelId
    dimensions?: number
    user?: string
    maxBatchSize?: number
  }): OpenAIEmbeddingModelHandle

  imageGenerationModel(options: {
    modelId: OpenAIImageGenerationModelId
  }): OpenAIImageGenerationModelHandle

  speechGenerationModel(options: {
    modelId: OpenAISpeechGenerationModelId
  }): OpenAISpeechGenerationModelHandle

  transcriptionModel(options: {
    modelId: OpenAITranscriptionModelId
  }): OpenAITranscriptionModelHandle

  listModels(options?: { abortSignal?: AbortSignal }): Promise<ModelList>
}

All constructors and factories require one options object. completionModel() defaults to api: 'chat'; baseUrl does not select it. Omitting controls applies per-model reasoning defaults derived from the model ID (OpenAIControlsFor). The two client forms are mutually exclusive: either provide managed connection options or inject an initialized OpenAI SDK client.

Model IDs and handles ​

The package exports known-ID unions and extensible IDs for completion, embedding, image generation, speech generation, and transcription. Factory results are exported as contract-oriented handle types:

ts
type OpenAICompletionModel<Controls extends CompletionModelControls = CompletionModelControls> =
  StreamingCompletionModel<unknown, Controls>
type OpenAIEmbeddingModelHandle = EmbeddingModel
type OpenAIImageGenerationModelHandle = ImageGenerationModel<unknown>
type OpenAISpeechGenerationModelHandle = SpeechGenerationModel<unknown>
type OpenAITranscriptionModelHandle = TranscriptionModel<unknown>

Known IDs provide autocomplete while ModelId<Known> still permits provider or gateway IDs that are not yet in the package.

Constants and namespace ​

ts
import {
  DALL_E_2,
  DALL_E_3,
  GPT_4O_MINI_TRANSCRIBE,
  GPT_4O_MINI_TTS,
  GPT_4O_TRANSCRIBE,
  GPT_4O_TRANSCRIBE_DIARIZE,
  GPT_IMAGE_1,
  GPT_IMAGE_2,
  GPT_6_LUNA,
  GPT_TRANSCRIBE,
  OPENAI_REASONING_EFFORTS,
  TTS_1,
  TTS_1_HD,
  WHISPER_1,
  openai,
} from '@anvia/openai'

openai contains the same client, types, and constants as the root entry point. The package has one public subpath, @anvia/openai/adapters, described below.

OPENAI_REASONING_EFFORTS enumerates every accepted reasoning effort (none, minimal, low, medium, high, xhigh, max). OpenAIControlsFor, OpenAIReasoningControls, and OpenAIReasoningEffort type the per-model controls surface; OpenAICompletionModelOptions mirrors the completionModel() options.

Adapters subpath ​

@anvia/openai/adapters (added in 1.2.0) exports OpenAIResponsesCompletionModel, the reusable Responses completion model. Provider packages such as @anvia/azure extend it and override its protected hooks: normalizeStream(stream) adapts endpoint-specific stream events before they are mapped, and requestParams(request) adapts the outgoing request. Subclasses can also override provider and traceRequest(). OpenAI's own parser keeps native event handling, including unnamed argument events, and validates tool-call names on completed calls. Application code should use OpenAIClient from the root entry point.

Decision models ​

OpenAIDecisionModelOptions is { modelId: OpenAIDecisionModelId }, and OpenAIDecisionModelHandle is DecisionModel<unknown>. KnownOpenAIDecisionModelId is the type of GPT_6_LUNA; OpenAIDecisionModelId also admits extensible string IDs. These types are exported from the root and openai namespace. Use the public client factory rather than internal model classes. See OpenAI decisions for mappings, limits, and refusal handling.

Built for Anvia.