Skip to content
Effect Days 2026 Get your ticket

OpenAiLanguageModel

The OpenAiLanguageModel module provides the OpenAI Responses API implementation of Effect AI's LanguageModel service. It translates Effect AI prompts, files, tools, structured output requests, reasoning metadata, and provider options into OpenAI response requests, then converts OpenAI non-streaming or streaming response results back into Effect AI response content and metadata.

6 exports Added in v4.0.0 Source

Configuration

withConfigOverride

Added in v4.0.0 Source

Provides scoped config overrides for OpenAI language model operations.

When to use

Use to apply OpenAI Responses API config overrides around one or more language model operations without changing the defaults passed to model, make, or layer.

Details

The override is dual, so it can be used in pipe form or as withConfigOverride(effect, overrides). Overrides are merged with any existing Config service in the current context, and the override values take precedence.

See

  • Config for the scoped configuration service consumed by this function

Signature

declare const withConfigOverride: {
  (overrides: {
    readonly background?: boolean;
    readonly conversation?: string;
    readonly fileIdPrefixes?: ReadonlyArray<string>;
    readonly include?: readonly Array<"message.input_image.image_url" | "reasoning.encrypted_content" | "message.output_text.logprobs" | "code_interpreter_call.outputs" | "web_search_call.action.sources">;
    readonly instructions?: string;
    readonly max_output_tokens?: number;
    readonly max_tool_calls?: number;
    readonly metadata?: {
      [key: string]: string;
    };
    readonly modalities?: readonly Array<"text" | "audio">;
    readonly model?: string;
    readonly previous_response_id?: string;
    readonly prompt_cache_key?: string;
    readonly prompt_cache_options?: {
      readonly mode?: "implicit" | "explicit";
      readonly ttl?: "30m";
    };
    readonly reasoning?: {
      readonly effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
      readonly generate_summary?: "auto" | "concise" | "detailed";
      readonly summary?: "auto" | "concise" | "detailed";
    };
    readonly seed?: number;
    readonly service_tier?: string;
    readonly store?: boolean;
    readonly strictJsonSchema?: boolean;
    readonly temperature?: number;
    readonly text?: {
      readonly verbosity?: "low" | "medium" | "high";
    };
    readonly top_logprobs?: number;
    readonly top_p?: number;
    readonly truncation?: "auto" | "disabled";
    readonly user?: string;
  }): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Exclude<R, Config>>;
  <A, E, R>(self: Effect<A, E, R>, overrides: {
    readonly background?: boolean;
    readonly conversation?: string;
    readonly fileIdPrefixes?: ReadonlyArray<string>;
    readonly include?: readonly Array<"message.input_image.image_url" | "reasoning.encrypted_content" | "message.output_text.logprobs" | "code_interpreter_call.outputs" | "web_search_call.action.sources">;
    readonly instructions?: string;
    readonly max_output_tokens?: number;
    readonly max_tool_calls?: number;
    readonly metadata?: {
      [key: string]: string;
    };
    readonly modalities?: readonly Array<"text" | "audio">;
    readonly model?: string;
    readonly previous_response_id?: string;
    readonly prompt_cache_key?: string;
    readonly prompt_cache_options?: {
      readonly mode?: "implicit" | "explicit";
      readonly ttl?: "30m";
    };
    readonly reasoning?: {
      readonly effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
      readonly generate_summary?: "auto" | "concise" | "detailed";
      readonly summary?: "auto" | "concise" | "detailed";
    };
    readonly seed?: number;
    readonly service_tier?: string;
    readonly store?: boolean;
    readonly strictJsonSchema?: boolean;
    readonly temperature?: number;
    readonly text?: {
      readonly verbosity?: "low" | "medium" | "high";
    };
    readonly top_logprobs?: number;
    readonly top_p?: number;
    readonly truncation?: "auto" | "disabled";
    readonly user?: string;
  }): Effect<A, E, Exclude<R, Config>>;
}

Constructors

make

Added in v4.0.0 Source

