From 64436132f0eeb7ce87c774321fb1860eae420b5a Mon Sep 17 00:00:00 2001 From: HafizMMoaz Date: Mon, 17 Aug 2026 13:58:09 +0500 Subject: [PATCH 1/2] docs: surface per-provider AI model override env vars .env.example only showed AI_TEXT_PROVIDER/AI_IMAGE_PROVIDER/ AI_AUDIO_PROVIDER (which provider to use), never the per-provider model overrides (OPENAI_IMAGE_MODEL, GEMINI_AUDIO_MODEL, etc.) that config/ai.php already wires up for every provider capability. A self-hoster reading only .env.example had no way to discover these existed. These aren't new: laravel/ai already resolves each capability's model independently per provider (confirmed in vendor - e.g. OpenAiProvider::defaultImageModel() falls back to a hardcoded image model, never to the text model), so there was never actually a text-model fallback bug to fix in code. The gap was purely that the override knobs were invisible outside of reading config/ai.php's source directly. --- .env.example | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/.env.example b/.env.example index 2ca8be9ce..48dab7cd0 100644 --- a/.env.example +++ b/.env.example @@ -190,6 +190,28 @@ AI_TEXT_PROVIDER=openai AI_IMAGE_PROVIDER=openai AI_AUDIO_PROVIDER=elevenlabs +# AI Model Overrides (optional) +# Each provider picks a sensible default model per capability on its own - +# these are NOT shared across capabilities, so overriding one (e.g. a text +# model) never affects another (e.g. that same provider's image model). +# Uncomment only the ones you want to override; every provider in play above +# (AI_TEXT_PROVIDER / AI_IMAGE_PROVIDER / AI_AUDIO_PROVIDER) reads its own set. +# OPENAI_TEXT_MODEL= +# OPENAI_IMAGE_MODEL= +# OPENAI_AUDIO_MODEL= +# ANTHROPIC_TEXT_MODEL= +# GEMINI_TEXT_MODEL= +# GEMINI_IMAGE_MODEL= +# GEMINI_AUDIO_MODEL= +# XAI_TEXT_MODEL= +# XAI_IMAGE_MODEL= +# OPENROUTER_TEXT_MODEL= +# OPENROUTER_IMAGE_MODEL= +# OPENROUTER_AUDIO_MODEL= +# ELEVENLABS_AUDIO_MODEL= +# OLLAMA_TEXT_MODEL= +# Ollama has no image/audio-capable driver in laravel/ai - text only. + # ============================================ # Stripe (Cashier — billing) # ============================================ From bc306e8f811f09df1cbc9cbc8035742b2c10519d Mon Sep 17 00:00:00 2001 From: Paulo Castellano Date: Wed, 26 Aug 2026 11:04:48 -0300 Subject: [PATCH 2/2] docs: document AI provider keys, URLs and example model values The override block landed with bare variable names and only covered the five providers whose API keys were already in .env.example. Filled in what a self-hoster still could not discover: - Example values on every model override, taken from laravel/ai's current per-capability defaults, so the ID format is visible (an Ollama tag, an OpenRouter vendor/model path and a bare OpenAI ID look nothing alike). - The keys and URLs for the providers .env.example already advertises as valid but never documented: XAI, GROQ, MISTRAL, DEEPSEEK, OLLAMA_URL and the openai-compatible endpoint. Ollama was the scenario in the original report and OLLAMA_URL matters more there than OLLAMA_TEXT_MODEL does. - GROQ/MISTRAL/DEEPSEEK text models, missing while their providers were listed as options. - openai-compatible has no built-in default model and throws without OPENAI_COMPATIBLE_TEXT_MODEL, so that one is flagged as required. - Corrected the audio provider list: gemini and openrouter implement AudioProvider too. The image and audio lists are no longer written as exhaustive. - Mirrored all of it into docker/.env.docker.example, which carried the same block untouched and is the file Docker self-hosters copy. Its OLLAMA_URL points at the host instead of localhost. --- .env.example | 51 +++++++++++++++++++++++++------------- docker/.env.docker.example | 45 ++++++++++++++++++++++++++++++--- 2 files changed, 76 insertions(+), 20 deletions(-) diff --git a/.env.example b/.env.example index 158a83c41..6a65d466d 100644 --- a/.env.example +++ b/.env.example @@ -185,11 +185,23 @@ ANTHROPIC_API_KEY= GEMINI_API_KEY= OPENROUTER_API_KEY= ELEVENLABS_API_KEY= +# Only needed if you point one of the AI_*_PROVIDER vars below at these providers. +# XAI_API_KEY= +# GROQ_API_KEY= +# MISTRAL_API_KEY= +# DEEPSEEK_API_KEY= +# Ollama runs locally and needs no key — set the URL only if it isn't on the default port. +# OLLAMA_URL=http://localhost:11434 +# Any OpenAI-compatible endpoint (LM Studio, vLLM, LocalAI, ...) via AI_TEXT_PROVIDER=openai-compatible. +# It has no built-in default model, so OPENAI_COMPATIBLE_TEXT_MODEL is required for that provider. +# OPENAI_COMPATIBLE_URL= +# OPENAI_COMPATIBLE_API_KEY= +# OPENAI_COMPATIBLE_TEXT_MODEL= # AI Provider Selection -# text: openai | anthropic | gemini | openrouter | xai | groq | mistral | deepseek | ... -# image: openai | gemini | xai | openrouter -# audio: openai | elevenlabs +# text: openai | anthropic | gemini | openrouter | xai | groq | mistral | deepseek | ollama | ... +# image: openai | gemini | xai | openrouter | ... +# audio: openai | elevenlabs | gemini | openrouter | ... # OpenRouter is a first-class laravel/ai provider (AI_TEXT_PROVIDER=openrouter + OPENROUTER_API_KEY). AI_TEXT_PROVIDER=openai AI_IMAGE_PROVIDER=openai @@ -201,20 +213,25 @@ AI_AUDIO_PROVIDER=elevenlabs # model) never affects another (e.g. that same provider's image model). # Uncomment only the ones you want to override; every provider in play above # (AI_TEXT_PROVIDER / AI_IMAGE_PROVIDER / AI_AUDIO_PROVIDER) reads its own set. -# OPENAI_TEXT_MODEL= -# OPENAI_IMAGE_MODEL= -# OPENAI_AUDIO_MODEL= -# ANTHROPIC_TEXT_MODEL= -# GEMINI_TEXT_MODEL= -# GEMINI_IMAGE_MODEL= -# GEMINI_AUDIO_MODEL= -# XAI_TEXT_MODEL= -# XAI_IMAGE_MODEL= -# OPENROUTER_TEXT_MODEL= -# OPENROUTER_IMAGE_MODEL= -# OPENROUTER_AUDIO_MODEL= -# ELEVENLABS_AUDIO_MODEL= -# OLLAMA_TEXT_MODEL= +# The values below are laravel/ai's current defaults, shown as format examples - +# they move with the package, so don't treat them as a contract. +# OPENAI_TEXT_MODEL=gpt-5.4 +# OPENAI_IMAGE_MODEL=gpt-image-2 +# OPENAI_AUDIO_MODEL=gpt-4o-mini-tts +# ANTHROPIC_TEXT_MODEL=claude-sonnet-5 +# GEMINI_TEXT_MODEL=gemini-3.6-flash +# GEMINI_IMAGE_MODEL=gemini-3.1-flash-image-preview +# GEMINI_AUDIO_MODEL=gemini-2.5-flash-preview-tts +# XAI_TEXT_MODEL=grok-4.20-non-reasoning +# XAI_IMAGE_MODEL=grok-imagine-image +# OPENROUTER_TEXT_MODEL=anthropic/claude-sonnet-4.6 +# OPENROUTER_IMAGE_MODEL=google/gemini-3.1-flash-image-preview +# OPENROUTER_AUDIO_MODEL=google/gemini-3.1-flash-tts-preview +# ELEVENLABS_AUDIO_MODEL=eleven_multilingual_v2 +# GROQ_TEXT_MODEL=openai/gpt-oss-120b +# MISTRAL_TEXT_MODEL=mistral-medium-latest +# DEEPSEEK_TEXT_MODEL=deepseek-v4-flash +# OLLAMA_TEXT_MODEL=llama3.1:8b # Ollama has no image/audio-capable driver in laravel/ai - text only. # ============================================ diff --git a/docker/.env.docker.example b/docker/.env.docker.example index 60d7ce479..128d437bd 100644 --- a/docker/.env.docker.example +++ b/docker/.env.docker.example @@ -147,16 +147,55 @@ ANTHROPIC_API_KEY= GEMINI_API_KEY= OPENROUTER_API_KEY= ELEVENLABS_API_KEY= +# Only needed if you point one of the AI_*_PROVIDER vars below at these providers. +# XAI_API_KEY= +# GROQ_API_KEY= +# MISTRAL_API_KEY= +# DEEPSEEK_API_KEY= +# Ollama runs locally and needs no key — from inside Docker point it at the host, not localhost. +# OLLAMA_URL=http://host.docker.internal:11434 +# Any OpenAI-compatible endpoint (LM Studio, vLLM, LocalAI, ...) via AI_TEXT_PROVIDER=openai-compatible. +# It has no built-in default model, so OPENAI_COMPATIBLE_TEXT_MODEL is required for that provider. +# OPENAI_COMPATIBLE_URL= +# OPENAI_COMPATIBLE_API_KEY= +# OPENAI_COMPATIBLE_TEXT_MODEL= # AI Provider Selection -# text: openai | anthropic | gemini | openrouter | xai | groq | mistral | deepseek | ... -# image: openai | gemini | xai | openrouter -# audio: openai | elevenlabs +# text: openai | anthropic | gemini | openrouter | xai | groq | mistral | deepseek | ollama | ... +# image: openai | gemini | xai | openrouter | ... +# audio: openai | elevenlabs | gemini | openrouter | ... # OpenRouter is a first-class laravel/ai provider (AI_TEXT_PROVIDER=openrouter + OPENROUTER_API_KEY). AI_TEXT_PROVIDER=openai AI_IMAGE_PROVIDER=openai AI_AUDIO_PROVIDER=elevenlabs +# AI Model Overrides (optional) +# Each provider picks a sensible default model per capability on its own - +# these are NOT shared across capabilities, so overriding one (e.g. a text +# model) never affects another (e.g. that same provider's image model). +# Uncomment only the ones you want to override; every provider in play above +# (AI_TEXT_PROVIDER / AI_IMAGE_PROVIDER / AI_AUDIO_PROVIDER) reads its own set. +# The values below are laravel/ai's current defaults, shown as format examples - +# they move with the package, so don't treat them as a contract. +# OPENAI_TEXT_MODEL=gpt-5.4 +# OPENAI_IMAGE_MODEL=gpt-image-2 +# OPENAI_AUDIO_MODEL=gpt-4o-mini-tts +# ANTHROPIC_TEXT_MODEL=claude-sonnet-5 +# GEMINI_TEXT_MODEL=gemini-3.6-flash +# GEMINI_IMAGE_MODEL=gemini-3.1-flash-image-preview +# GEMINI_AUDIO_MODEL=gemini-2.5-flash-preview-tts +# XAI_TEXT_MODEL=grok-4.20-non-reasoning +# XAI_IMAGE_MODEL=grok-imagine-image +# OPENROUTER_TEXT_MODEL=anthropic/claude-sonnet-4.6 +# OPENROUTER_IMAGE_MODEL=google/gemini-3.1-flash-image-preview +# OPENROUTER_AUDIO_MODEL=google/gemini-3.1-flash-tts-preview +# ELEVENLABS_AUDIO_MODEL=eleven_multilingual_v2 +# GROQ_TEXT_MODEL=openai/gpt-oss-120b +# MISTRAL_TEXT_MODEL=mistral-medium-latest +# DEEPSEEK_TEXT_MODEL=deepseek-v4-flash +# OLLAMA_TEXT_MODEL=llama3.1:8b +# Ollama has no image/audio-capable driver in laravel/ai - text only. + # Telemetry — disabled by default in Docker dev. NIGHTWATCH_ENABLED=false NIGHTWATCH_TOKEN=