OpenAiClient
The OpenAiClient module provides an Effect service for OpenAI-compatible chat completions and embeddings APIs. It builds on the Effect HTTP client, adds authentication and OpenAI organization or project headers, and exposes typed helpers for non-streaming chat completions, streaming chat completions, and embedding requests.
Configuration
ChatCompletionResponseFormat type
Signature
type ChatCompletionResponseFormat = | { readonly type: "json_object"; } | { readonly json_schema: { readonly description?: string; readonly name: string; readonly schema: JsonObject; readonly strict?: boolean; }; readonly type: "json_schema"; };ChatCompletionToolChoice type
Controls whether the model may call tools and can force a specific function.
Signature
type ChatCompletionToolChoice = | "none" | "auto" | "required" | { readonly function: { readonly name: string; }; readonly type: "function"; };TextResponseFormatConfiguration type
Text output format configuration for plain text, JSON object, or JSON Schema responses.
Signature
type TextResponseFormatConfiguration = | { readonly type: "text"; } | { readonly description?: string; readonly name: string; readonly schema: JsonObject; readonly strict?: boolean | null; readonly type: "json_schema"; } | { readonly type: "json_object"; };Constructors
Constructs an OpenAI-compatible client service from explicit options.
When to use
Use when you need the OpenAI-compatible client service value inside an effect.
Details
The returned service uses the current HttpClient, prepends apiUrl or https://api.openai.com/v1, adds authentication and OpenAI organization/project headers, accepts JSON responses, and applies transformClient when provided.
Gotchas
A scoped OpenAiConfig.withClientTransform is applied when request helpers run, after the transformClient option supplied to make.
See
layerfor providing this client from explicit optionslayerConfigfor loading client settings fromConfig
Signature
declare const make: (...args: [options: Options]) => Effect;Layers
Creates a layer that provides an OpenAI-compatible client from explicit options.
When to use
Use to install OpenAiClient in an application layer when the client options are already available as values rather than loaded from Config.
See
makefor constructing the client service effectfullylayerConfigfor loading client settings fromConfig
Signature
declare function layer(options: Options): Layer<OpenAiClient, never, HttpClient>;layerConfig
Creates a layer that loads OpenAI-compatible client settings from Config values before constructing the service.
When to use
Use when you need client settings for OpenAI-compatible APIs to be read from Effect Config values while providing OpenAiClient as a layer.
Details
Only config values supplied in options are loaded. Omitted fields are passed to make as undefined, and transformClient is forwarded as a plain option.
See
Signature
declare function layerConfig(options?: { readonly apiKey?: Config<Redacted<string> | undefined>; readonly apiUrl?: Config<string>; readonly organizationId?: Config<Redacted<string> | undefined>; readonly projectId?: Config<Redacted<string> | undefined>; readonly transformClient?: (client: HttpClient) => HttpClient;}): Layer<OpenAiClient, ConfigError, HttpClient>;Models
Annotation type
Citation and file-path annotations attached to output text content.
Signature
type Annotation = | FileCitationAnnotation | UrlCitationAnnotation | ContainerFileCitationAnnotation | FilePathAnnotation;ChatCompletionChoice type
Decoded choice object returned by chat completion responses and chunks.
Signature
type ChatCompletionChoice = typeof ChatCompletionChoice.Type;ChatCompletionContentPart type
Structured content parts accepted in chat completion messages.
Signature
type ChatCompletionContentPart = | { readonly text: string; readonly type: "text"; } | { readonly image_url: { readonly detail?: "low" | "high" | "auto"; readonly url: string; }; readonly type: "image_url"; };ChatCompletionMessage type
Decoded message object from a non-streaming chat completion choice.
Signature
type ChatCompletionMessage = typeof ChatCompletionMessage.Type;ChatCompletionRequest type
Request payload for the OpenAI-compatible chat completions endpoint.
Signature
type ChatCompletionRequest = { [x: string]: unknown; readonly max_tokens?: number | null; readonly messages: ReadonlyArray<ChatCompletionRequestMessage>; readonly model: string; readonly parallel_tool_calls?: boolean | null; readonly reasoning?: unknown; readonly response_format?: ChatCompletionResponseFormat; readonly seed?: number; readonly service_tier?: string; readonly stream?: boolean; readonly stream_options?: { readonly include_usage?: boolean; }; readonly temperature?: number | null; readonly tool_choice?: ChatCompletionToolChoice; readonly tools?: ReadonlyArray<ChatCompletionTool>; readonly top_p?: number | null; readonly user?: string | null;};ChatCompletionRequestMessage type
Message shapes accepted by the chat completions endpoint.
Signature
type ChatCompletionRequestMessage = | { readonly content: string | ReadonlyArray<ChatCompletionContentPart> | null; readonly role: "system" | "developer" | "user" | "assistant"; readonly tool_calls?: ReadonlyArray<ChatCompletionRequestToolCall>; } | { readonly content: string; readonly role: "tool"; readonly tool_call_id: string; };ChatCompletionRequestToolCall type
Tool call data attached to an assistant chat completion message.
Signature
type ChatCompletionRequestToolCall = { readonly function: { readonly arguments: string; readonly name: string; }; readonly id: string; readonly type: "function";};ChatCompletionResponse type
Decoded successful response from the chat completions endpoint.
Signature
type ChatCompletionResponse = typeof ChatCompletionResponse.Type;ChatCompletionTool type
Function tool definition accepted by the chat completions endpoint.
Signature
type ChatCompletionTool = { readonly function: { readonly description?: string | null; readonly name: string; readonly parameters?: JsonObject; readonly strict?: boolean; }; readonly type: "function";};ChatCompletionToolCall type
Decoded tool-call object from a chat completion response or streaming chunk.
Signature
type ChatCompletionToolCall = typeof ChatCompletionToolCall.Type;ChatCompletionUsage type
Decoded token usage summary returned by chat completions.
Signature
type ChatCompletionUsage = typeof ChatCompletionUsage.Type;CreateEmbedding200 type
Decoded successful embeddings response body.
Signature
type CreateEmbedding200 = CreateEmbeddingResponse;CreateEmbeddingRequest type
Request payload for the embeddings endpoint.
Signature
type CreateEmbeddingRequest = { readonly dimensions?: number; readonly encoding_format?: "float" | "base64"; readonly input: | string | ReadonlyArray<string> | ReadonlyArray<number> | ReadonlyArray<ReadonlyArray<number>>; readonly model: string; readonly user?: string;};CreateEmbeddingRequestJson type
JSON request body accepted by the embeddings endpoint.
Signature
type CreateEmbeddingRequestJson = CreateEmbeddingRequest;CreateEmbeddingResponse type
Successful response payload returned by the embeddings endpoint.
Signature
type CreateEmbeddingResponse = { readonly data: ReadonlyArray<Embedding>; readonly model: string; readonly object?: "list"; readonly usage?: { readonly prompt_tokens: number; readonly total_tokens: number; };};CreateResponse type
Request options for creating a Responses-style response with an OpenAI-compatible provider.
Signature
type CreateResponse = { readonly background?: boolean | null; readonly conversation?: string | null; readonly include?: ReadonlyArray<IncludeEnum> | null; readonly input?: string | ReadonlyArray<InputItem>; readonly instructions?: string | null; readonly max_output_tokens?: number | null; readonly max_tool_calls?: number | null; readonly metadata?: Readonly<Record<string, string>> | null; readonly modalities?: ReadonlyArray<"text" | "audio">; readonly model?: string; readonly parallel_tool_calls?: boolean | null; readonly previous_response_id?: string | null; readonly prompt_cache_key?: string | null; readonly prompt_cache_retention?: "in-memory" | "24h" | null; readonly reasoning?: unknown; readonly safety_identifier?: string | null; readonly seed?: number; readonly service_tier?: string; readonly store?: boolean | null; readonly stream?: boolean | null; readonly temperature?: number | null; readonly text?: { readonly format?: TextResponseFormatConfiguration; readonly verbosity?: "low" | "medium" | "high" | null; }; readonly tool_choice?: ToolChoice; readonly tools?: ReadonlyArray<Tool>; readonly top_logprobs?: number; readonly top_p?: number | null; readonly truncation?: "auto" | "disabled" | null; readonly user?: string | null;};CreateResponse200 type
Decoded successful chat completion response body returned by createResponse.
Signature
type CreateResponse200 = ChatCompletionResponse;CreateResponseRequestJson type
JSON request body used by this client when creating a chat completion response.
Signature
type CreateResponseRequestJson = ChatCompletionRequest;Represents one embedding item returned by an OpenAI-compatible embeddings API.
Details
The embedding can be returned either as a numeric vector or as a base64-encoded string. The index field identifies the input item that produced this embedding.
Signature
type Embedding = { readonly embedding: ReadonlyArray<number> | string; readonly index: number; readonly object?: string;};IncludeEnum type
Optional response fields that can be requested with the include parameter.
Signature
type IncludeEnum = | "message.input_image.image_url" | "reasoning.encrypted_content" | "message.output_text.logprobs";InputContent type
Content blocks accepted in input messages.
Signature
type InputContent = InputTextContent | InputImageContent | InputFileContent;Item shapes accepted by a Responses-style input field.
Details
Supports input messages, output messages, tool calls, tool outputs, reasoning items, custom tool interactions, and item references.
Signature
type InputItem = | { readonly content: string | ReadonlyArray<InputContent>; readonly role: "user" | "assistant" | "system" | "developer"; readonly type?: "message"; } | { readonly content: ReadonlyArray<InputContent>; readonly role: "user" | "system" | "developer"; readonly status?: MessageStatus; readonly type?: "message"; } | OutputMessage | FunctionCall | FunctionCallOutput | ReasoningItem | CustomToolCallOutput | CustomToolCall | ItemReference;MessageStatus type
Lifecycle status shared by message, reasoning, and tool-call items.
Signature
type MessageStatus = "in_progress" | "completed" | "incomplete";ReasoningItem type
Reasoning output item containing encrypted reasoning content, summaries, and optional reasoning text.
Signature
type ReasoningItem = { readonly content?: ReadonlyArray<ReasoningTextContent>; readonly encrypted_content?: string | null; readonly id: string; readonly status?: MessageStatus; readonly summary: ReadonlyArray<SummaryTextContent>; readonly type: "reasoning";};Responses-style response object returned by compatible providers or embedded in response stream lifecycle events.
Signature
type Response = { readonly created_at: number; readonly id: string; readonly incomplete_details?: { readonly reason?: "max_output_tokens" | "content_filter"; } | null; readonly model: string; readonly object?: "response"; readonly output: ReadonlyArray<OutputItem>; readonly service_tier?: string; readonly status?: "completed" | "failed" | "in_progress" | "cancelled" | "queued" | "incomplete"; readonly usage?: ResponseUsage | null;};ResponseUsage type
Token accounting reported on Responses-style response objects.
Signature
type ResponseUsage = { readonly input_tokens: number; readonly input_tokens_details?: unknown; readonly output_tokens: number; readonly output_tokens_details?: unknown; readonly total_tokens: number;};SummaryTextContent type
Text content block used for model-provided reasoning summaries.
Signature
type SummaryTextContent = { readonly text: string; readonly type: "summary_text";};Tool definitions that can be supplied to a Responses-style request.
Signature
type Tool = FunctionTool | CustomToolParam;Options
Configuration options used to construct an OpenAI-compatible client.
Signature
type Options = { readonly apiKey?: Redacted.Redacted<string>; readonly apiUrl?: string; readonly organizationId?: Redacted.Redacted<string>; readonly projectId?: Redacted.Redacted<string>; readonly transformClient?: (client: HttpClient.HttpClient) => HttpClient.HttpClient;};Services
OpenAiClient
Service tag for the OpenAI-compatible chat completions and embeddings client.
When to use
Use when building effects that depend on the low-level OpenAI-compatible client through context rather than receiving the client as a value.
Details
The tagged service is the Service interface produced by make and provided by layer or layerConfig.
See
Servicefor the operations provided by the servicemakefor constructing the service from explicit optionslayerfor providing the service from explicit optionslayerConfigfor loading client settings fromConfig
Signature
declare class OpenAiClient extends Shape<"@effect/ai-openai-compat/OpenAiClient", Service, this> { constructor(_: never);}Effect service interface for OpenAI-compatible chat completions and embeddings.
Details
Exposes the configured HTTP client plus helpers for non-streaming chat completions, streaming chat completions, and embeddings. Transport and schema decoding failures are mapped to AiError.
Signature
interface Service { readonly client: HttpClient; readonly createEmbedding: (options: CreateEmbeddingRequest) => Effect<CreateEmbeddingResponse, AiError>; readonly createResponse: (options: ChatCompletionRequest) => Effect<[body: { readonly choices: readonly Array<{ readonly delta?: { readonly content?: string | null; readonly reasoning?: string | null; readonly reasoning_content?: string | null; readonly role?: string; readonly tool_calls?: readonly Array<{ readonly function?: ...; readonly id?: ...; readonly index?: ...; readonly type?: ...; }>; }; readonly finish_reason?: string | null; readonly index: number; readonly message?: { readonly content?: string | null; readonly reasoning?: string | null; readonly reasoning_content?: string | null; readonly role?: string; readonly tool_calls?: readonly Array<{ readonly function?: ...; readonly id?: ...; readonly index?: ...; readonly type?: ...; }>; }; }>; readonly created: number; readonly id: string; readonly model: string; readonly service_tier?: string; readonly usage?: { readonly completion_tokens: number; readonly completion_tokens_details?: any; readonly prompt_tokens: number; readonly prompt_tokens_details?: any; readonly total_tokens: number; } | null; }, response: HttpClientResponse], AiError>; readonly createResponseStream: (options: Omit<CreateResponseRequestJson, "stream" | "stream_options">) => Effect<[response: HttpClientResponse, stream: Stream<ChatCompletionStreamEvent, AiError, never>], AiError>;}Streaming
ChatCompletionChunk type
Decoded streaming chunk emitted by the chat completions endpoint.
Signature
type ChatCompletionChunk = typeof ChatCompletionChunk.Type;ChatCompletionStreamEvent type
Streaming chat completion event, including decoded chunks, unknown parsed events, and the [DONE] sentinel.
Signature
type ChatCompletionStreamEvent = ChatCompletionChunk | UnknownChatCompletionEvent | "[DONE]";CreateResponse200Sse type
Decoded server-sent event payload emitted by createResponseStream.
Signature
type CreateResponse200Sse = ChatCompletionStreamEvent;ResponseStreamEvent type
Server-sent event shapes emitted by Responses-style response streams.
Signature
type ResponseStreamEvent = | ResponseCreatedEvent | ResponseCompletedEvent | ResponseIncompleteEvent | ResponseFailedEvent | ResponseOutputItemAddedEvent | ResponseOutputItemDoneEvent | ResponseTextDeltaEvent | ResponseOutputTextAnnotationAddedEvent | ResponseFunctionCallArgumentsDeltaEvent | ResponseReasoningSummaryPartAddedEvent | ResponseReasoningSummaryPartDoneEvent | ResponseReasoningSummaryTextDeltaEvent | ResponseErrorEvent | UnknownResponseStreamEvent;UnknownChatCompletionEvent interface
A parsed chat completion event that does not match the expected chunk schema.
Signature
interface UnknownChatCompletionEvent { readonly _tag: "UnknownChatCompletionEvent"; readonly data: unknown;}
JSON response format configuration for chat completion requests.