Creates an OpenAI LanguageModel service from a model identifier and optional request defaults.

When to use

Use to construct an OpenAI Responses API language model service backed by OpenAiClient.

Details

The returned effect requires OpenAiClient. Request defaults from the config option are merged with any Config service in the context, with context values taking precedence. The service supports both generateText and streamText.

See

  • layer for providing the service as a Layer
  • model for creating a model descriptor for Effect.provide

Signature

declare const make: (...args: [{
  readonly config?: Omit<{
    readonly background?: boolean;
    readonly conversation?: string;
    readonly fileIdPrefixes?: readonly Array<string>;
    readonly include?: readonly Array<"message.input_image.image_url" | "reasoning.encrypted_content" | "message.output_text.logprobs" | "code_interpreter_call.outputs" | "web_search_call.action.sources">;
    readonly instructions?: string;
    readonly max_output_tokens?: number;
    readonly max_tool_calls?: number;
    readonly metadata?: {
      [key: string]: string;
    };
    readonly modalities?: readonly Array<"text" | "audio">;
    readonly model?: string;
    readonly previous_response_id?: string;
    readonly prompt_cache_key?: string;
    readonly prompt_cache_options?: {
      readonly mode?: "implicit" | "explicit";
      readonly ttl?: "30m";
    };
    readonly reasoning?: {
      readonly effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
      readonly generate_summary?: "auto" | "concise" | "detailed";
      readonly summary?: "auto" | "concise" | "detailed";
    };
    readonly seed?: number;
    readonly service_tier?: string;
    readonly store?: boolean;
    readonly strictJsonSchema?: boolean;
    readonly temperature?: number;
    readonly text?: {
      readonly verbosity?: "low" | "medium" | "high";
    };
    readonly top_logprobs?: number;
    readonly top_p?: number;
    readonly truncation?: "auto" | "disabled";
    readonly user?: string;
  }, "model">;
  readonly model: string & {} | Model;
}]) => Effect<LanguageModel, never, OpenAiClient>

model

Added in v4.0.0 Source

Creates an OpenAI model descriptor that can be provided with Effect.provide.

When to use

Use when you want an OpenAI language model value that carries provider and model metadata and can be supplied directly to an Effect program.

See

  • layer for creating a LanguageModel.LanguageModel layer directly
  • make for constructing the language model service effectfully

Signature

declare function model(model: string & {} | Model, config?: Omit<{
  readonly background?: boolean;
  readonly conversation?: string;
  readonly fileIdPrefixes?: readonly Array<string>;
  readonly include?: readonly Array<"message.input_image.image_url" | "reasoning.encrypted_content" | "message.output_text.logprobs" | "code_interpreter_call.outputs" | "web_search_call.action.sources">;
  readonly instructions?: string;
  readonly max_output_tokens?: number;
  readonly max_tool_calls?: number;
  readonly metadata?: {
    [key: string]: string;
  };
  readonly modalities?: readonly Array<"text" | "audio">;
  readonly model?: string;
  readonly previous_response_id?: string;
  readonly prompt_cache_key?: string;
  readonly prompt_cache_options?: {
    readonly mode?: "implicit" | "explicit";
    readonly ttl?: "30m";
  };
  readonly reasoning?: {
    readonly effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
    readonly generate_summary?: "auto" | "concise" | "detailed";
    readonly summary?: "auto" | "concise" | "detailed";
  };
  readonly seed?: number;
  readonly service_tier?: string;
  readonly store?: boolean;
  readonly strictJsonSchema?: boolean;
  readonly temperature?: number;
  readonly text?: {
    readonly verbosity?: "low" | "medium" | "high";
  };
  readonly top_logprobs?: number;
  readonly top_p?: number;
  readonly truncation?: "auto" | "disabled";
  readonly user?: string;
}, "model">): Model<"openai", LanguageModel, OpenAiClient>

Layers

layer

Added in v4.0.0 Source

Creates a layer that provides the OpenAI LanguageModel.LanguageModel service.

When to use

