### Description
Since #3212, the instance's voice can be a local engine (a `typ…e: "tts"` integration) instead of Gladys Plus. That voice has two consumers: the "Talk on a speaker" scene action (`MUSIC.PLAY_NOTIFICATION`) and the voice assistant reply. An integration cannot use it.
Field case: the [Karotz integration](https://github.com/smuteau/gladys-karotz). The rabbit can play an audio URL, but its own text-to-speech is an online service, which no longer answers on my rabbit. "Talk on a speaker" works, because the rabbit exposes `play_notification`. But the integration's own "Make the rabbit speak" action cannot get a clip of the voice: no host API route and no SDK call gives one. For the same reason its widget has no "speak" button. The same goes for any integration that drives its own player (a doorbell, a speaker with no `play_notification` feature).
**What changes**
- New host API route **`POST /api/integration/v1/tts/speech_url`** `{ "text", "language" }` → `200 { "url" }`.
- It calls `gladys.tts.getSpeechUrl`, like the two other consumers. The voice is the active provider, never chosen by the caller.
- With an integration provider, the URL is the LAN `http://` URL of the RAM clip (10 minutes, 20-clip cap). With Gladys Plus, it is the signed `https://` URL, returned as is: a player that cannot read HTTPS (the Karotz is one) needs a local voice, as it already does for "Talk on a speaker".
- Without `language`, the first administrator's language is used, as for a scene announcement.
- **A host API route, not a WebSocket command.** The WebSocket carries core → integration commands and integration → core fire-and-forget nudges. Integration → core requests that need an answer are host API routes (`GET /house`, `POST /network_discovery/scan`).
- **Who may call it: every integration type, no manifest flag.** The integration gets back only a clip of a text it supplied itself. The manifest flags (`location`, `network_wake`…) protect personal data or what the core emits on the integration's behalf, and this call is neither. What it consumes (the Gladys Plus TTS quota, or a local engine's CPU) is bounded by the rate limit.
- A `speech: true` flag was considered and set aside. It would mean a new key in the canonical manifest schema (integration-store) and a new line on the install screen, for a call that exposes nothing. It can still be added later without breaking anything, if quota consumption needs the admin's consent. **Your call if you prefer the flag.**
- **Bounds**
- `text`: a non-blank string of at most 2000 characters (`MAX_TTS_TEXT_LENGTH`). A longer text is a `400`, not truncated: the integration chose it and can split it.
- `language`: a tag such as `fr`, `en-US` or `pt_BR`, or `null`. Anything else is a `400`.
- **10 requests per minute per integration** (`MAX_TTS_SPEECH_URLS_PER_MINUTE`, a fixed window like `POST /state`), `429` beyond.
- A refused request (`400`) is not counted. The counter is dropped on uninstall.
- **One failure code.** Every failure of the voice answers `503 SERVICE_UNAVAILABLE`, message `TTS_UNAVAILABLE`:
- no provider running, or the selected one gone;
- a timeout or an invalid clip;
- Gladys Plus answering without a URL;
- Gladys Plus **402 / 403 / 429**. Those are the upsell paths of the Gladys UI; relayed to an integration they would read as "payment required", "forbidden" or "you are rate limited".
- The core logs the cause with the caller's selector. The admin sees the state of the voice on the Voice card.
- Spec: `docs/specs/external-integrations/capabilities/tts-type.md`, new **point 3**, plus its risk, tests and verification. Following the README rule, the route lives in that file, not in the shared C.3/C.8 tables.
- SDK counterpart: GladysAssistant/integration-sdk-js#51, `gladys.getSpeechUrl(text, { language })`.
**Tests**
- `server/test/lib/external-integration/externalIntegration.getSpeechUrl.test.js` covers:
- the Gladys Plus URL;
- the full chain with a real `tts` proxy service: the provider receives the caller's text and language, and the LAN URL serves its clip;
- the default language;
- every `503` path, including Gladys Plus 402/403/429 and a provider's invalid clip, which stays a `503`, not a `400`;
- validation, and the rate limit (per integration, window reset, refused requests not counted, cleanup on uninstall).
- `server/test/controllers/integrationHost/integrationHost.tts.test.js` covers `401`, `200` (Gladys Plus, and LAN URL whose clip is then fetched unauthenticated), `400`, `503` and `429`.
- Local run: full server suite green (`TZ=UTC npm test`: 10,235 passing, 0 failing). 100% line and branch coverage of `externalIntegration.getSpeechUrl.js`. ESLint reports 0 errors on the server; Prettier and `checkjs` are clean on the changed files. The front is not touched.
- **Not tested yet:** the whole chain on a real device. The Karotz integration will call the route once it and the SDK method are available.
### Related request
Forum: https://community.gladysassistant.com/t/utiliser-la-voix-de-gladys-par-une-integration-externe/11644
### Checklist
- [x] If a forum topic or GitHub issue exists, the description links it (`Forum: https://community.gladysassistant.com/t/...` or `Closes #...`)
- [x] Tests pass: `cd server && npm run coverage` (Codecov requires 100% coverage on changed lines) and Cypress (`npm run cypress:run`) if the UI changed (it did not)
- [x] Linter and prettier pass on both front and server (`npm run eslint`, `npm run prettier`): run on the server, front not changed
- [x] No undocumented breaking change
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Summary by CodeRabbit
* **New Features**
* Integrations can request a speech URL through the API, using available text-to-speech providers.
* Requests support an optional language and are limited to 10 per integration per minute.
* **Bug Fixes**
* Invalid requests are rejected, and unavailable speech services return a consistent error.
* **Documentation**
* Updated the integration guide with the speech URL capability and verification steps.