OpenAI provider implementation with multi-driver architecture for Chat, Responses, and Images APIs.

Architecture

This provider uses a metadata-driven routing system to dispatch requests to specialized API drivers:

• ChatAPI (ReqLLM.Providers.OpenAI.ChatAPI) - Handles /v1/chat/completions endpoint for models like GPT-4, GPT-3.5, and other chat-based models.

• ResponsesAPI (ReqLLM.Providers.OpenAI.ResponsesAPI) - Handles /v1/responses endpoint for reasoning models (o1, o3, o4, GPT-4.1, GPT-5) with extended thinking capabilities.

• ImagesAPI (ReqLLM.Providers.OpenAI.ImagesAPI) - Handles /v1/images/generations endpoint for image generation models (DALL-E 2, DALL-E 3, gpt-image-*).

The provider automatically routes requests based on the operation type and model metadata:

• :image operations → uses ImagesAPI driver
• :chat operations with "api": "responses" → uses ResponsesAPI driver
• :chat operations (default) → uses ChatAPI driver

Capabilities

Chat Completions API (ChatAPI)

• Text generation with GPT models
• Streaming responses with usage tracking
• Tool calling (function calling)
• Multi-modal inputs (text and images)
• Embeddings generation
• Full OpenAI Chat API compatibility

Responses API (ResponsesAPI)

• Extended reasoning for o1/o3/o4/GPT-4.1/GPT-5 models
• Reasoning effort control (minimal, low, medium, high)
• Streaming with reasoning token tracking
• Tool calling with responses-specific format
• Enhanced usage metrics including :reasoning_tokens

Images API (ImagesAPI)

• Image generation with DALL-E and gpt-image-* models
• Multiple output formats: PNG, JPEG, WebP (gpt-image-* only)
• Size and aspect ratio control
• Quality and style options (DALL-E 3)
• Returns images as ReqLLM.Message.ContentPart with :image or :image_url type
• Streaming not supported

Usage Normalization

Chat and Responses drivers normalize usage metrics to provide consistent field names:

• :reasoning_tokens - Primary field for reasoning token count (ResponsesAPI)
• :reasoning - Backward-compatibility alias (deprecated, use :reasoning_tokens)

Deprecation Notice: The :reasoning usage key is deprecated in favor of :reasoning_tokens and will be removed in a future version.

Configuration

Set your OpenAI API key via environment variable or application config:

# Option 1: Environment variable (automatically loaded from .env via dotenvy)
OPENAI_API_KEY=sk-...

# Option 2: Store in application config
ReqLLM.put_key(:openai_api_key, "sk-...")

Examples

# Simple text generation (ChatAPI)
model = ReqLLM.model("openai:gpt-4")
{:ok, response} = ReqLLM.generate_text(model, "Hello!")

# Reasoning model (ResponsesAPI)
model = ReqLLM.model("openai:o1")
{:ok, response} = ReqLLM.generate_text(model, "Solve this problem...")
response.usage.reasoning_tokens  # Reasoning tokens used

# Streaming with reasoning
{:ok, stream} = ReqLLM.stream_text(model, "Complex question", stream: true)

# Tool calling (both APIs)
tools = [%ReqLLM.Tool{name: "get_weather", ...}]
{:ok, response} = ReqLLM.generate_text(model, "What's the weather?", tools: tools)

# Embeddings (ChatAPI)
{:ok, embedding} = ReqLLM.generate_embedding("openai:text-embedding-3-small", "Hello world")

# Reasoning effort (ResponsesAPI)
{:ok, response} = ReqLLM.generate_text(
  "openai:gpt-5",
  "Hard problem",
  reasoning_effort: :high
)

# Image generation (ImagesAPI)
{:ok, response} = ReqLLM.generate_image("openai:gpt-image-1", "A futuristic city at sunset")

# DALL-E with options
{:ok, response} = ReqLLM.generate_image(
  "openai:dall-e-3",
  "A watercolor painting of a forest",
  size: {1792, 1024},
  quality: :hd,
  style: :natural
)