Skip to content

docs: fix TTS model header — optional, default s2.1-pro, document fallback #110

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
M2Night wants to merge 1 commit into from
Closed

docs: fix TTS model header — optional, default s2.1-pro, document fallback #110

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions api-reference/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2472,10 +2472,10 @@
{
"in": "header",
"name": "model",
"description": "Specify which TTS model to use. Use `s2.1-pro-free` for the free developer tier.",
"required": true,
"description": "Specify which TTS model to use. Use `s2.1-pro-free` for the free developer tier. If omitted or set to an unrecognized value, the request falls back to `s2.1-pro`.",
"required": false,
Comment on lines +2475 to +2476

@coderabbitai coderabbitai Bot Jul 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Update the feature documentation in the same change.

features/text-to-speech.mdx:268 still states that the model header is required on every /v1/tts request, contradicting this optional-header contract. Update that documentation or defer this OpenAPI change until both public descriptions agree.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@api-reference/openapi.json` around lines 2475 - 2476, Update the model-header
documentation in the text-to-speech feature content to state that it is optional
and defaults to s2.1-pro when omitted or unrecognized, aligning it with the
OpenAPI description; otherwise defer the OpenAPI contract change until both
descriptions agree.

"schema": {
"default": "s2.1-pro-free",
"default": "s2.1-pro",
Comment on lines +2475 to +2478

@coderabbitai coderabbitai Bot Jul 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "Tracked OpenAPI files:"
git ls-files | rg '(^|/)openapi\.json$|api-reference/' || true

echo
echo "Relevant snippets:"
python3 - <<'PY'
from pathlib import Path
p=Path("api-reference/openapi.json")
if not p.exists():
    print(f"{p} missing")
    raise SystemExit
text=p.read_text(encoding="utf-8").splitlines()
for start,end in ((2475,2478),(2653,2656)):
    print(f"\n--- {p}:{start}-{end} ---")
    for i in range(start, end+1):
        print(f"{i}: {text[i-1]}")

print("\nSearch for fallback wording and model enum occurrences:")
import re
matches=[]
for i,line in enumerate(text, start=1):
    if "falls back" in line or "fall back" in line or "s2.1-pro-free" in line or "s2.1-pro" in line:
        matches.append((i,line))
for i,line in matches[:80]:
    print(f"{i}: {line}")
PY

echo
echo "Inspect surrounding schema definitions with Python JSON parsing:"
python3 - <<'PY'
import json
from pathlib import Path
p=Path("api-reference/openapi.json")
data=json.loads(p.read_text())
def find_paths(obj, key=None, path=()):
    if isinstance(obj, dict):
        for k,v in obj.items():
            if k == key:
                print(f"KEY {key} at {path}.{k}")
            yield from find_paths(v, key, f"{path}.{k}")
        for k,v in obj.items():
            yield from find_paths(v, key, f"{path}.{k}")
    elif isinstance(obj, list):
        for idx,v in enumerate(obj):
            yield from find_paths(v, key, path=f"{path}[{idx}]")

# Navigate likely paths around TTS endpoints
try:
    paths=json.loads(p.read_text())[ "paths"]
    for path in paths:
        if "tts" in path.lower():
            print(f"\nPATH {path}")
            for method,params in paths[path].items():
                print(f"  {method.upper()}")
                if "requestBody" in params:
                    print(json.dumps(params["requestBody"], indent=2)[:1200])
                if "parameters" in params:
                    for par in params["parameters"]:
                        if "model" in par.get("name","").lower() or "model" in str(par.get("schema",{})).lower():
                            print("  parameter:", json.dumps(par, indent=2))
except Exception as e:
    print("PATH traversal failed:", e)

print("\nAll enum arrays containing model values:")
def walk(o,path=""):
    if isinstance(o, dict):
        if o.get("enum") is not None:
            v=o["enum"]
            if any("s2" in str(x).lower() or "tts" in path.lower() or "model" in path.lower() for x in v):
                print(f"{path}: {v}")
        for k,v in o.items():
            walk(v, f"{path}.{k}")
    elif isinstance(o, list):
        for i,v in enumerate(o):
            walk(v, f"{path}[{i}]")
walk(data)
PY

Repository: fishaudio/docs

Length of output: 11456

Don’t promise unknown-model fallback while the schemas limit model values.

Both TTS endpoint headers document that unrecognized model values fall back to s2.1-pro, but each model parameter schema has a closed enum (s1, s2-pro, s2.1-pro, s2.1-pro-free). Make the schemas allow any string/default-driven value, or remove the fallback language from both /v1/tts and /v1/tts/stream/with-timestamp.

📍 Affects 1 file
  • api-reference/openapi.json#L2475-L2478 (this comment)
  • api-reference/openapi.json#L2653-L2656
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@api-reference/openapi.json` around lines 2475 - 2478, Align both TTS model
schemas with their documented fallback behavior: update the model parameters at
api-reference/openapi.json lines 2475-2478 and 2653-2656 to accept arbitrary
string values while retaining the s2.1-pro default, or remove the
unrecognized-value fallback wording from both descriptions. Apply the same
choice consistently to /v1/tts and /v1/tts/stream/with-timestamp.

"enum": [
"s1",
"s2-pro",
Expand Down Expand Up @@ -2650,10 +2650,10 @@
{
"in": "header",
"name": "model",
"description": "Specify which TTS model to use. Use `s2.1-pro-free` for the free developer tier.",
"required": true,
"description": "Specify which TTS model to use. Use `s2.1-pro-free` for the free developer tier. If omitted or set to an unrecognized value, the request falls back to `s2.1-pro`.",
"required": false,
"schema": {
"default": "s2.1-pro-free",
"default": "s2.1-pro",
"enum": [
"s1",
"s2-pro",
Expand Down
Loading