BaseChatOpenAI

Model name to use.

What sampling temperature to use.

Holds any model parameters valid for create call not explicitly specified.

API key to use.

Can be inferred from the OPENAI_API_KEY environment variable, or specified as a string, or sync or async callable that returns a string.

export OPENAI_API_KEY=...

from langchain_openai import ChatOpenAI

model = ChatOpenAI(model="gpt-5-nano")

from langchain_openai import ChatOpenAI

model = ChatOpenAI(model="gpt-5-nano", api_key="...")

from langchain_openai import ChatOpenAI

def get_api_key() -> str:
    # Custom logic to retrieve API key
    return "..."

model = ChatOpenAI(model="gpt-5-nano", api_key=get_api_key)

from langchain_openai import ChatOpenAI

async def get_api_key() -> str:
    # Custom async logic to retrieve API key
    return "..."

model = ChatOpenAI(model="gpt-5-nano", api_key=get_api_key)

Base URL path for API requests, leave blank if not using a proxy or service emulator.

Resolution order (first match wins):

1. Explicit base_url (or openai_api_base) kwarg.
2. Env var OPENAI_API_BASE (read by LangChain at init).
3. Env var OPENAI_BASE_URL (read by the underlying openai SDK client).

OPENAI_BASE_URL is also inspected by LangChain only to decide whether to default-enable stream_usage — when set, the default is left off because many non-OpenAI endpoints do not support streaming token usage.

Automatically inferred from env var OPENAI_ORG_ID if not provided.

Timeout for requests to OpenAI completion API.

Can be float, httpx.Timeout or None.

Whether to include usage metadata in streaming output.

If enabled, an additional message chunk will be generated during the stream including usage metadata.

This parameter is enabled unless openai_api_base is set or the model is initialized with a custom client, as many chat completions APIs do not support streaming token usage.

Maximum number of retries to make when generating.

Penalizes repeated tokens.

Penalizes repeated tokens according to frequency.

Seed for generation

Whether to return logprobs.

Number of most likely tokens to return at each token position, each with an associated log probability.

logprobs must be set to true if this parameter is used.

Modify the likelihood of specified tokens appearing in the completion.

Whether to stream the results or not.

Number of chat completions to generate for each prompt.

Total probability mass of tokens to consider at each step.

Maximum number of tokens to generate.

Constrains effort on reasoning for reasoning models.

For use with the Chat Completions API. Reasoning models only.

Currently supported values are 'minimal', 'low', 'medium', and 'high'. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.

Reasoning parameters for reasoning models. None disables reasoning.

For use with the Responses API.

reasoning={
    "effort": None,  # Default None; can be "low", "medium", or "high"
    "summary": "auto",  # Can be "auto", "concise", or "detailed"
}

Controls the verbosity level of responses for reasoning models.

For use with the Responses API.

Currently supported values are 'low', 'medium', and 'high'.

The model name to pass to tiktoken when using this class.

Tiktoken is used to count the number of tokens in documents to constrain them to be under a certain limit.

By default, when set to None, this will be the same as the embedding model name. However, there are some cases where you may want to use this Embedding class with a model name not supported by tiktoken. This can include when using Azure embeddings or when using one of the many model providers that expose an OpenAI-like API but with different models. In those cases, in order to avoid erroring when tiktoken is called, you can specify a model name to use here.

Optional httpx.Client.

Only used for sync invocations. Must specify http_async_client as well if you'd like a custom client for async invocations.

Optional httpx.AsyncClient.

Only used for async invocations. Must specify http_client as well if you'd like a custom client for sync invocations.

TCP socket options applied to the httpx transports built by this instance.

Defaults to a conservative TCP-keepalive + TCP_USER_TIMEOUT profile that targets a ~2-minute bound on silent connection hangs (silent mid-stream peer loss, gVisor/NAT idle timeouts, silent TCP black holes) on platforms that support the full option set. On platforms that only support a subset (macOS without TCP_USER_TIMEOUT, Windows with only SO_KEEPALIVE, minimal kernels), unsupported options are silently dropped and the bound degrades to whatever the remaining options + OS defaults provide — still better than indefinite hang.

Accepted values:

• None (default): use env-driven defaults. Matches the "unset" convention used by http_client elsewhere on this class.
• () (empty): disable socket-option injection entirely. Inherits the OS defaults and restores httpx's native env-proxy auto-detection.
• A non-empty sequence of (level, option, value) tuples: explicit override; passed verbatim to the transport (not filtered). Unsupported options raise OSError at connect time rather than being silently dropped — the user chose them explicitly.

Environment variables (only consulted when this field is None): LANGCHAIN_OPENAI_TCP_KEEPALIVE (set to 0 to disable entirely — the kill-switch), LANGCHAIN_OPENAI_TCP_KEEPIDLE, LANGCHAIN_OPENAI_TCP_KEEPINTVL, LANGCHAIN_OPENAI_TCP_KEEPCNT, LANGCHAIN_OPENAI_TCP_USER_TIMEOUT_MS.

