OpenAI API Integration

Connect Open WebUI with OpenAI and OpenAI-compatible providers

Overview

Open WebUI supports OpenAI’s API and any OpenAI-compatible API endpoints, including Azure OpenAI, Anthropic, Google AI, and custom providers.

Quick Start

1. Get API Key

   Obtain an API key from your provider (OpenAI, Azure, etc.)

2. Configure Environment

   Set the API key and base URL

3. Enable OpenAI API

   Enable in Admin Panel or set ENABLE_OPENAI_API=True

Configuration

OpenAI

Environment Variables

OPENAI_API_KEY=sk-proj-...
OPENAI_API_BASE_URL=https://api.openai.com/v1
ENABLE_OPENAI_API=True

Azure OpenAI

Environment Variables

OPENAI_API_KEY=your-azure-key
OPENAI_API_BASE_URL=https://your-resource.openai.azure.com

Azure OpenAI requires deployment names. The model ID in Open WebUI should match your Azure deployment name.

File: backend/open_webui/routers/openai.py:800

Advanced Configuration

Authentication Types

Open WebUI supports multiple authentication methods:

Bearer Token (Default)

{
  "auth_type": "bearer",
  "key": "your-api-key"
}

File: backend/open_webui/routers/openai.py:149

Custom Headers

Add custom headers to API requests:

{
  "OPENAI_API_CONFIGS": {
    "0": {
      "headers": {
        "X-Custom-Header": "value",
        "Authorization": "Custom auth-scheme token"
      }
    }
  }
}

Model Filtering

Specify which models to expose:

{
  "OPENAI_API_CONFIGS": {
    "0": {
      "model_ids": [
        "gpt-4-turbo",
        "gpt-4",
        "gpt-3.5-turbo"
      ]
    }
  }
}

Connection Types

Tag connections as local or external:

{
  "OPENAI_API_CONFIGS": {
    "0": {
      "connection_type": "local",
      "prefix_id": "local",
      "tags": ["fast", "private"]
    },
    "1": {
      "connection_type": "external",
      "prefix_id": "cloud",
      "tags": ["cloud", "gpt4"]
    }
  }
}

File: backend/open_webui/routers/openai.py:421

OpenAI-Compatible Providers

Anthropic

OPENAI_API_BASE_URL=https://api.anthropic.com/v1
OPENAI_API_KEY=sk-ant-...

Open WebUI automatically detects Anthropic URLs and uses appropriate model mapping.

File: backend/open_webui/routers/openai.py:96

Google AI (Gemini)

GEMINI_API_KEY=your-gemini-key
GEMINI_API_BASE_URL=https://generativelanguage.googleapis.com/v1

OpenRouter

OPENAI_API_BASE_URL=https://openrouter.ai/api/v1
OPENAI_API_KEY=sk-or-...

OpenRouter requires specific headers:

{
  "OPENAI_API_CONFIGS": {
    "0": {
      "headers": {
        "HTTP-Referer": "https://openwebui.com/",
        "X-Title": "Open WebUI"
      }
    }
  }
}

File: backend/open_webui/routers/openai.py:134

Local Providers

LM Studio

OPENAI_API_BASE_URL=http://localhost:1234/v1
OPENAI_API_KEY=lm-studio

Reasoning Models (o1, o3)

Open WebUI automatically handles OpenAI’s reasoning models:

o1-mini / o1-preview

// Converts max_tokens to max_completion_tokens
// Converts system role to user role

File: backend/open_webui/routers/openai.py:101

Responses API

For providers supporting OpenAI’s Responses API:

{
  "OPENAI_API_CONFIGS": {
    "0": {
      "api_type": "responses"
    }
  }
}

Automatic conversion from Chat Completions to Responses API format:

File: backend/open_webui/routers/openai.py:827

API Endpoints

Model Management

• GET /openai/models - List available models
  File: backend/open_webui/routers/openai.py:556

• POST /openai/verify - Verify connection and API key
  File: backend/open_webui/routers/openai.py:659

Completions

• POST /openai/chat/completions - Chat completions
  File: backend/open_webui/routers/openai.py:936

• POST /openai/responses - Responses API (experimental)
  File: backend/open_webui/routers/openai.py:1256

Audio

• POST /openai/audio/speech - Text-to-speech
  File: backend/open_webui/routers/openai.py:272

Embeddings

For RAG and semantic search:

# Automatically routed based on model
POST /openai/embeddings
{
  "model": "text-embedding-3-small",
  "input": "Your text here"
}

File: backend/open_webui/routers/openai.py:1151

Troubleshooting

API Key Invalid

1. Verify the API key format
2. Check for leading/trailing whitespace
3. Ensure the key has necessary permissions
4. Test with the provider’s verify endpoint

Models Not Loading

OpenAI API filters out certain models by default:

• Embedding models
• TTS/Whisper models
• DALL-E models
• Legacy babbage/davinci models

File: backend/open_webui/routers/openai.py:505

Azure OpenAI Errors

Common issues:

• Deployment name doesn’t match model ID
• Incorrect API version
• Missing api-key header for non-Entra auth
• Unsupported parameters for API version

Allowed parameters vary by API version.

File: backend/open_webui/routers/openai.py:754

Rate Limiting

Open WebUI respects provider rate limits. Consider:

• Using multiple API keys with load balancing
• Implementing backoff in Pipelines
• Monitoring usage through provider dashboard

Advanced Features

Logit Bias

Control token generation probabilities:

{
  "logit_bias": {
    "1234": -100,
    "5678": 100
  }
}

File: backend/open_webui/routers/openai.py:1058

User Info Forwarding

Forward user context to API:

ENABLE_FORWARD_USER_INFO_HEADERS=true

Headers:

• X-OpenWebUI-User-Name
• X-OpenWebUI-User-Id
• X-OpenWebUI-User-Email
• X-OpenWebUI-User-Role
• X-OpenWebUI-Chat-Id

File: backend/open_webui/routers/openai.py:80

Model Caching

Models are cached for performance:

MODELS_CACHE_TTL=300  # 5 minutes

File: backend/open_webui/routers/openai.py:482

Best Practices

Use Environment Variables

Keep API keys in environment variables, not in database

Multiple Keys

Configure multiple API keys for load balancing and redundancy

Model Access Control

Use Open WebUI’s RBAC to control model access per user

Monitor Costs

Track usage through provider dashboards and OpenTelemetry