Adam SmithandClaude Opus 5
13c60c242a
Every label, description and error in this integration's UI renders untranslated in a live Home Assistant. homeassistant.helpers.translation loads `<integration>/translations/<lang>.json` and nothing else (there is no fallback to strings.json -- see translation.py's `integration.file_path / "translations" / file_name`), and this component has no translations/ directory at all. Core integrations get away with shipping only strings.json because core generates translations/ as a release step, resolving the `[%key:...%]` references strings.json uses to avoid duplicating text. Vendoring the source tree copies the input and leaves out the generated output, so the defect arrived with commit 48195c9 and would hit anyone who installs this from HACS. Rather than hand-write the file once and let it rot on the next upstream re-sync, scripts/generate_translations.py regenerates it: - `common::...` references resolve against the *installed* homeassistant package's own strings.json, so the text matches what core would have produced for that HA version. - `component::openai_compatible::...` self-references resolve against strings.json itself, repeatedly, since a reference can point at another reference. - Anything it cannot resolve (an unknown namespace, a reference to a different integration, a path that does not exist, a marker surviving the final pass) is a hard error rather than a raw `[%key:...%]` marker shipped into a label. All 70 references in strings.json resolve; the generated file carries config, config_subentries, exceptions, issues, selector and services. tests/test_translations.py locks it down: en.json must exist, must equal what the generator produces, and must contain no surviving markers. Verified the check actually catches drift rather than passing vacuously -- perturbing one label fails it, and deleting the file fails it. Local: 141 passed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NxJYWgGJtCw13qUHZtG8ki
OpenAI Compatible for Home Assistant
Home Assistant's built-in OpenAI integration, with one change that matters: the
API base URL is configurable. Point Home Assistant's conversation agent, AI Task,
speech-to-text and text-to-speech at any OpenAI-compatible endpoint — LiteLLM, vLLM,
OpenRouter, a gateway of your own — instead of only api.openai.com.
Everything else is upstream Home Assistant code, vendored unmodified, so behavior and options match the core integration you already know.
Why this exists
Core's openai_conversation hardcodes OpenAI's endpoint. If you run a proxy for cost
control, routing, key management or privacy, or you self-host models, there is no way to
tell the core integration about it. This fork adds a Base URL field to the config
flow and threads it to every client it creates.
What you get
Everything the core integration provides, as config subentries you can add more than one of:
- Conversation agent — an Assist conversation entity, with the LLM Assist API, tool calling, and the full upstream option set (model, temperature, top-p, max tokens, reasoning effort, verbosity, web search, code interpreter, service tier, …)
- AI Task — for
ai_task.generate_data/ image generation - Speech-to-text — an STT entity
- Text-to-speech — a TTS entity, with speed control
- Actions —
openai_compatible.generate_contentandopenai_compatible.generate_image
Requirements
- Home Assistant 2026.9.0 or newer
- An OpenAI-compatible endpoint (see Endpoint compatibility)
Installation
HACS (custom repository)
- HACS → ⋮ → Custom repositories
- Add
https://github.com/adamjs83/ha-openai-compatible, category Integration - Find OpenAI Compatible in HACS, download it, and restart Home Assistant
- Settings → Devices & services → Add integration → OpenAI Compatible
Manual
Copy custom_components/openai_compatible/ into your Home Assistant
config/custom_components/ directory and restart.
Configuration
The initial dialog asks for two things:
| Field | Notes |
|---|---|
| Base URL | Full URL including any version path, e.g. https://api.openai.com/v1. Passed to the OpenAI SDK as-is. |
| API key | Optional — leave blank for an endpoint that does not authenticate. |
Then add one subentry per capability you want (conversation, AI Task, STT, TTS), each with its own model and options.
Base URL rules
- Only
httpandhttpsare accepted; the URL must include a host. - Whitespace and trailing slashes are stripped.
- Include the version path if your server expects one. Most do:
/v1. - Credentials embedded in the URL (
https://user:pass@host/v1) are rejected. Put the token in the API key field — it is stored as a secret and kept out of logs, while a base URL is echoed back in error and log messages. - Re-authenticating (rotating the API key) keeps your configured base URL.
Empty API keys
Local endpoints often require no auth. Leave the API key blank and the integration sends
the placeholder not-required — the OpenAI SDK refuses to build a client with no key at
all, so something has to be sent, and servers that ignore auth ignore it.
Endpoint examples
| Server | Typical base URL |
|---|---|
| OpenAI | https://api.openai.com/v1 |
| LiteLLM | http://litellm.local:4000/v1 |
| vLLM | http://vllm.local:8000/v1 |
| OpenRouter | https://openrouter.ai/api/v1 |
| Azure OpenAI (via a proxy) | your proxy's URL |
Endpoint compatibility
This is the important caveat. Upstream uses OpenAI's Responses API, not Chat
Completions, so a server that only implements /v1/chat/completions will not work
for conversation or AI Task.
| Feature | Endpoint the server must implement |
|---|---|
| Setup / connection test | GET /v1/models |
| Conversation, AI Task | POST /v1/responses |
| Text-to-speech | POST /v1/audio/speech |
| Speech-to-text | POST /v1/audio/transcriptions |
generate_image action |
POST /v1/images/generations |
You only need the endpoints for the subentries you actually add. Check your server's docs for Responses API support before filing a bug — LiteLLM and vLLM have it in recent versions; several popular local servers still do not.
Model names
The default and "recommended" model names come from upstream and are OpenAI's
(gpt-4o-mini, gpt-4o-mini-tts, gpt-4o-mini-transcribe, …). Set the model your
endpoint actually serves in each subentry's options. Upstream's lists of models that
don't support web search, image generation, and so on are also keyed to OpenAI names, so
they won't match a third-party model string — the endpoint's own error is what you'll
see if you ask for something it can't do.
Relationship to Home Assistant core
custom_components/openai_compatible/ is derived from
homeassistant/components/openai_conversation/ at core tag 2026.9.2
(commit recorded in UPSTREAM_COMMIT),
with the domain renamed to openai_compatible and the base URL made configurable.
Base-URL handling lives in its own module,
url_util.py, deliberately separate
from the vendored files so re-syncing with core stays a clean merge.
Installing this alongside core's OpenAI integration is fine — different domain, separate config entries. This is not an official Home Assistant integration and is not affiliated with or endorsed by OpenAI.
Development
Requires Python 3.14+ (Home Assistant 2026.9's floor).
pip install -r requirements_test.txt
pytest tests/ -v
The suite is core's openai_conversation test suite, ported as a regression net, plus
tests for the base-URL behavior this fork adds.
License
Apache-2.0, inherited from Home Assistant core. See NOTICE for attribution.