Applied per side: if http_client is supplied, the sync path uses that user-owned client's socket options as-is; the async path still gets http_socket_options applied to its default builder (and vice-versa for http_async_client). Supply both to take full control.

Per-chunk wall-clock timeout (seconds) on async streaming responses.

Applies to async invocations only (astream, ainvoke with streaming, etc.). Sync streaming (stream) is not affected.

Fires between content chunks yielded by the openai SDK's streaming iterator (i.e., each call to __anext__ on the response). Crucially, this is not the same as httpx's timeout.read:

• httpx's read timeout is inter-byte and gets reset every time any bytes arrive on the socket — including OpenAI's SSE keepalive comments (: keepalive) that trickle down during long model generations. A stream that's silent on content but still producing keepalives looks alive forever to httpx.
• stream_chunk_timeout measures the gap between parsed chunks. The openai SDK's SSE parser consumes keepalive comments internally and does not emit them as chunks, so keepalives do not reset this timer. It fires on genuine content silence.

When it fires, a StreamChunkTimeoutError (subclass of asyncio.TimeoutError) is raised with a self-describing message naming this knob, the env-var override, the model, and the number of chunks received before the stall. A WARNING log with extra={"source": "stream_chunk_timeout", "timeout_s": <value>, "model_name": <value>, "chunks_received": <value>} also fires so aggregate logging can distinguish app-layer timeouts from transport-layer failures.

Defaults to 120s. Set to None or 0 to disable. Overridable via the LANGCHAIN_OPENAI_STREAM_CHUNK_TIMEOUT_S env var. Negative values (from either the env var or the constructor kwarg — e.g., hydrated from YAML/JSON configs) fall back to the default with a WARNING log rather than silently disabling the wrapper, so a misconfigured value still boots safely and the fallback is visible.

Default stop sequences.

Whether to include response headers in the output message response_metadata.

Note: some inference providers return additional metadata (such as served model names) in the response headers. Enable to capture these metadata.

Parameters of the OpenAI client or chat.completions endpoint that should be disabled for the given model.

Should be specified as {"param": None | ['val1', 'val2']} where the key is the parameter and the value is either None, meaning that parameter should never be used, or it's a list of disabled values for the parameter.

For example, older models may not support the 'parallel_tool_calls' parameter at all, in which case disabled_params={"parallel_tool_calls": None} can be passed in.

If a parameter is disabled then it will not be used by default in any methods, e.g. in with_structured_output. However this does not prevent a user from directly passed in the parameter during invocation.

Additional fields to include in generations from Responses API.

Supported values:

• 'file_search_call.results'
• 'message.input_image.image_url'
• 'computer_call_output.output.image_url'
• 'reasoning.encrypted_content'
• 'code_interpreter_call.outputs'

Options controlling OpenAI prompt cache behavior.

Latency tier for request.

Options are 'auto', 'default', or 'flex'.

Relevant for users of OpenAI's scale tier service.

If True, OpenAI may store response data for future use.

Defaults to True for the Responses API and False for the Chat Completions API.

Truncation strategy (Responses API).

Can be 'auto' or 'disabled' (default).

If 'auto', model may drop input items from the middle of the message sequence to fit the context window.

If True, always pass previous_response_id using the ID of the most recent response. Responses API only.

Input messages up to the most recent response will be dropped from request payloads.

For example, the following two are equivalent:

model = ChatOpenAI(
    model="...",
    use_previous_response_id=True,
)
model.invoke(
    [
        HumanMessage("Hello"),
        AIMessage("Hi there!", response_metadata={"id": "resp_123"}),
        HumanMessage("How are you?"),
    ]
)

model = ChatOpenAI(model="...", use_responses_api=True)
model.invoke([HumanMessage("How are you?")], previous_response_id="resp_123")

Whether to use the Responses API instead of the Chat API.

If not specified then will be inferred based on invocation params.

Version of AIMessage output format to use.

This field is used to roll-out new output formats for chat model AIMessage responses in a backwards-compatible way.

Supported values:

• 'v0': AIMessage format as of langchain-openai 0.3.x.
• 'responses/v1': Formats Responses API output items into AIMessage content blocks (Responses API only)
• 'v1': v1 of LangChain cross-provider standard.

Same as model_name.

Build extra kwargs from additional params that were passed in.

Validate temperature parameter for different models.

• gpt-5 models (excluding gpt-5-chat) only allow temperature=1 or unset (Defaults to 1)

Validate that api key and python package exists in environment.

Get the tokens present in the text with tiktoken package.

Bind tool-like objects to this chat model.

Assumes model is compatible with OpenAI tool-calling API.

Model wrapper that returns outputs formatted to match the given schema.