VoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription & audiobook creation in 646 languages.
Python aiaudiobookcudadubbingelevenlabs-alternativehuggingfacelocal-firstmlxomnivoice-studiospeech-to-texttext-to-speechtranscriptiontranslatettsvoice-aivoice-cloningvoice-generationvoicestudioworkflow
"""
OpenAI-compatible TTS & STT API — Phase 3.2 (ROADMAP.md P0).
Drop-in replacement for OpenAI's audio endpoints so that any tool speaking the
OpenAI protocol (the official ``openai`` SDK, the OpenAI Agents SDK voice
pipeline, pipecat, LiveKit, litellm, n8n, etc.) can use VoiceStudio as a local
backend with zero code changes.
Endpoints
─────────
POST /v1/audio/speech → TTS (text → mp3/opus/aac/flac/wav/pcm)
POST /v1/audio/transcriptions → STT (audio file → text/json)
POST /v1/audio/translations → STT + translate to English (Whisper engines)
GET /v1/models → OpenAI aliases + installed engines
GET /v1/models/{id} → one model
GET /v1/audio/voices → list available voices (VoiceStudio extension)
Errors on these routes use OpenAI's shape,
``{"error": {"message", "type", "param", "code"}}``, so the SDK raises typed
errors with a readable message; request-validation failures are 400 (OpenAI's
status) rather than FastAPI's 422. The original ``detail`` is kept alongside
for existing VoiceStudio clients.
The router delegates to the active TTS/ASR backends via the same adapter
protocol used by the rest of VoiceStudio, so engine selection, GPU offloading,
model loading, and invisible provenance watermarking (services.watermark,
#1169) all work identically.
Reference: https://platform.openai.com/docs/api-reference/audio
"""
from __future__ import annotations
import asyncio
import base64
import io
import json
import logging
import os
import re
import tempfile
from typing import Annotated, Any, Literal, Optional, Union
from fastapi import APIRouter, File, Form, HTTPException, UploadFile
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse, StreamingResponse
from fastapi.routing import APIRoute
from pydantic import BaseModel, Field, field_validator
from starlette.exceptions import HTTPException as StarletteHTTPException
from services.model_manager import _gpu_pool, run_on_gpu_pool_guarded
from core.http_headers import content_disposition
from core.path_security import contained_join, upload_suffix
from services.audio_io import OPUS_CODEC_ARGS, OPUS_SAMPLE_RATE
logger = logging.getLogger("omnivoice.openai_compat")
# ── OpenAI-shaped errors ────────────────────────────────────────────────────
class OpenAIError(HTTPException):
"""An HTTPException that also names OpenAI's ``param`` and ``code``."""
def __init__(self, status_code: int, message: Union[str, dict], *, param: Optional[str] = None,
code: Optional[str] = None, headers: Optional[dict] = None):
super().__init__(status_code=status_code, detail=message, headers=headers)
self.param = param
self.code = code
def _error_type(status: int) -> str:
if status == 401:
return "authentication_error"
if status == 403:
return "permission_error"
if status == 429:
return "rate_limit_error"
if status >= 500:
return "server_error"
return "invalid_request_error"
def _openai_error_body(status: int, message: str, *, param=None, code=None, detail=None) -> dict:
return {
"error": {
"message": message,
"type": _error_type(status),
"param": param,
"code": code,
},
# Kept for VoiceStudio-aware clients that read FastAPI's `detail`.
"detail": message if detail is None else detail,
}
def _http_error_response(exc: StarletteHTTPException) -> JSONResponse:
detail = exc.detail
param = getattr(exc, "param", None)
code = getattr(exc, "code", None)
if isinstance(detail, dict):
message = str(detail.get("message") or detail.get("detail") or json.dumps(detail))
code = code or (detail.get("error") if isinstance(detail.get("error"), str) else None)
elif isinstance(detail, str):
message = detail
else:
message = json.dumps(detail, default=str)
return JSONResponse(
status_code=exc.status_code,
content=_openai_error_body(exc.status_code, message, param=param, code=code, detail=detail),
headers=getattr(exc, "headers", None),
)
def _validation_error_response(exc: RequestValidationError) -> JSONResponse:
# Echo neither `input` (can be an audio-sized body) nor `ctx` (can hold
# a non-JSON exception object) — same hygiene as main's 422 handler.
errors = [
{"loc": list(e.get("loc", ())), "msg": str(e.get("msg", "")), "type": str(e.get("type", ""))}
for e in exc.errors()
]
first = errors[0] if errors else {"loc": [], "msg": "Invalid request"}
loc = [str(p) for p in first["loc"] if p not in ("body", "query", "path", "header")]
param = ".".join(loc) or None
message = f"Invalid value for '{param}': {first['msg']}" if param else first["msg"]
return JSONResponse(
status_code=400,
content=_openai_error_body(400, message, param=param, code="invalid_value", detail=errors),
)
class OpenAIErrorRoute(APIRoute):
"""Route class that renders every error raised by a /v1 handler in
OpenAI's error shape. Scoped to this router only — the rest of the API
keeps FastAPI's ``{"detail": ...}`` contract."""
def get_route_handler(self):
handler = super().get_route_handler()
async def route(request):
try:
return await handler(request)
except RequestValidationError as exc:
return _validation_error_response(exc)
except StarletteHTTPException as exc:
return _http_error_response(exc)
return route
router = APIRouter(prefix="/v1", tags=["OpenAI-Compatible Audio API"], route_class=OpenAIErrorRoute)
# ── OpenAI model / voice aliases ────────────────────────────────────────────
#: OpenAI TTS model ids advertised by GET /v1/models. Any id matching
#: ``_OPENAI_TTS_MODEL_RE`` (dated snapshots, future ``gpt-*-tts`` ids) is
#: accepted too, so an SDK upgrade that changes its default cannot 400.
OPENAI_TTS_MODELS = ("tts-1", "tts-1-hd", "gpt-4o-mini-tts")
_OPENAI_TTS_MODEL_RE = re.compile(r"^(tts-1(-hd)?|gpt-[a-z0-9.]+(-mini)?-tts)(-[0-9a-z-]+)?$")
#: OpenAI STT model ids. /v1/audio/transcriptions always uses the active ASR
#: engine; these are listed so clients that validate the model list find them.
OPENAI_STT_MODELS = ("whisper-1", "gpt-4o-transcribe", "gpt-4o-mini-transcribe")
# OpenAI's named voices aren't real voices in VoiceStudio. Map them to the
# active engine's default voice so callers that hardcode "alloy" (or the
# Agents SDK's default "ash") don't get an engine-preset error.
_OPENAI_VOICE_ALIASES = {
"alloy", "ash", "ballad", "cedar", "coral", "echo", "fable", "marin",
"nova", "onyx", "sage", "shimmer", "verse",
}
def is_openai_tts_model(model_id: str) -> bool:
return model_id in OPENAI_TTS_MODELS or bool(_OPENAI_TTS_MODEL_RE.match(model_id))
def _voice_name_key(name: Any) -> str:
"""Comparison key for a voice-profile name: Unicode-normalised, trimmed,
case-folded — so ``"Narrator"``, ``" narrator "`` and ``"NARRATOR"`` match
(SQLite's ``LOWER()`` folds ASCII only)."""
import unicodedata
return unicodedata.normalize("NFKC", str(name or "")).strip().casefold()
def _name_is_reserved(name: Any) -> bool:
"""A profile named like an OpenAI voice or ``default`` keeps that word's
built-in meaning on /v1/audio/speech; it stays reachable by id."""
key = _voice_name_key(name)
return key == "default" or key in _OPENAI_VOICE_ALIASES
def _resolve_voice_profile(voice: str):
"""Resolve ``voice`` to a voice-profile row (#2617).
An exact profile id always wins; otherwise a unique case-insensitive
profile name matches. Several profiles sharing the name is a 409 that
lists their ids, so the caller can pick one instead of getting a silently
arbitrary voice. Returns ``None`` when nothing matches (the caller treats
``voice`` as an engine preset) or the profile store can't be read.
"""
try:
from core.db import db_conn
with db_conn() as conn:
row = conn.execute("SELECT * FROM voice_profiles WHERE id=?", (voice,)).fetchone()
if row is not None:
return row
key = _voice_name_key(voice)
if not key or _name_is_reserved(key):
return None
ids = [
r["id"]
for r in conn.execute("SELECT id, name FROM voice_profiles ORDER BY created_at, id")
if _voice_name_key(r["name"]) == key
]
if len(ids) == 1:
return conn.execute("SELECT * FROM voice_profiles WHERE id=?", (ids[0],)).fetchone()
except Exception:
logger.warning("Voice profiles could not be read; treating voice as an engine preset")
return None
if len(ids) > 1:
message = (
f"{len(ids)} voice profiles are named '{voice.strip()}'. Pass one of their "
f"ids as `voice` instead, or rename the profiles so the name is unique: "
+ ", ".join(ids)
)
raise OpenAIError(
409,
{"message": message, "matching_ids": ids},
param="voice",
code="ambiguous_voice",
)
return None
# ── Schemas ─────────────────────────────────────────────────────────────────
SpeechFormat = Literal["mp3", "opus", "aac", "flac", "wav", "pcm"]
class SpeechRequest(BaseModel):
"""POST /v1/audio/speech — mirrors OpenAI's CreateSpeechRequest."""
model: str = Field(
default="omnivoice",
description=(
"TTS model to use. Maps to VoiceStudio engine IDs: "
"'omnivoice', 'voxcpm2', 'cosyvoice', 'mlx-audio', 'kittentts', 'moss-tts-nano'. "
"OpenAI model ids ('tts-1', 'tts-1-hd', 'gpt-4o-mini-tts', dated "
"snapshots) are aliases for the active engine."
),
)
input: str = Field(
...,
max_length=4096,
description="The text to synthesize. Max 4096 characters.",
)
voice: Union[str, dict] = Field(
default="default",
description=(
"Voice to use. For VoiceStudio: pass a voice profile ID, a voice "
"profile name (case-insensitive; an ID wins, and a name shared by "
"several profiles is a 409 listing their IDs), 'default', "
"or a KittenTTS preset name (also accepted as OpenAI's "
"{\"id\": ...} object). OpenAI voice names (alloy, ash, ballad, "
"coral, echo, fable, nova, onyx, sage, shimmer, verse, marin, "
"cedar) are accepted and mapped to the engine default."
),
)
instructions: Optional[str] = Field(
default=None,
max_length=4096,
description="OpenAI's voice-style instructions, forwarded as the engine's style "
"instruction (OmniVoice keeps only its voice-design tags). VoiceStudio's "
"`instruct` wins when both are sent.",
)
response_format: SpeechFormat = Field(
default="mp3",
description="Audio output format. `pcm` is raw 24 kHz 16-bit little-endian mono.",
)
speed: float = Field(
default=1.0,
ge=0.25,
le=4.0,
description="Speed of the generated audio (0.25 to 4.0).",
)
stream_format: Optional[Literal["audio", "sse"]] = Field(
default=None,
description="'audio' streams raw audio bytes (the default); 'sse' streams "
"`speech.audio.delta` / `speech.audio.done` server-sent events.",
)
# VoiceStudio extensions (not part of OpenAI spec, but accepted if sent)
language: Optional[str] = Field(default=None, description="Language code (ISO 639-1)")
description: Optional[str] = Field(
default=None,
description="Voice description for voice design (VoxCPM2 only). "
"E.g. 'young female, warm tone, slight British accent'.",
)
instruct: Optional[str] = Field(default=None, description="Style instruction for the TTS engine.")
duration: Optional[float] = Field(
default=None,
gt=0,
description="VoiceStudio extension: target output duration in seconds.",
)
seed: Optional[int] = Field(
default=None,
description="VoiceStudio extension: deterministic sampling seed.",
)
denoise: bool = Field(
default=True,
description="VoiceStudio extension: prepend denoise control when supported.",
)
preprocess_prompt: bool = Field(
default=True,
description="VoiceStudio extension: trim/preprocess reference prompt when supported.",
)
chunk_duration: Optional[float] = Field(
default=None,
ge=0,
description="OmniVoice GGUF extension: long-form internal chunk duration.",
)
chunk_threshold: Optional[float] = Field(
default=None,
ge=0,
description="OmniVoice GGUF extension: long-form internal chunk threshold.",
)
# #1014: these two were silently DISCARDED before (pydantic ignores
# undeclared fields) — a 200 OK that quietly dropped the caller's quality
# knobs. Declared now and passed through, matching the native /generate
# form fields (defaults there: num_step=16, guidance_scale=2.0; the
# model's documented "quality" preset is num_step=32).
num_step: Optional[int] = Field(
default=None,
ge=1,
le=128,
description="VoiceStudio extension: iterative unmasking steps (app default 16; 32 = the model's documented quality preset).",
)
guidance_scale: Optional[float] = Field(
default=None,
gt=0,
le=20,
description="VoiceStudio extension: classifier-free guidance scale (app default 2.0).",
)
@field_validator("voice", mode="before")
@classmethod
def _voice_id(cls, v: Any) -> Any:
# OpenAI accepts a custom voice as {"id": "voice_..."}; VoiceStudio's
# equivalent is a voice-profile id, so unwrap it.
if isinstance(v, dict):
vid = v.get("id")
if not isinstance(vid, str) or not vid:
raise ValueError("voice object must be {\"id\": \"<voice id>\"}")
return vid
return v
class TranscriptionResponse(BaseModel):
"""Mirrors OpenAI's CreateTranscriptionResponse."""
text: str
class VerboseTranscriptionResponse(BaseModel):
"""Mirrors OpenAI's verbose_json transcription response."""
task: str = "transcribe"
language: str = ""
duration: float = 0.0
text: str = ""
segments: list[dict] = Field(default_factory=list)
words: Optional[list[dict]] = None
# ── TTS: POST /v1/audio/speech ──────────────────────────────────────────────
def _known_engine_ids() -> str:
try:
from services.tts_backend import list_backends
return ", ".join(b["id"] for b in list_backends())
except Exception:
return "omnivoice, voxcpm2, cosyvoice, kittentts, indextts2"
def _resolve_engine(model_id: str):
"""Map an OpenAI model name to a VoiceStudio backend."""
from services.tts_backend import (
get_backend_class, get_active_tts_backend, get_engine_instance_for,
)
# Direct engine ID match first, so a real engine id always means that
# engine; then OpenAI model ids as pass-through to the active engine.
try:
cls = get_backend_class(model_id)
except ValueError:
if is_openai_tts_model(model_id):
return get_active_tts_backend()
raise OpenAIError(
400,
f"Unknown model '{model_id}'. Use an OpenAI TTS model id "
f"({', '.join(OPENAI_TTS_MODELS)}) for the active engine, or a "
f"VoiceStudio engine id: {_known_engine_ids()}. "
"GET /v1/models lists what this server offers.",
param="model", code="model_not_found",
)
ok, msg = cls.is_available()
if not ok:
raise OpenAIError(
400, f"Engine '{model_id}' is not available: {msg}",
param="model", code="model_not_available",
)
from services.tts_backend import OmniVoiceBackend
if cls is OmniVoiceBackend:
# OmniVoice only ever runs as the shared active engine — the
# explicit-omnivoice request is the active-engine request.
return get_active_tts_backend()
# Cached singleton, not a fresh cls(): SubprocessBackend engines would
# spawn a sidecar process and reload their model on EVERY request, and
# register a new atexit hook each time (get_engine_instance's contract).
# No router-local cache on top of it: the shared cache is keyed by
# CLASS precisely so id rebinds/evictions can't serve a stale instance,
# and cross-engine memory discipline is create_speech's
# evict_other_tts_engines call (the same seam /generate uses) — not a
# bespoke unload here.
return get_engine_instance_for(model_id)
#: OpenAI's `pcm` format: raw 24 kHz, 16-bit signed little-endian, mono.
PCM_SAMPLE_RATE = 24000
#: (mime type, file extension) per response_format. The body always matches.
_FORMAT_MEDIA = {
"mp3": ("audio/mpeg", "mp3"),
"opus": ("audio/ogg", "opus"),
"aac": ("audio/aac", "aac"),
"flac": ("audio/flac", "flac"),
"wav": ("audio/wav", "wav"),
"pcm": ("audio/pcm", "pcm"),
}
#: Formats encoded by ffmpeg: codec args, container, sample rates the codec
#: accepts (anything else is resampled to OpenAI's 24 kHz).
_FFMPEG_FORMATS = {
"mp3": (["-c:a", "libmp3lame", "-b:a", "128k"], "mp3",
{8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000}),
"opus": (OPUS_CODEC_ARGS, "ogg", {OPUS_SAMPLE_RATE}),
"aac": (["-c:a", "aac", "-b:a", "128k"], "adts",
{8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000, 64000, 88200, 96000}),
}
def _cpu_float(wav_tensor):
import torch
t = wav_tensor
if t.device.type != "cpu":
t = t.cpu()
if t.dtype != torch.float32:
t = t.to(torch.float32)
return t
def _pcm24k(wav_tensor, sample_rate: int) -> bytes:
"""Raw OpenAI PCM: mono, 24 kHz, int16 LE — resampled from the engine rate
(VoxCPM2 is 48 kHz, KittenTTS 24 kHz, others vary) so clients that assume
OpenAI's documented rate don't play it at the wrong speed."""
import torch
t = _cpu_float(wav_tensor)
if t.ndim == 2:
t = t.mean(dim=0)
elif t.ndim != 1:
t = t.reshape(-1)
if sample_rate != PCM_SAMPLE_RATE:
import torchaudio.functional as AF
t = AF.resample(t, sample_rate, PCM_SAMPLE_RATE)
t = t.clamp(-1.0, 1.0).contiguous()
pcm = (t * 32767).round().clamp(-32768, 32767).to(torch.int16)
# int16 tobytes() is host order; every supported host is little-endian,
# but make it explicit so a big-endian build can't flip the samples.
return pcm.numpy().astype("<i2", copy=False).tobytes()
def _ffmpeg_or_error(fmt: str) -> str:
"""Resolve ffmpeg for a compressed format, or raise an OpenAI-shaped 400
BEFORE any GPU time is spent (never a WAV body labelled as mp3)."""
from services.ffmpeg_utils import find_ffmpeg
exe = find_ffmpeg()
if not exe:
raise OpenAIError(
400,
f"response_format '{fmt}' needs ffmpeg, which VoiceStudio could not find. "
"Request 'wav', 'flac' or 'pcm', or install ffmpeg (Settings → Audio tools) "
"or set FFMPEG_PATH.",
param="response_format", code="unsupported_response_format",
)
return exe
async def _encode_ffmpeg(ffmpeg: str, wav_tensor, sample_rate: int, fmt: str) -> bytes:
from services.audio_io import _safe_torchaudio_save
from services.ffmpeg_utils import run_ffmpeg
codec_args, container, rates = _FFMPEG_FORMATS[fmt]
out_rate = sample_rate if sample_rate in rates else (OPUS_SAMPLE_RATE if fmt == "opus" else PCM_SAMPLE_RATE)
fd, src = tempfile.mkstemp(suffix=".wav")
os.close(fd)
try:
await asyncio.to_thread(_safe_torchaudio_save, src, _cpu_float(wav_tensor), sample_rate, format="wav")
cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-i", src,
"-ar", str(out_rate), *codec_args, "-f", container, "pipe:1"]
rc, out, err = await run_ffmpeg(cmd, timeout=300.0)
finally:
try:
os.unlink(src)
except OSError:
# Best-effort temp cleanup: a leftover temp WAV must not turn an
# encoded response (or the real encode error) into a failure.
pass
if rc != 0 or not out:
from core.failure import strip_ffmpeg_banner
tail = strip_ffmpeg_banner((err or b"").decode("utf-8", "replace")).strip()[-300:]
raise OpenAIError(
500, f"Encoding the audio as '{fmt}' failed ({tail or f'ffmpeg exit {rc}'}). "
"Request 'wav', 'flac' or 'pcm' instead.",
param="response_format", code="encoding_failed",
)
return out
async def _encode_audio(wav_tensor, sample_rate: int, fmt: str,
ffmpeg: Optional[str] = None) -> tuple[bytes, str, str]:
"""Encode a torch tensor to the requested audio format.
Returns ``(bytes, mime_type, file_ext)``; the bytes are always the format
the mime type names — a missing encoder is an error, never a silent WAV.
"""
from services.audio_io import _safe_torchaudio_save
mime, ext = _FORMAT_MEDIA[fmt]
if fmt == "pcm":
return await asyncio.to_thread(_pcm24k, wav_tensor, sample_rate), mime, ext
if fmt in ("wav", "flac"):
buf = io.BytesIO()
await asyncio.to_thread(_safe_torchaudio_save, buf, wav_tensor, sample_rate, format=fmt)
return buf.getvalue(), mime, ext
ffmpeg = ffmpeg or await asyncio.to_thread(_ffmpeg_or_error, fmt)
return await _encode_ffmpeg(ffmpeg, wav_tensor, sample_rate, fmt), mime, ext
def _typed_speech_http_error(e: Exception) -> Optional[HTTPException]:
"""Map typed synthesis failures to actionable HTTP errors (#1172/#1173).
- TTSInputError (bad caller input, e.g. nothing speakable) → 400,
matching /generate's ValueError→400 mapping.
- InvalidBinaryError (managed engine binary is a placeholder / corrupt /
refused by the OS) → 503 with the repair hint, instead of the bare
"[Errno 8] Exec format error" 500.
- TimeoutError (#1190/#1202: pool saturation or a job that overran its
execution budget) → 503 + Retry-After + X-OmniVoice-Retryable, instead of
the 500 a scripted client can't distinguish from a real crash. Matched on
the BUILTIN base, not GpuJobTimeoutError by name, so a mid-suite module
reload can't break the isinstance check (same rationale as the load-path
catch below).
Returns None for anything else (caller falls through to the generic 500).
"""
from services.binary_preflight import InvalidBinaryError
from services.tts_backend import TTSInputError
if isinstance(e, TTSInputError):
return OpenAIError(400, str(e), param="input")
if isinstance(e, InvalidBinaryError):
return HTTPException(status_code=503, detail=str(e))
if isinstance(e, TimeoutError):
return HTTPException(
status_code=503, detail=str(e),
headers={"Retry-After": str(getattr(e, "retry_after", 30)),
"X-OmniVoice-Retryable": "true"},
)
return None
def _run_tts(backend, text: str, kw: dict):
"""Run TTS inference in the GPU thread pool."""
import torch
from services.audio_dsp import apply_mastering, normalize_audio, trim_speech_padding
from services.watermark import mark_synthetic
wav = backend.generate(text, **kw)
sr = backend.sample_rate
# Strip the engine's lead-in/tail silence, as /generate does — unless the
# caller asked for an exact `duration`, which a trim would shorten.
if not kw.get("duration") and torch.is_tensor(wav):
wav = trim_speech_padding(wav, sr)
# Engines that already emit mastered, studio-grade audio (e.g. VoxCPM2's
# native 48 kHz) opt out of apply_mastering via `applies_own_mastering`.
# That chain's highpass + Compressor is tuned for VoiceStudio's 24 kHz clone
# output; applied to a studio engine it adds an audible level pump that
# degrades the very output we want clean. Loudness normalisation still
# runs — it's a benign peak scale, not dynamics.
if not getattr(backend, "applies_own_mastering", False):
wav = apply_mastering(wav, sample_rate=sr)
wav = normalize_audio(wav, target_dBFS=-2.0)
# Invisible AudioSeal provenance mark at the tensor stage, before any
# container encoding (#1169 — this route used to return unmarked audio
# while /generate marked the same text). Same failure semantics as
# /generate: pref-gated, no-op without AudioSeal, passes audio through
# unchanged on any failure — never blocks the response.
wav = mark_synthetic(wav, sr, context="openai_compat.speech")
return wav, sr
def _engine_instructions(backend, instructions: Optional[str]) -> Optional[str]:
"""OpenAI ``instructions`` for this engine, or None.
OpenAI treats them as free-form, best-effort style prose (tts-1 ignores
them), and the Agents SDK sends a prose default on every request. The
OmniVoice family's ``instruct`` is a closed vocabulary of voice-design
tags that rejects prose, so it gets only the tags it knows ("female,
whisper" survives; "speak cheerfully" is dropped) instead of failing the
request. Engines with free-text instructions get the text unchanged.
"""
if not instructions:
return None
if getattr(backend, "instruct_vocabulary", "freeform") == "tags":
from omnivoice.utils.voice_design import sanitize_instruct
return sanitize_instruct(instructions) or None
return instructions
_STREAM_CHUNK = 32 * 1024
def _sse_events(audio: bytes):
"""OpenAI's speech SSE stream: base64 `speech.audio.delta` events, then a
`speech.audio.done`. VoiceStudio synthesises the whole clip first, so the
events carry the finished audio in chunks (no token usage to report)."""
for i in range(0, len(audio), _STREAM_CHUNK):
delta = base64.b64encode(audio[i:i + _STREAM_CHUNK]).decode("ascii")
yield f"data: {json.dumps({'type': 'speech.audio.delta', 'audio': delta})}\n\n"
done = {"type": "speech.audio.done",
"usage": {"input_tokens": 0, "output_tokens": 0, "total_tokens": 0}}
yield f"data: {json.dumps(done)}\n\n"
def _audio_chunks(audio: bytes):
for i in range(0, len(audio), _STREAM_CHUNK):
yield audio[i:i + _STREAM_CHUNK]
@router.post("/audio/speech")
async def create_speech(req: SpeechRequest):
"""Generate audio from text. Compatible with OpenAI's POST /v1/audio/speech."""
from services.model_acceptance import ModelLicenceNotAccepted
try:
backend = _resolve_engine(req.model)
except ModelLicenceNotAccepted as exc:
# OpenAI's error shape; `detail` keeps the models for VoiceStudio clients.
raise OpenAIError(403, exc.detail(), param="model", code=exc.detail()["code"]) from exc
# Compressed formats need ffmpeg: fail fast, before any model load or GPU
# work, and never fall back to a body that doesn't match the format.
ffmpeg = None
if req.response_format in _FFMPEG_FORMATS:
ffmpeg = await asyncio.to_thread(_ffmpeg_or_error, req.response_format)
# Routing gate (#21 — no silent CPU fallback), identical to REST /generate.
from core.device_caps import detect_host_caps
from services.engine_routing import routing_notice, runtime_compute_profile_async
_routing = await runtime_compute_profile_async(
backend, detect_host_caps()
)
if _routing["routing_status"] == "unavailable":
raise OpenAIError(400, _routing["routing_reason"], param="model", code="model_not_available")
_routing_notice = routing_notice(_routing) # (status, reason) or None
# Build kwargs for the backend's generate() method
kw: dict = {
"speed": req.speed,
"denoise": req.denoise,
"preprocess_prompt": req.preprocess_prompt,
}
if req.duration is not None:
kw["duration"] = req.duration
if req.seed is not None:
kw["seed"] = req.seed
if req.chunk_duration is not None:
kw["chunk_duration"] = req.chunk_duration
if req.chunk_threshold is not None:
kw["chunk_threshold"] = req.chunk_threshold
if req.num_step is not None:
kw["num_step"] = req.num_step
if req.guidance_scale is not None:
kw["guidance_scale"] = req.guidance_scale
if req.language:
kw["language"] = req.language
# OpenAI's `instructions` maps onto VoiceStudio's `instruct` (it used to be
# dropped silently); an explicit `instruct` wins.
instruct = req.instruct or _engine_instructions(backend, req.instructions)
if instruct:
kw["instruct"] = instruct
if req.description:
kw["description"] = req.description
# Voice handling: an OpenAI alias or "default", in any case or spacing,
# uses the engine default; a voice-profile id, then a profile name
# (#2617), resolves the reference clip; anything else is forwarded as an
# engine preset (e.g. KittenTTS).
voice = req.voice
if not _name_is_reserved(voice):
row = _resolve_voice_profile(voice)
if row:
from core.config import VOICES_DIR
if row["is_locked"] and row["locked_audio_path"]:
kw["ref_audio"] = contained_join(VOICES_DIR, row["locked_audio_path"])
elif row["ref_audio_path"]:
kw["ref_audio"] = contained_join(VOICES_DIR, row["ref_audio_path"])
if row["ref_text"]:
kw["ref_text"] = row["ref_text"]
if row["instruct"] and not instruct:
kw["instruct"] = row["instruct"]
if req.seed is None and row["seed"] is not None:
kw["seed"] = row["seed"]
else:
# Not a profile — forward as an engine preset name.
kw["voice"] = voice
# Engine-agnostic text normalization (junk strip, numbers→words,
# abbreviations) at this route's text→engine choke point — the same
# pre-pass as /generate, applied exactly once per request. `req.language`
# is everything this route knows about the language (None → universal
# safety filters only). Pref-gated (default ON), idempotent, never raises.
from services.text_normalization import normalize_for_tts
text = normalize_for_tts(req.input, req.language)
# VRAM eviction runs in get_model()'s warm-return path now, covering every
# native TTS generate (this route, WS TTS, dub, batch, audiobook).
# Single-active-engine memory discipline (MM2-01), the same call /generate
# makes before its load: hand back every OTHER resident TTS engine's model
# before this one warms up, so switching `model` ids across requests —
# explicit id → explicit id, or explicit id → the tts-1/omnivoice aliases —
# can't stack multi-GB engines/sidecars. No-op when nothing else is
# resident; opt out with OMNIVOICE_SINGLE_ENGINE_RESIDENT=0.
from services.engine_memory import evict_other_tts_engines
await evict_other_tts_engines(backend.id)
# ── #1033/#1037/#1014: warm the engine under the LOAD budget before the
# generate clock starts. The T4 verification (#1014) measured a fresh
# install's first /v1/audio/speech burning its whole 300s generate budget
# on the multi-GB checkpoint download (0% GPU util throughout) and dying
# with a misleading "too heavy for the available compute" error. Model
# loading gets OMNIVOICE_MODEL_LOAD_TIMEOUT (default 1200s); once warm
# this is a per-request no-op.
from services.model_manager import _model_load_timeout
try:
await run_on_gpu_pool_guarded(
backend.ensure_ready,
what=f"TTS engine '{backend.id}' model load",
timeout=_model_load_timeout(),
)
# Catch the BUILTIN TimeoutError base, not GpuJobTimeoutError by name:
# several tests reload services.model_manager mid-suite, so a class
# imported at call time can differ in identity from the one the guard
# (bound at this module's import) actually raises — the except would
# silently miss. The builtin base has one identity forever. (Caught by
# this exact test failing CI-only, in full-suite order.)
except TimeoutError as e:
logger.warning("engine load exceeded the model-load budget: %s", e)
raise HTTPException(
status_code=503,
detail=(
f"TTS engine '{backend.id}' did not finish loading within its "
f"model-load budget — on a first run this usually means the weight "
f"download is slow or stalled (check the engine's Weights list in Model Catalogue for "
f"progress), not that generation failed. Retry once the model "
f"shows as installed."
),
headers={"Retry-After": "30", "X-OmniVoice-Retryable": "true"},
) from e
except Exception as e:
if type(e).__name__ == "ModelLoadInterruptedByShutdown":
raise
# A sidecar engine's load can also hit the #1172 class (broken venv
# interpreter / placeholder binary) — surface the typed 503 here too.
http = _typed_speech_http_error(e)
if http is None:
# #2298: an untyped load failure — the weight download refused,
# DNS gone, the mirror down — used to re-raise into the generic
# 500. Same actionable sentence as /generate's twin catch; this
# route keeps a string detail because its errors are read by
# OpenAI-shaped clients.
from core.public_errors import model_load_failure
logger.error("OpenAI TTS model load failed")
raise HTTPException(
status_code=503,
detail=str(model_load_failure(backend.id, e)["detail"]),
headers={"Retry-After": "30", "X-OmniVoice-Retryable": "true"},
) from e
logger.warning("OpenAI TTS engine load failed: %s", e)
raise http from e
# Admission control at SUBMIT (#1190/#1202). This is the scripted-client
# surface: a script fanning out N requests at a 1-worker pool used to get N
# silent multi-minute waits and then "too heavy for the available compute".
# Refusing up front with 429 + Retry-After lets a client back off correctly,
# and costs an interactive user nothing (the policy only trips when a full
# wave of jobs is ALREADY queued — see check_gpu_admission).
from services.model_manager import check_gpu_admission
try:
check_gpu_admission(what="OpenAI TTS generate")
except TimeoutError as e:
logger.warning("OpenAI TTS refused — GPU pool saturated: %s", e)
raise HTTPException(
status_code=429, detail=str(e),
headers={"Retry-After": str(getattr(e, "retry_after", 30)),
"X-OmniVoice-Retryable": "true"},
) from e
try:
# Bounded + pool-reset on hang so a wedged TTS request can't starve the
# GPU pool and brick the backend (#730 class). The budget is the shared
# length-scaled one (#1190) — this route used to hardcode the flat 300s,
# so long inputs failed here even after v0.3.22 shipped the scaling.
from services.model_manager import generate_timeout_s
wav, sr = await run_on_gpu_pool_guarded(
lambda: _run_tts(backend, text, kw), what="OpenAI TTS generate",
timeout=generate_timeout_s(text, engine=backend))
except Exception as e:
# #1172/#1173: typed failures get their real status + actionable
# message (400 bad input / 503 broken engine binary) instead of a
# generic 500 wrapping an errno or an ONNX abort.
http = _typed_speech_http_error(e)
if http is not None:
logger.warning("OpenAI TTS failed (typed): %s", e)
raise http from e
logger.exception("OpenAI TTS failed: %s", e)
raise HTTPException(status_code=500, detail=str(e))
audio_bytes, mime_type, ext = await _encode_audio(wav, sr, req.response_format, ffmpeg)
_headers = {
"Content-Disposition": content_disposition(f"speech.{ext}", disposition="inline"),
}
if _routing_notice:
from services.engine_routing import header_safe_reason
_headers["X-OmniVoice-Routing"] = _routing_notice[0]
_hr = header_safe_reason(_routing_notice[1])
if _hr:
_headers["X-OmniVoice-Routing-Reason"] = _hr
if req.stream_format == "sse":
_headers.pop("Content-Disposition")
return StreamingResponse(_sse_events(audio_bytes), media_type="text/event-stream",
headers=_headers)
if req.stream_format == "audio":
# Chunked transfer (no Content-Length), like OpenAI's streamed audio.
return StreamingResponse(_audio_chunks(audio_bytes), media_type=mime_type, headers=_headers)
_headers["Content-Length"] = str(len(audio_bytes))
return StreamingResponse(
io.BytesIO(audio_bytes),
media_type=mime_type,
headers=_headers,
)
# ── STT: POST /v1/audio/transcriptions and /v1/audio/translations ──────────
_TRANSCRIPT_FORMATS = ("json", "text", "srt", "verbose_json", "vtt")
class _TaskUnsupported(Exception):
"""The active ASR engine cannot perform the requested task (translate)."""
class _ModelNotActive(Exception):
"""``model`` names a VoiceStudio ASR engine that is not the one serving."""
def __init__(self, requested: str, active: str):
super().__init__(requested)
self.requested = requested
self.active = active
def _is_asr_engine_id(model: Optional[str]) -> bool:
if not model:
return False
from services.asr_backend import _REGISTRY
try:
return model in _REGISTRY
except Exception:
return False
def _backend_request_kwargs(backend, options: dict) -> dict:
"""The subset of OpenAI-derived decode options this backend's
``transcribe()`` declares (shared with dictation's vocabulary prompt)."""
from services.asr_backend import transcribe_request_kwargs
return transcribe_request_kwargs(backend, options)
def _reported_language(result: dict, requested: Optional[str], task: str) -> str:
if task == "translate":
return "en" # OpenAI reports the output language for translations
lang = result.get("language")
if isinstance(lang, str) and lang and lang.lower() not in ("auto", "unknown", "none"):
return lang
return requested or "unknown"
def _num(value, default: float = 0.0) -> float:
try:
return float(value) if value is not None else default
except (TypeError, ValueError):
return default
def _result_segments(result: dict) -> list[dict]:
segments = result.get("segments") or []
if segments:
return segments
# Engines that only return `chunks` (transformers pipeline shape).
out = []
for c in result.get("chunks") or []:
ts = c.get("timestamp") or (None, None)
out.append({"text": c.get("text", ""), "start": ts[0], "end": ts[1]})
return out
def _openai_segments(segments: list[dict], temperature: Optional[float]) -> list[dict]:
"""OpenAI TranscriptionSegment shape; fields an engine doesn't report
get neutral values rather than being omitted."""
return [
{
"id": i,
"seek": int(seg.get("seek", 0) or 0),
"start": _num(seg.get("start")),
"end": _num(seg.get("end"), _num(seg.get("start"))),
"text": seg.get("text", ""),
"tokens": list(seg.get("tokens") or []),
"temperature": _num(seg.get("temperature"), temperature or 0.0),
"avg_logprob": _num(seg.get("avg_logprob")),
"compression_ratio": _num(seg.get("compression_ratio")),
"no_speech_prob": _num(seg.get("no_speech_prob")),
}
for i, seg in enumerate(segments)
]
def _openai_words(segments: list[dict]) -> list[dict]:
words = []
for seg in segments:
for w in seg.get("words") or []:
token = w.get("word", w.get("text"))
# Aligners leave numerals/symbols untimed; OpenAI words are timed.
if token is None or w.get("start") is None or w.get("end") is None:
continue
words.append({"word": str(token).strip(), "start": _num(w["start"]), "end": _num(w["end"])})
return words
async def _transcribe_request(
*, task: str, file: UploadFile, model: Optional[str] = None,
language: Optional[str], prompt: Optional[str],
response_format: str, temperature: Optional[float],
timestamp_granularities: Optional[list[str]] = None, stream: Optional[bool] = None,
):
from services.asr_backend import (
ASRModelMissingError,
asr_model_missing_detail,
asr_model_missing_error,
load_active_asr_backend,
)
from services.model_acceptance import ModelLicenceNotAccepted
if response_format not in _TRANSCRIPT_FORMATS:
raise OpenAIError(
400, f"Unsupported response_format '{response_format}'. Use one of: "
f"{', '.join(_TRANSCRIPT_FORMATS)}.",
param="response_format", code="invalid_value",
)
if stream:
raise OpenAIError(
400, "stream=true is not supported here. Use WS /v1/audio/transcriptions/stream "
"for live partial transcripts.", param="stream", code="unsupported_parameter",
)
if temperature is not None and not 0 <= temperature <= 1:
raise OpenAIError(400, "temperature must be between 0 and 1.", param="temperature",
code="invalid_value")
granularities = set(timestamp_granularities or [])
bad = granularities - {"word", "segment"}
if bad:
raise OpenAIError(
400, f"Unsupported timestamp_granularities {sorted(bad)}; use 'word' and/or 'segment'.",
param="timestamp_granularities", code="invalid_value",
)
want_words = response_format == "verbose_json" and "word" in granularities
# TTS-only install: no ASR model on disk → actionable 409, BEFORE any
# backend load could silently auto-download multi-GB whisper weights.
# Same typed detail shape as /transcribe (capture.py): the machine fields
# (`error`, `missing_repo_id`, `recommended`) let VoiceStudio-aware clients
# render the one-click download CTA, while `message` keeps a human-readable
# line for generic OpenAI-compat clients.
missing = await asyncio.to_thread(asr_model_missing_error)
if missing is not None:
raise HTTPException(
status_code=409,
detail={**missing, "message": asr_model_missing_detail(missing)},
)
# Write uploaded file to a temp location
# Content is probed by ffmpeg, so an unusable extension just gets ".wav".
suffix = upload_suffix(file.filename, ".wav") or ".wav"
try:
with tempfile.NamedTemporaryFile(delete=False, suffix=suffix) as tmp:
content = await file.read()
tmp.write(content)
tmp_path = tmp.name
except Exception as e:
raise OpenAIError(400, f"Could not read audio file: {e}", param="file")
options = {
"language": language or None,
"initial_prompt": prompt or None,
"temperature": temperature,
"task": "translate" if task == "translate" else None,
}
try:
# Run transcription in the thread pool to avoid blocking the event loop,
# bounded so a stuck/starved ASR returns a 504 with guidance instead of
# hanging the request forever (see run_transcribe_guarded).
from services.asr_backend import run_transcribe_guarded
# Word timestamps cost an alignment pass: only when they're returned.
word_ts = want_words
# `load_active_asr_backend`, not `get_active_asr_backend`: the latter is
# a pure selector, so a backend whose shallow `is_available()` probe
# passes but whose deep import chain is broken (whisperx →
# ctranslate2 failing to dlopen on a hardened kernel) reached
# `.transcribe()` and 500'd, even with a healthy engine next in line.
# The loader does select + ensure_loaded + degrade (#1185). It loads
# weights, so it belongs inside the pool with the transcribe call —
# never on the event loop.
# OpenAI model ids (and any other name) mean "the active engine". A
# VoiceStudio ASR engine id is a concrete choice: serve it only when
# it is the engine actually loaded, never silently substitute another.
explicit_engine = model if _is_asr_engine_id(model) else None
def _run():
backend = load_active_asr_backend()
if explicit_engine and getattr(backend, "id", None) != explicit_engine:
raise _ModelNotActive(explicit_engine, getattr(backend, "id", "?"))
extra = _backend_request_kwargs(backend, options)
if task == "translate" and not (
"task" in extra and getattr(backend, "supports_translation", lambda: False)()
):
# Includes Whisper turbo / English-only checkpoints, which
# would return the source language labelled as English.
raise _TaskUnsupported(backend.id)
return backend.transcribe(tmp_path, word_timestamps=word_ts, **extra)
result = await run_transcribe_guarded(_gpu_pool, _run, what="OpenAI")
segments = _result_segments(result)
full_text = (result.get("text") or "").strip() if not segments else " ".join(
(seg.get("text") or "").strip() for seg in segments
).strip()
detected_lang = _reported_language(result, language, task)
# Format response based on requested format
if response_format == "text":
from fastapi.responses import PlainTextResponse
return PlainTextResponse(full_text)
if response_format == "verbose_json":
duration = _num(result.get("duration"))
if not duration and segments:
duration = _num(segments[-1].get("end"))
return VerboseTranscriptionResponse(
task=task,
language=detected_lang,
duration=duration,
text=full_text,
segments=_openai_segments(segments, temperature),
words=_openai_words(segments) if want_words else None,
).model_dump(exclude_none=True)
if response_format == "srt":
from fastapi.responses import PlainTextResponse
srt_lines = []
for i, seg in enumerate(segments, 1):
start = _num(seg.get("start"))
end = _num(seg.get("end"), start)
text = (seg.get("text") or "").strip()
srt_lines.append(
f"{i}\n"
f"{_format_ts_srt(start)} --> {_format_ts_srt(end)}\n"
f"{text}\n"
)
return PlainTextResponse("\n".join(srt_lines), media_type="text/plain")
if response_format == "vtt":
from fastapi.responses import PlainTextResponse
from services.srt_parser import escape_webvtt_text
vtt_lines = ["WEBVTT\n"]
for seg in segments:
start = _num(seg.get("start"))
end = _num(seg.get("end"), start)
text = escape_webvtt_text((seg.get("text") or "").strip(), preserve_markup=False)
vtt_lines.append(
f"{_format_ts_vtt(start)} --> {_format_ts_vtt(end)}\n{text}\n"
)
return PlainTextResponse("\n".join(vtt_lines), media_type="text/vtt")
# Default: json
return TranscriptionResponse(text=full_text)
except HTTPException:
raise
except _ModelNotActive as e:
raise OpenAIError(
400,
f"Speech-recognition engine '{e.requested}' is not the active engine "
f"('{e.active}' is). Select it in Model Catalogue, or send an OpenAI model "
"id such as 'whisper-1' to use the active engine.",
param="model", code="model_not_active",
)
except _TaskUnsupported as e:
raise OpenAIError(
400,
f"The active speech-recognition engine '{e}' cannot translate with its "
"current model. Translation needs a multilingual Whisper checkpoint "
"(large-v3, medium, …) on faster-whisper, whisperx, mlx-whisper or "
"pytorch-whisper; turbo, distil and English-only (.en) models are "
"transcription-only. Change it in Model Catalogue, or use "
"/v1/audio/transcriptions.",
param="model", code="unsupported_task",
)
except ASRModelMissingError as e:
# A degraded-to candidate has no weights on disk. Same typed 409 the
# preflight above raises — never a 500, and never a silent multi-GB
# auto-download.
raise HTTPException(
status_code=409,
detail={**e.payload, "message": asr_model_missing_detail(e.payload)},
)
except ModelLicenceNotAccepted as e:
# The active engine's model licence needs acceptance in the app (#2689).
raise OpenAIError(403, e.detail(), param="model", code=e.detail()["code"]) from e
except TimeoutError as e:
# ASRTimeoutError (subclass): backend alive, ASR too heavy for compute.
logger.warning("OpenAI transcription timed out: %s", e)
raise HTTPException(status_code=504, detail=str(e))
except Exception as e:
from core.failure import NO_AUDIO_TRACK_MESSAGE, NoAudioTrackError
from services.ffmpeg_utils import raise_for_audio_extract_failure
try:
await asyncio.to_thread(raise_for_audio_extract_failure, str(e), tmp_path)
except NoAudioTrackError:
raise OpenAIError(400, NO_AUDIO_TRACK_MESSAGE, param="file", code="no_audio_track")
logger.exception("OpenAI transcription failed: %s", e)
raise HTTPException(status_code=500, detail=str(e))
finally:
# Clean up temp file
try:
os.unlink(tmp_path)
except OSError:
pass
_MODEL_DESC = (
"ASR model. OpenAI ids ('whisper-1', 'gpt-4o-transcribe', "
"'gpt-4o-mini-transcribe') are served by the active engine; a VoiceStudio "
"ASR engine id must name the active engine (400 otherwise)."
)
#: The SDK sends list fields as `name[]` in multipart forms; accept both.
_Granularities = Annotated[
Optional[list[str]],
Form(alias="timestamp_granularities[]", description="'word' and/or 'segment' (verbose_json)."),
]
_GranularitiesPlain = Annotated[Optional[list[str]], Form(alias="timestamp_granularities")]
_Stream = Annotated[Optional[bool], Form(description="Streaming is not supported (400).")]
@router.post("/audio/transcriptions")
async def create_transcription(
file: UploadFile = File(..., description="Audio file to transcribe"),
model: str = Form(default="whisper-1", description=_MODEL_DESC),
language: Optional[str] = Form(
default=None,
description="Language of the input audio (ISO 639-1). Optional.",
),
prompt: Optional[str] = Form(
default=None,
description="Optional text to guide the model's style or continue a previous segment.",
),
response_format: str = Form(
default="json",
description="Output format: json, text, verbose_json, srt, vtt.",
),
temperature: Optional[float] = Form(
default=None,
description="Sampling temperature (0–1). Used by engines that support it.",
),
timestamp_granularities: _Granularities = None,
timestamp_granularities_plain: _GranularitiesPlain = None,
stream: _Stream = None,
):
"""Transcribe audio to text. Compatible with OpenAI's POST /v1/audio/transcriptions."""
return await _transcribe_request(
task="transcribe", file=file, model=model, language=language, prompt=prompt,
response_format=response_format, temperature=temperature,
timestamp_granularities=(timestamp_granularities or []) + (timestamp_granularities_plain or []),
stream=stream,
)
@router.post("/audio/translations")
async def create_translation(
file: UploadFile = File(..., description="Audio file to translate into English"),
model: str = Form(default="whisper-1", description=_MODEL_DESC),
prompt: Optional[str] = Form(default=None, description="Optional text to guide the model's style."),
response_format: str = Form(default="json", description="Output format: json, text, verbose_json, srt, vtt."),
temperature: Optional[float] = Form(default=None, description="Sampling temperature (0–1)."),
):
"""Translate speech into English text. Compatible with OpenAI's
POST /v1/audio/translations; needs a Whisper-family ASR engine."""
return await _transcribe_request(
task="translate", file=file, model=model, language=None, prompt=prompt,
response_format=response_format, temperature=temperature,
)
# ── Models: GET /v1/models ──────────────────────────────────────────────────
def _model_entry(model_id: str, kind: str, alias: bool) -> dict:
return {
"id": model_id,
"object": "model",
"created": 0,
"owned_by": "voicestudio",
# VoiceStudio extension: what the id does here.
"voicestudio": {"kind": kind, "alias_for_active_engine": alias},
}
def _model_list() -> list[dict]:
"""Every id listed here is one the audio routes actually honour: TTS
requests route to any installed engine, while transcription always runs
on the active ASR engine — so only that one is listed for STT."""
data = [_model_entry(m, "tts", True) for m in OPENAI_TTS_MODELS]
data += [_model_entry(m, "stt", True) for m in OPENAI_STT_MODELS]
seen = {m["id"] for m in data}
try:
from services.tts_backend import list_backends
for b in list_backends():
if b.get("available") and b.get("id") not in seen:
seen.add(b["id"])
data.append(_model_entry(b["id"], "tts", False))
except Exception:
logger.warning("Could not list TTS engines for /v1/models", exc_info=True)
try:
from services.asr_backend import active_backend_id
active = active_backend_id()
if active and active not in seen:
data.append(_model_entry(active, "stt", False))
except Exception:
logger.warning("Could not resolve the active ASR engine for /v1/models", exc_info=True)
return data
@router.get("/models")
def list_models():
"""OpenAI-shaped model list: OpenAI aliases plus every installed engine."""
return {"object": "list", "data": _model_list()}
@router.get("/models/{model_id:path}")
def retrieve_model(model_id: str):
"""One model from GET /v1/models (OpenAI's retrieve shape)."""
for m in _model_list():
if m["id"] == model_id:
return m
if is_openai_tts_model(model_id):
return _model_entry(model_id, "tts", True)
raise OpenAIError(404, f"The model '{model_id}' does not exist on this VoiceStudio server.",
param="model", code="model_not_found")
# ── Voices: GET /v1/audio/voices (VoiceStudio extension) ─────────────────────
@router.get("/audio/voices")
def list_voices():
"""List available voices. VoiceStudio extension to the OpenAI API."""
from services.tts_backend import list_backends
backends = list_backends()
voices = []
# Always include the OpenAI standard voice names as aliases
for name in sorted(_OPENAI_VOICE_ALIASES):
voices.append({
"voice_id": name,
"name": name.capitalize(),
"type": "openai_alias",
"description": f"OpenAI '{name}' voice — maps to the active VoiceStudio engine's default voice.",
})
# Include voice profiles from the database. `voice_id` is always
# accepted as `voice`; the name is too when `addressable_by_name` (#2617)
# — unique among profiles and not an OpenAI voice name or "default".
try:
from collections import Counter
from core.db import db_conn
with db_conn() as conn:
rows = conn.execute(
"SELECT id, name, language FROM voice_profiles ORDER BY name"
).fetchall()
name_counts = Counter(_voice_name_key(r["name"]) for r in rows)
for row in rows:
key = _voice_name_key(row["name"])
voices.append({
"voice_id": row["id"],
"name": row["name"],
"type": "profile",
"language": row["language"],
"addressable_by_name": bool(key) and name_counts[key] == 1
and not _name_is_reserved(key),
})
except Exception:
logger.warning("Voice profiles could not be loaded; returning built-in aliases only")
# OpenAI-compatible clients such as Open WebUI read each voice's `id`
# (#2679); `voice_id` stays for existing callers.
for voice in voices:
voice["id"] = voice["voice_id"]
return {"voices": voices, "engines": backends}
# ── Helpers ─────────────────────────────────────────────────────────────────
def _format_ts_srt(seconds: float) -> str:
"""Format seconds as SRT timestamp: HH:MM:SS,mmm"""
from services.srt_parser import format_cue_timestamp
return format_cue_timestamp(seconds, ",")
def _format_ts_vtt(seconds: float) -> str:
"""Format seconds as VTT timestamp: HH:MM:SS.mmm"""
from services.srt_parser import format_cue_timestamp
return format_cue_timestamp(seconds, ".")