Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python

Add GPT-5 support with automatic parameter detection for OpenAI API

Murtaza Nasired022c3d62d4
diff --git a/config/env.asr.example b/config/env.asr.example
index 0b2255ae..8edfffe6 100644
--- a/config/env.asr.example
+++ b/config/env.asr.example
@@ -12,6 +12,27 @@ TEXT_MODEL_BASE_URL=https://openrouter.ai/api/v1
TEXT_MODEL_API_KEY=your_openrouter_api_key
TEXT_MODEL_NAME=openai/gpt-4o-mini
+# --- GPT-5 Specific Settings (only used with OpenAI API and GPT-5 models) ---
+# If using GPT-5 models (gpt-5, gpt-5-mini, gpt-5-nano, gpt-5-chat-latest) with OpenAI API,
+# these parameters will be used instead of temperature.
+#
+# Example GPT-5 configuration:
+# TEXT_MODEL_BASE_URL=https://api.openai.com/v1
+# TEXT_MODEL_NAME=gpt-5-mini
+#
+# Reasoning effort: minimal, low, medium, high (default: medium)
+# - minimal: Fastest responses, minimal reasoning tokens
+# - low: Fast responses with basic reasoning
+# - medium: Balanced reasoning and speed (recommended)
+# - high: Maximum reasoning for complex tasks
+GPT5_REASONING_EFFORT=medium
+#
+# Verbosity: low, medium, high (default: medium)
+# - low: Concise responses
+# - medium: Balanced detail
+# - high: Detailed explanations
+GPT5_VERBOSITY=medium
+
# --- Transcription Service (ASR Endpoint) ---
# Setting this to true enables all ASR features including speaker diarization
# Note: File chunking is NOT supported with ASR endpoints
diff --git a/config/env.whisper.example b/config/env.whisper.example
index 3a2bc055..5fadf7b9 100644
--- a/config/env.whisper.example
+++ b/config/env.whisper.example
@@ -12,6 +12,27 @@ TEXT_MODEL_BASE_URL=https://openrouter.ai/api/v1
TEXT_MODEL_API_KEY=your_openrouter_api_key
TEXT_MODEL_NAME=openai/gpt-4o-mini
+# --- GPT-5 Specific Settings (only used with OpenAI API and GPT-5 models) ---
+# If using GPT-5 models (gpt-5, gpt-5-mini, gpt-5-nano, gpt-5-chat-latest) with OpenAI API,
+# these parameters will be used instead of temperature.
+#
+# Example GPT-5 configuration:
+# TEXT_MODEL_BASE_URL=https://api.openai.com/v1
+# TEXT_MODEL_NAME=gpt-5-mini
+#
+# Reasoning effort: minimal, low, medium, high (default: medium)
+# - minimal: Fastest responses, minimal reasoning tokens
+# - low: Fast responses with basic reasoning
+# - medium: Balanced reasoning and speed (recommended)
+# - high: Maximum reasoning for complex tasks
+GPT5_REASONING_EFFORT=medium
+#
+# Verbosity: low, medium, high (default: medium)
+# - low: Concise responses
+# - medium: Balanced detail
+# - high: Detailed explanations
+GPT5_VERBOSITY=medium
+
# --- Transcription Service (OpenAI Whisper API) ---
TRANSCRIPTION_BASE_URL=https://api.openai.com/v1
TRANSCRIPTION_API_KEY=your_openai_api_key
diff --git a/docs/GPT5_SUPPORT.md b/docs/GPT5_SUPPORT.md
new file mode 100644
index 00000000..c5782394
--- /dev/null
+++ b/docs/GPT5_SUPPORT.md
@@ -0,0 +1,130 @@
+# GPT-5 Support in Speakr
+
+Speakr now supports OpenAI's GPT-5 model family with proper parameter handling according to OpenAI's Chat Completions API specifications.
+
+## Requirements
+
+- **OpenAI Python SDK**: Version 2.2.0 or higher (updated in `requirements.txt`)
+- GPT-5 support was added to the OpenAI SDK in 2025
+
+## Overview
+
+GPT-5 models require different API parameters compared to previous models like GPT-4. When using GPT-5 models with the official OpenAI API, Speakr automatically detects this and adjusts the API calls accordingly.
+
+## Supported GPT-5 Models
+
+- `gpt-5` - Best for complex reasoning, broad world knowledge, and code-heavy tasks
+- `gpt-5-mini` - Cost-optimized reasoning and chat; balances speed, cost, and capability
+- `gpt-5-nano` - High-throughput tasks, especially simple instruction-following
+- `gpt-5-chat-latest` - Latest GPT-5 chat model
+
+## Key Differences from GPT-4
+
+### Unsupported Parameters
+GPT-5 models **do not support** the following parameters:
+- `temperature` - Replaced by `reasoning_effort` and `verbosity`
+- `top_p` - Not supported
+- `logprobs` - Not supported
+
+### New GPT-5 Parameters
+
+#### Reasoning Effort
+Controls how many reasoning tokens the model generates before producing a response.
+
+- **minimal** - Fastest responses, minimal reasoning tokens (best for simple tasks)
+- **low** - Fast responses with basic reasoning
+- **medium** - Balanced reasoning and speed (default, recommended)
+- **high** - Maximum reasoning for complex tasks like coding and multi-step planning
+
+#### Verbosity
+Controls how many output tokens are generated.
+
+- **low** - Concise responses
+- **medium** - Balanced detail (default)
+- **high** - Thorough explanations and detailed code
+
+#### Token Limit
+- Uses `max_completion_tokens` instead of `max_tokens`
+
+## Configuration
+
+### Environment Variables
+
+Add these settings to your `.env` file:
+
+```bash
+# Use OpenAI API endpoint
+TEXT_MODEL_BASE_URL=https://api.openai.com/v1
+TEXT_MODEL_API_KEY=your_openai_api_key
+TEXT_MODEL_NAME=gpt-5-mini
+
+# GPT-5 specific parameters (optional, defaults shown)
+GPT5_REASONING_EFFORT=medium
+GPT5_VERBOSITY=medium
+```
+
+### Example Configurations
+
+#### Fast Summarization (Low Cost)
+```bash
+TEXT_MODEL_NAME=gpt-5-nano
+GPT5_REASONING_EFFORT=minimal
+GPT5_VERBOSITY=low
+```
+
+#### Standard Usage (Recommended)
+```bash
+TEXT_MODEL_NAME=gpt-5-mini
+GPT5_REASONING_EFFORT=medium
+GPT5_VERBOSITY=medium
+```
+
+#### Complex Analysis (High Quality)
+```bash
+TEXT_MODEL_NAME=gpt-5
+GPT5_REASONING_EFFORT=high
+GPT5_VERBOSITY=high
+```
+
+## Automatic Detection
+
+Speakr automatically detects when you're using:
+1. A GPT-5 model (based on model name)
+2. The official OpenAI API (based on base URL containing `api.openai.com`)
+
+When both conditions are met, it automatically:
+- Removes `temperature` parameter from API calls
+- Adds `reasoning_effort` parameter
+- Adds `verbosity` parameter
+- Uses `max_completion_tokens` instead of `max_tokens`
+- Logs that GPT-5 parameters are being used
+
+## Use Cases
+
+### Summarization
+- **Fast summaries**: `gpt-5-nano` with `minimal` effort and `low` verbosity
+- **Standard summaries**: `gpt-5-mini` with `medium` effort and `medium` verbosity
+- **Detailed summaries**: `gpt-5` with `medium` effort and `high` verbosity
+
+### Chat
+- **Quick Q&A**: `gpt-5-mini` with `minimal` effort and `low` verbosity
+- **Standard conversation**: `gpt-5-mini` with `low` effort and `medium` verbosity
+- **Complex analysis**: `gpt-5` with `high` effort and `medium` verbosity
+
+## Troubleshooting
+
+### Error: "Unsupported parameter 'temperature'"
+This means GPT-5 detection failed. Check that:
+1. `TEXT_MODEL_BASE_URL` contains `api.openai.com`
+2. `TEXT_MODEL_NAME` starts with `gpt-5` or is one of: `gpt-5`, `gpt-5-mini`, `gpt-5-nano`, `gpt-5-chat-latest`
+
+### Error: Invalid reasoning_effort value
+Valid values are: `minimal`, `low`, `medium`, `high`
+
+### Error: Invalid verbosity value
+Valid values are: `low`, `medium`, `high`
+
+## References
+
+- [OpenAI GPT-5 Documentation](https://platform.openai.com/docs/guides/latest-model)
+- [OpenAI Chat Completions API](https://platform.openai.com/docs/api-reference/chat)
diff --git a/requirements.txt b/requirements.txt
index c2180d0b..946ddb99 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -5,7 +5,7 @@ flask-wtf==1.2.2
flask-bcrypt==1.0.1
Flask-Limiter==3.5.0
email-validator==2.2.0
-openai==1.3.0
+openai>=2.2.0
werkzeug==2.3.7
gunicorn==21.2.0
python-dotenv==1.0.0
diff --git a/src/app.py b/src/app.py
index c3788e7f..78fd53de 100644
--- a/src/app.py
+++ b/src/app.py
@@ -2133,42 +2133,88 @@ except Exception as client_init_e:
app.logger.error(f"Failed to initialize LLM client: {client_init_e}", exc_info=True)
client = None
+def is_gpt5_model(model_name):
+ """
+ Check if the model is a GPT-5 series model that requires special API parameters.
+
+ Args:
+ model_name: The model name string
+
+ Returns:
+ Boolean indicating if this is a GPT-5 model
+ """
+ if not model_name:
+ return False
+ model_lower = model_name.lower()
+ return model_lower.startswith('gpt-5') or model_lower in ['gpt-5', 'gpt-5-mini', 'gpt-5-nano', 'gpt-5-chat-latest']
+
+def is_using_openai_api():
+ """
+ Check if we're using the official OpenAI API (not OpenRouter or other providers).
+
+ Returns:
+ Boolean indicating if this is the OpenAI API
+ """
+ return TEXT_MODEL_BASE_URL and 'api.openai.com' in TEXT_MODEL_BASE_URL
+
def call_llm_completion(messages, temperature=0.7, response_format=None, stream=False, max_tokens=None):
"""
Centralized function for LLM API calls with proper error handling and logging.
-
+
Args:
messages: List of message dicts with 'role' and 'content'
- temperature: Sampling temperature (0-1)
+ temperature: Sampling temperature (0-1) - ignored for GPT-5 models
response_format: Optional response format dict (e.g., {"type": "json_object"})
stream: Whether to stream the response
max_tokens: Optional maximum tokens to generate
-
+
Returns:
OpenAI completion object or generator (if streaming)
"""
if not client:
raise ValueError("LLM client not initialized")
-
+
if not TEXT_MODEL_API_KEY:
raise ValueError("TEXT_MODEL_API_KEY not configured")
-
+
try:
+ # Check if we're using GPT-5 with OpenAI API
+ using_gpt5 = is_gpt5_model(TEXT_MODEL_NAME) and is_using_openai_api()
+
completion_args = {
"model": TEXT_MODEL_NAME,
"messages": messages,
- "temperature": temperature,
"stream": stream
}
-
+
+ if using_gpt5:
+ # GPT-5 models don't support temperature, top_p, or logprobs
+ # They use reasoning_effort and verbosity instead
+ app.logger.debug(f"Using GPT-5 model: {TEXT_MODEL_NAME} - applying GPT-5 specific parameters")
+
+ # Get GPT-5 specific parameters from environment variables
+ reasoning_effort = os.environ.get("GPT5_REASONING_EFFORT", "medium") # minimal, low, medium, high
+ verbosity = os.environ.get("GPT5_VERBOSITY", "medium") # low, medium, high
+
+ # Add GPT-5 specific parameters
+ completion_args["reasoning_effort"] = reasoning_effort
+ completion_args["verbosity"] = verbosity
+
+ # Use max_completion_tokens instead of max_tokens for GPT-5
+ if max_tokens:
+ completion_args["max_completion_tokens"] = max_tokens
+ else:
+ # Non-GPT-5 models use standard parameters
+ completion_args["temperature"] = temperature
+
+ if max_tokens:
+ completion_args["max_tokens"] = max_tokens
+
if response_format:
completion_args["response_format"] = response_format
-
- if max_tokens:
- completion_args["max_tokens"] = max_tokens
-
+
return client.chat.completions.create(**completion_args)
-
+
except Exception as e:
app.logger.error(f"LLM API call failed: {e}")
raise