feat(api): adapter generate returns seed_used; expose X-Seed-Used header

server/main.py

@@ -151,13 +151,19 @@ def build_app() -> FastAPI:
 
         gen_fn = decorate(adapter.generate)
         try:
-            wav_bytes, _sr = gen_fn(text, ref_path, language, json.loads(params or "{}"))
+            wav_bytes, _sr, seed_used = gen_fn(
+                text, ref_path, language, json.loads(params or "{}")
+            )
         except Exception as exc:
             return JSONResponse(
                 status_code=500,
                 content={"error": {"code": "generation_failed", "message": str(exc)}},
             )
-        return Response(content=wav_bytes, media_type="audio/wav")
+        return Response(
+            content=wav_bytes,
+            media_type="audio/wav",
+            headers={"X-Seed-Used": str(seed_used), "Access-Control-Expose-Headers": "X-Seed-Used"},
+        )
 
     @app.exception_handler(HTTPException)
     async def _http_exc(request, exc: HTTPException):

server/models/base.py

@@ -29,7 +29,7 @@ class ModelAdapter(Protocol):
         reference_wav_path: str | None,
         language: str | None,
         params: dict[str, Any],
-    ) -> tuple[bytes, int]: ...
+    ) -> tuple[bytes, int, int]: ...   # (wav_bytes, sample_rate, seed_used)
 
 
 def is_valid_adapter(cls: type) -> bool:

server/models/chatterbox_en.py

@@ -7,6 +7,7 @@ from typing import Any, ClassVar
 import soundfile as sf
 
 from server.schemas import Lang, ParamSpec
+from server.seed import apply_seed
 
 
 class Adapter:
@@ -52,9 +53,10 @@ class Adapter:
         reference_wav_path: str | None,
         language: str | None,
         params: dict[str, Any],
-    ) -> tuple[bytes, int]:
+    ) -> tuple[bytes, int, int]:
         if self._model is None:
             raise RuntimeError("model not loaded")
+        seed_used = apply_seed(params.get("seed"))
         wav = self._model.generate(
             text,
             audio_prompt_path=reference_wav_path,
@@ -73,4 +75,4 @@ class Adapter:
         sr = getattr(self._model, "sr", 24000)
         buf = io.BytesIO()
         sf.write(buf, arr, sr, format="WAV", subtype="PCM_16")
-        return buf.getvalue(), sr
+        return buf.getvalue(), sr, seed_used

server/models/chatterbox_mtl.py

@@ -7,6 +7,7 @@ from typing import Any, ClassVar
 import soundfile as sf
 
 from server.schemas import Lang, ParamSpec
+from server.seed import apply_seed
 
 
 _MTL_LANGS: list[Lang] = [
@@ -70,11 +71,12 @@ class Adapter:
         reference_wav_path: str | None,
         language: str | None,
         params: dict[str, Any],
-    ) -> tuple[bytes, int]:
+    ) -> tuple[bytes, int, int]:
         if self._model is None:
             raise RuntimeError("model not loaded")
         if not language:
             raise ValueError("language is required for chatterbox-mtl")
+        seed_used = apply_seed(params.get("seed"))
         wav = self._model.generate(
             text,
             language_id=language,
@@ -93,4 +95,4 @@ class Adapter:
         sr = getattr(self._model, "sr", 24000)
         buf = io.BytesIO()
         sf.write(buf, arr, sr, format="WAV", subtype="PCM_16")
-        return buf.getvalue(), sr
+        return buf.getvalue(), sr, seed_used

server/models/chatterbox_turbo.py

@@ -7,6 +7,7 @@ from typing import Any, ClassVar
 import soundfile as sf
 
 from server.schemas import Lang, ParamSpec
+from server.seed import apply_seed
 
 
 class Adapter:
@@ -54,9 +55,10 @@ class Adapter:
         reference_wav_path: str | None,
         language: str | None,
         params: dict[str, Any],
-    ) -> tuple[bytes, int]:
+    ) -> tuple[bytes, int, int]:
         if self._model is None:
             raise RuntimeError("model not loaded")
+        seed_used = apply_seed(params.get("seed"))
         wav = self._model.generate(
             text,
             audio_prompt_path=reference_wav_path,
@@ -74,4 +76,4 @@ class Adapter:
         sr = getattr(self._model, "sr", 24000)
         buf = io.BytesIO()
         sf.write(buf, arr, sr, format="WAV", subtype="PCM_16")
-        return buf.getvalue(), sr
+        return buf.getvalue(), sr, seed_used

tests/conftest.py

@@ -37,7 +37,10 @@ class FakeAdapter:
         self.loaded = False
 
     def generate(self, text, reference_wav_path, language, params):
-        return (b"FAKEWAV", 24000)
+        # FakeAdapter never actually applies a seed; report the input or 0.
+        seed_in = params.get("seed", 0) if isinstance(params, dict) else 0
+        seed_used = 0 if seed_in is None or seed_in < 0 else int(seed_in)
+        return (b"FAKEWAV", 24000, seed_used)
 
 
 class FakeAdapterB(FakeAdapter):

tests/test_main_generate.py

@@ -25,6 +25,7 @@ async def test_generate_returns_wav_bytes(monkeypatch, fake_classes):
     assert r.status_code == 200
     assert r.headers["content-type"].startswith("audio/wav")
     assert r.content == b"FAKEWAV"
+    assert r.headers["x-seed-used"] == "0"
 
 
 async def test_generate_unknown_model_404(monkeypatch, fake_classes):