docs: fix TTS model header — optional, default s2.1-pro, document fallback - #110
Closed
M2Night wants to merge 1 commit into
Closed
docs: fix TTS model header — optional, default s2.1-pro, document fallback#110M2Night wants to merge 1 commit into
M2Night wants to merge 1 commit into
Conversation
Live tests (trace IDs 5e56d2de…, 9027a9d2…, 9a40d052…, aaa50a97…) show the model header is not required and unrecognized/omitted values fall back to s2.1-pro, not s2.1-pro-free. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughThe OpenAPI contract makes the ChangesTTS model contract
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with 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.
Inline comments:
In `@api-reference/openapi.json`:
- Around line 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.
- Around line 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.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 200897cb-3faf-4def-b736-45a047b949f3
📒 Files selected for processing (1)
api-reference/openapi.json
Comment on lines
+2475
to
+2476
| "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, |
There was a problem hiding this comment.
🗄️ 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.
Comment on lines
+2475
to
+2478
| "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", |
There was a problem hiding this comment.
🗄️ 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)
PYRepository: 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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The
modelheader on the TTS endpoints (/v1/ttsand/v1/tts/stream/with-timestamp) was documented as required with defaults2.1-pro-free. Live testing shows both are wrong:s2.1-pro(paid tier), nots2.1-pro-free. An unrecognized value (e.g. a typo likes2pro) does not error; it silently falls back tos2.1-proas well.This PR updates
api-reference/openapi.jsonaccordingly and adds one sentence documenting the fallback behavior:Test evidence
All four requests returned 200 from
us-san-jose, each with a distincttraceparent(per the observability docs) so the backend can confirm which model actually served them.ratelimit-limit-concurrencywas captured to distinguish free vs paid tier:modelsent5e56d2de69a1a713a62e369c01aa8e92s2pro9027a9d2f50f325d9ccdce983e524f4bs2-pro9a40d052f02ec2cfbf05eb70a1b1b452s2.1-proaaa50a97136c81c78926b47011379de6Note for maintainers
openapi.jsonis refreshed from upstream bynpm run update:openapi, so the same fix (required=False,default="s2.1-pro", fallback sentence in the description) should also land in the backend FastAPI parameter definition — otherwise the next schema sync will revert this.The
/v1/voice-designmodelheader is intentionally untouched.🤖 Generated with Claude Code
Summary by CodeRabbit
modelheader is now optional for text-to-speech requests.s2.1-pro.