# `Alloy.Provider.OpenAI`
[🔗](https://github.com/alloy-ex/alloy/blob/v0.12.4/lib/alloy/provider/openai.ex#L1)

Provider for OpenAI's Responses API.

Normalizes OpenAI's response output items (assistant messages + function
calls) to Alloy's content-block format.

## Config

Required:
- `:api_key` - OpenAI API key
- `:model` - Model name (e.g., "gpt-5.4", "gpt-5.1", "o3-pro")

Optional:
- `:max_tokens` - Max output tokens (default: 4096)
- `:system_prompt` - System prompt string
- `:api_url` - Base URL (default: "https://api.openai.com"). Can point to
  compatible Responses APIs such as xAI's "https://api.x.ai"
- `:provider_state` - opaque provider-owned state carried across turns.
  For Responses APIs Alloy uses `%{response_id: "..."}`
- `:store` - Persist the response server-side when supported
- `:include` - Additional response fields to include
- `:tool_choice` - Provider-native tool selection mode
- `:parallel_tool_calls` - Whether the provider may issue tool calls in parallel
- `:previous_response_id` - Explicit Responses continuation ID. Overrides
  `provider_state.response_id` when both are present
- `:built_in_tools` - provider-native tool definitions to append to custom
  function tools
- `:web_search` - `true` or a config map to append a `web_search` tool
- `:x_search` - `true` or a config map to append an `x_search` tool
- `:req_options` - Additional options passed to Req

In stateless mode (`store` not `true` with no previous response ID), Alloy
automatically requests encrypted reasoning content and round-trips opaque
reasoning output items between tool calls.

## Example

    Alloy.run("Summarize this code.",
      provider: {Alloy.Provider.OpenAI,
        api_key: System.get_env("OPENAI_API_KEY"),
        model: "gpt-5.4"
      }
    )

    Alloy.run("Review this repo",
      provider: {Alloy.Provider.OpenAI,
        api_key: System.get_env("XAI_API_KEY"),
        api_url: "https://api.x.ai",
        model: "grok-4"
      }
    )

# `config`

```elixir
@type config() :: %{
  :api_key => String.t(),
  :model => String.t(),
  optional(:max_tokens) => pos_integer(),
  optional(:system_prompt) => String.t(),
  optional(:api_url) => String.t(),
  optional(:provider_state) => map(),
  optional(:store) => boolean(),
  optional(:include) => [String.t()],
  optional(:tool_choice) => String.t() | map(),
  optional(:parallel_tool_calls) => boolean(),
  optional(:previous_response_id) => String.t(),
  optional(:built_in_tools) => [map()],
  optional(:web_search) => boolean() | map(),
  optional(:x_search) => boolean() | map(),
  optional(:req_options) => keyword()
}
```

Configuration for the OpenAI provider. See the module doc for field
semantics.

---

*Consult [api-reference.md](api-reference.md) for complete listing*