Chat with an OpenAI model

This is the main interface to OpenAI's models, using the responses API. You can use this to access OpenAI's latest models and features like image generation and web search. If you need to use an OpenAI-compatible API from another provider, or the chat completions API with OpenAI,use chat_openai_compatible() instead.

Note that a ChatGPT Plus membership does not grant access to the API. You will need to sign up for a developer account (and pay for it) at the developer platform.

Usage

chat_openai(
  system_prompt = NULL,
  base_url = "https://api.openai.com/v1",
  api_key = NULL,
  credentials = NULL,
  model = NULL,
  params = NULL,
  api_args = list(),
  api_headers = character(),
  service_tier = c("auto", "default", "flex", "priority"),
  echo = c("none", "output", "all")
)

models_openai(
  base_url = "https://api.openai.com/v1",
  api_key = NULL,
  credentials = NULL
)

Arguments

system_prompt

A system prompt to set the behavior of the assistant.

base_url

The base URL to the API endpoint.

api_key

Use credentials instead.

credentials

Override the default credentials. You generally should not need this argument; instead set the OPENAI_API_KEY environment variable. The best place to set this is in .Renviron, which you can easily edit by calling usethis::edit_r_environ().

If you do need additional control, this argument takes a zero-argument function that returns either a string (the API key), or a named list (added as additional headers to every request).

model

The model to use for the chat (defaults to "gpt-5.6-terra"). We regularly update the default, so we strongly recommend explicitly specifying a model for anything other than casual use. Use models_openai() to see all options.

params

Common model parameters, usually created by params().

api_args

Named list of arbitrary extra arguments appended to the body of every chat API call. Combined with the body object generated by ellmer with modifyList().

api_headers

Named character vector of arbitrary extra headers appended to every chat API call.

service_tier

Request a specific service tier. There are four options:

• "auto" (default): uses the service tier configured in Project settings.

• "default": standard pricing and performance.

• "flex": slower and cheaper.

• "priority": faster and more expensive.

echo

One of the following options:

• none: don't emit any output (default when running in a function).

• output: echo text and tool-calling output as it streams in (default when running at the console).

• all: echo all input and output.

Note this only affects the chat() method.

Value

A Chat object.

See also

Other chatbots: chat_anthropic(), chat_aws_bedrock(), chat_azure_openai(), chat_cloudflare(), chat_databricks(), chat_deepseek(), chat_github(), chat_google_gemini(), chat_groq(), chat_huggingface(), chat_lmstudio(), chat_mistral(), chat_ollama(), chat_openai_compatible(), chat_openrouter(), chat_perplexity(), chat_portkey(), chat_posit()

Examples

chat <- chat_openai()
#> Using model = "gpt-5.6-terra".
chat$chat("
  What is the difference between a tibble and a data frame?
  Answer with a bulleted list
")
#> - **Origin**
#>   - A **data frame** is a base R data structure.
#>   - A **tibble** is a modern reimplementation of a data frame from the
#> **tibble** package, commonly used in the tidyverse.
#> 
#> - **Printing**
#>   - Data frames often print all rows and columns, which can be 
#> overwhelming for large datasets.
#>   - Tibbles print a compact preview: only the first few rows and 
#> columns, along with column types.
#> 
#> - **Data types**
#>   - Data frames may automatically convert character columns to factors
#> in older versions of R (depending on settings).
#>   - Tibbles do not automatically convert strings to factors.
#> 
#> - **Column names**
#>   - Data frames can modify invalid or duplicate column names by 
#> default (for example, adding dots).
#>   - Tibbles preserve column names more consistently and can support 
#> non-syntactic names.
#> 
#> - **Subsetting**
#>   - Extracting a single column from a data frame with `df[, "x"]` may 
#> simplify the result to a vector.
#>   - Extracting from a tibble with `tbl[, "x"]` always returns another 
#> tibble; use `tbl[["x"]]` or `tbl$x` to get a vector.
#> 
#> - **Partial matching**
#>   - Data frames may allow partial matching of column names, such as 
#> `df$long` matching a column called `long_name`.
#>   - Tibbles do not allow partial matching, helping prevent accidental 
#> mistakes.
#> 
#> - **Recycling behavior**
#>   - Data frames may silently recycle shorter vectors when creating or 
#> modifying columns.
#>   - Tibbles are stricter and generally require vectors to have 
#> compatible lengths, reducing silent errors.
#> 
#> - **Compatibility**
#>   - A tibble is still a type of data frame, so many functions that 
#> work with data frames also work with tibbles.
#>   - Some base R functions or older code may expect a plain data frame,
#> in which case a tibble can be converted with `as.data.frame()`.

chat$chat("Tell me three funny jokes about statisticians")
#> - Why did the statistician drown crossing a river?  
#>   Because it was three feet deep on average.
#> 
#> - A statistician’s favorite type of joke?  
#>   One with a significant *p*-unchline.
#> 
#> - There are three kinds of statisticians:  
#>   Those who can count, and those who can’t account for sampling error.