Documentation

openai.ChatClient

One model turn against OpenAI's Chat Completions API (`POST https://api.openai.com/v1/chat/completions`).

Reference version

Signature

class openai.ChatClient

One model turn against OpenAI's Chat Completions API (POST https://api.openai.com/v1/chat/completions).

The sibling of openai.ResponsesClient: same provider, older and far more widely-cloned endpoint. Reach for this one when you want chat-completions semantics from OpenAI itself; for any other OpenAI-compatible server use openai.GenericClient, openai.OllamaClient, openai.OpenRouterClient or openai.AzureClient, which are the same wire core with different compat flags (openai/ns_internal/chat.baml).

Source:<builtin>/openai/chat.bamlbytes 553–8721

Fields

model

string

api_key

ai.Credential | null

base_url

ai.Credential | null

timeout

baml.time.Duration | ai.LlmTimeoutOptions | null

request_body

baml.json.json | null

headers

map<string, string> | null

query_params

map<string, string> | null

temperature

float | null

max_tokens

int | null

max_completion_tokens

int | null

top_p

float | null

stop

string[] | null

seed

int | null

capture_wire

bool

structured_output

bool

Hold the model to the output type with OpenAI Structured Outputs: the request carries a strict JSON Schema of the type as response_format, and the answer is read strictly as JSON rather than parsed leniently.

The model sees that schema, with every @description and /// on the type's classes, fields and enum variants, so the prompt need not include ${ctx.output_format()}. A prompt that keeps it sends the schema twice, which is harmless but costs tokens.

An output type strict mode cannot describe (a map, media, a type with no JSON form) is rejected before the request is sent, and so is a call that streams: streaming does not support it yet.

Static methods

function

new

(
model: string = …,
api_key: ai.Credential | null = …,
base_url: ai.Credential | null = …,
timeout: baml.time.Duration | ai.LlmTimeoutOptions | null = …,
request_body: baml.json.json | null = …,
headers: map<string, string> | null = …,
query_params: map<string, string> | null = …,
temperature: float | null = …,
max_tokens: int | null = …,
max_completion_tokens: int | null = …,
top_p: float | null = …,
stop: string[] | null = …,
seed: int | null = …,
capture_wire: bool = …,
structured_output: bool = …
) -> openai.ChatClient throws never

Creates a client. Construction reads no environment variable, so declaring one is always safe; credentials and endpoints resolve when a request is built.

Parameters

  • structured_output: send OpenAI Structured Outputs and read the answer strictly (see the field of the same name). The model sees the output type's schema, documentation included, so a prompt need not include ${ctx.output_format()}.

Instance methods

function

compat

(self) -> openai.internal.ChatCompat throws baml.errors.Io | baml.errors.ParseError

The provider record: everything the shared core needs to know about this endpoint. Only stream_options distinguishes first-party OpenAI from a bare compatible server. The provider record: everything the shared chat core needs to know about this endpoint.

function

params

(
self,
preview: bool = …
) -> openai.internal.ChatParams throws baml.errors.Io | baml.errors.ParseError

The per-request parameters handed to the shared chat core.

Parameters

  • preview: omit the credential, for rendering a request without sending it.
function

resolved_api_key

(self) -> string | null throws baml.errors.Io | baml.errors.ParseError

The request-time credential: the explicit value (a literal, or the value of the variable an env.NAME ref points at), else the provider's canonical variable. Null is reported as a configuration error when the request is built, naming OPENAI_API_KEY.

function

resolved_base_url

(self) -> string throws baml.errors.Io | baml.errors.ParseError

The request-time base URL, or the provider default.

Implementations

ai.Client for openai.ChatClient

Instance methods

function

default_cache_args

(self) -> baml.json.json throws never

What a ${cache()} sends as prompt_cache_breakpoint on the part before it: {"mode": "explicit"}. Null for GPT-5.5 and earlier, which reject the field; a ${cache()} sends nothing there.

function

invoke

(
self,
input: ai.ModelTurnInput
) -> ai.ModelTurn throws reflect.errors.CompilationError | baml.errors.Timeout | baml.errors.UnknownError | ai.errors.Failure
function

provider

(self) -> string throws never
function

render

(
self,
input: ai.ModelTurnInput
) -> baml.http.Request throws reflect.errors.CompilationError | baml.errors.Timeout | baml.errors.UnknownError | ai.errors.Failure
function

requested_model

(self) -> string throws never

Source:<builtin>/openai/chat.bamlbytes 6950–8208

ai.stream.StreamingClient for openai.ChatClient

Instance methods

function

invoke_stream

(
self,
input: ai.ModelTurnInput
) -> ai.stream.TurnStream throws reflect.errors.CompilationError | baml.errors.Timeout | baml.errors.UnknownError | ai.errors.Failure

Source:<builtin>/openai/chat.bamlbytes 8214–8719