Use when composing application layers and you want OpenAI to satisfy LanguageModel.LanguageModel while supplying OpenAiClient from another layer.

Details

The config option supplies request defaults for the selected model. Scoped values from withConfigOverride are merged when each request is built and take precedence over these defaults.

See

  • make for constructing the language model service effectfully
  • model for creating a model descriptor for Effect.provide
  • withConfigOverride for scoped request configuration overrides

Signature

declare function layer(options: {
  readonly config?: Omit<{
    readonly background?: boolean;
    readonly conversation?: string;
    readonly fileIdPrefixes?: readonly Array<string>;
    readonly include?: readonly Array<"message.input_image.image_url" | "reasoning.encrypted_content" | "message.output_text.logprobs" | "code_interpreter_call.outputs" | "web_search_call.action.sources">;
    readonly instructions?: string;
    readonly max_output_tokens?: number;
    readonly max_tool_calls?: number;
    readonly metadata?: {
      [key: string]: string;
    };
    readonly modalities?: readonly Array<"text" | "audio">;
    readonly model?: string;
    readonly previous_response_id?: string;
    readonly prompt_cache_key?: string;
    readonly prompt_cache_options?: {
      readonly mode?: "implicit" | "explicit";
      readonly ttl?: "30m";
    };
    readonly reasoning?: {
      readonly effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
      readonly generate_summary?: "auto" | "concise" | "detailed";
      readonly summary?: "auto" | "concise" | "detailed";
    };
    readonly seed?: number;
    readonly service_tier?: string;
    readonly store?: boolean;
    readonly strictJsonSchema?: boolean;
    readonly temperature?: number;
    readonly text?: {
      readonly verbosity?: "low" | "medium" | "high";
    };
    readonly top_logprobs?: number;
    readonly top_p?: number;
    readonly truncation?: "auto" | "disabled";
    readonly user?: string;
  }, "model">;
  readonly model: string & {} | Model;
}): Layer<LanguageModel, never, OpenAiClient>

Models

Model type

Added in v4.0.0 Source

OpenAI model identifiers supported by the Responses API language model.

Signature

type Model = typeof ResponseModelIds.Encoded | typeof SharedModelIds.Encoded

Services

Config

Added in v4.0.0 Source

Context service for OpenAI language model configuration.

When to use

Use when you need to provide OpenAI Responses API request defaults through Effect context for language model operations.

Details

Config values are merged with the config object passed to model, make, or layer, with scoped context values taking precedence.

See

Signature

declare class Config extends Shape<"@effect/ai-openai/OpenAiLanguageModel/Config", {
  readonly background?: boolean;
  readonly conversation?: string;
  readonly fileIdPrefixes?: readonly Array<string>;
  readonly include?: readonly Array<"message.input_image.image_url" | "reasoning.encrypted_content" | "message.output_text.logprobs" | "code_interpreter_call.outputs" | "web_search_call.action.sources">;
  readonly instructions?: string;
  readonly max_output_tokens?: number;
  readonly max_tool_calls?: number;
  readonly metadata?: {
    [key: string]: string;
  };
  readonly modalities?: readonly Array<"text" | "audio">;
  readonly model?: string;
  readonly previous_response_id?: string;
  readonly prompt_cache_key?: string;
  readonly prompt_cache_options?: {
    readonly mode?: "implicit" | "explicit";
    readonly ttl?: "30m";
  };
  readonly reasoning?: {
    readonly effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
    readonly generate_summary?: "auto" | "concise" | "detailed";
    readonly summary?: "auto" | "concise" | "detailed";
  };
  readonly seed?: number;
  readonly service_tier?: string;
  readonly store?: boolean;
  readonly strictJsonSchema?: boolean;
  readonly temperature?: number;
  readonly text?: {
    readonly verbosity?: "low" | "medium" | "high";
  };
  readonly top_logprobs?: number;
  readonly top_p?: number;
  readonly truncation?: "auto" | "disabled";
  readonly user?: string;
}, this> {
  constructor(_: never);
}