docs: add timestamped TTS stream reference#79
Conversation
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (4)
📝 WalkthroughWalkthroughThis PR introduces comprehensive documentation for a new TTS streaming endpoint that returns server-sent events containing audio chunks with optional text alignment timing. The change includes OpenAPI schema definitions, detailed endpoint reference documentation with code examples, developer guide integration, and navigation updates. ChangesTTS Streaming with Timestamps Feature Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 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 |
Kilerd
force-pushed
the
codex/tts-with-timestamp-docs
branch
from
fc31983 to
18b3e99
Compare
|
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
🧹 Nitpick comments (1)
api-reference/openapi.json (1)
2625-3579: ⚡ Quick winConsider deduplicating the response examples block.
The 200 response duplicates the same alignment payload in two places: once inside
schema.examples(an array, lines 2629–3083) and again undercontent["text/event-stream"].examplesas a map of named examples (lines 3115–3578). This roughly doubles the size of the response definition. OpenAPI tooling typically consumes the namedexamplesmap for rendering; the in-schemaexamplesarray is rarely necessary alongside it. Removing one of the two would significantly shrink the spec without losing rendered documentation.🤖 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 2625 - 3579, The OpenAPI response duplicates large example payloads: the TTSTimestampStreamEvent's schema.examples array and the content["text/event-stream"].examples map both contain the same alignment/audio examples; remove one to reduce spec size—prefer keeping the named examples under content["text/event-stream"].examples (used by tooling) and delete the schema.examples array (or vice versa) so only a single source of truth remains for TTSTimestampStreamEvent examples.
🤖 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 2586-2598: The parameter declaration for the
/v1/tts/stream/with-timestamp endpoint has `required: true` but also a `default:
"s2-pro"`, which is inconsistent; update the parameter in the OpenAPI fragment
that defines the Model (enum ["s1","s2-pro"]) by removing the `default:
"s2-pro"` or alternatively set `required: false`—prefer removing the default so
the parameter remains required and the enum/title/type remain unchanged.
- Around line 2405-2422: The OpenAPI parameter "model" currently has a semantic
contradiction: it is marked required:true while also providing a default
("s2-pro"); choose one resolution—either remove the default field from the
"model" header parameter so it remains required and clients must supply it, or
set "required": false so the default "s2-pro" is meaningful; update the "model"
parameter entry in the parameters array accordingly (leave its enum/title/type
intact) and ensure only one of required or default is present.
---
Nitpick comments:
In `@api-reference/openapi.json`:
- Around line 2625-3579: The OpenAPI response duplicates large example payloads:
the TTSTimestampStreamEvent's schema.examples array and the
content["text/event-stream"].examples map both contain the same alignment/audio
examples; remove one to reduce spec size—prefer keeping the named examples under
content["text/event-stream"].examples (used by tooling) and delete the
schema.examples array (or vice versa) so only a single source of truth remains
for TTSTimestampStreamEvent examples.
🪄 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
Run ID: 51b4991b-20cc-4007-96ef-4bdb2374101f
📒 Files selected for processing (4)
api-reference/endpoint/openapi-v1/text-to-speech-stream-with-timestamps.mdxapi-reference/openapi.jsondeveloper-guide/core-features/text-to-speech.mdxdocs.json
| "parameters": [ | ||
| { | ||
| "in": "header", | ||
| "name": "model", | ||
| "description": "Specify which TTS model to use. We recommend `s2-pro`.", | ||
| "required": true, | ||
| "schema": { | ||
| "default": "s2-pro", | ||
| "enum": [ | ||
| "s1", | ||
| "s2-pro" | ||
| ], | ||
| "title": "Model", | ||
| "type": "string" | ||
| }, | ||
| "deprecated": false | ||
| } | ||
| ], |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
OpenAPI 3.1 required parameter with default value semantics
💡 Result:
In OpenAPI 3.1, a parameter marked required cannot also rely on default semantics to make the parameter “optional”. The spec’s intent is: required controls validation/contract that the client must supply the value; default documents server behavior when the value is missing (so the default value is only applicable when the parameter is not required). 1) What “required” means for parameters - The OpenAPI Parameter Object defines required as a boolean that determines whether the parameter is mandatory; it defaults to false for non-path parameters. For path parameters, required MUST be true. [1] 2) What “default” means for parameters (and where it must be placed) - For request parameters, the default value is specified using the default keyword inside the parameter’s schema (not at the top level of the Parameter Object). Swagger’s parameter documentation states: “Use the default keyword in the parameter schema to specify the default value for an optional parameter… The default value is the one that the server uses if the client does not supply the parameter value.” [2] - Swagger also calls out a mistake: “Using default with required parameters… does not make sense – if a value is required, the client must always send it, and the default value is never used.” [2] - A concrete example of correct placement (schema default vs. Parameter Object default) is reflected in the OpenAPI-upstream behavior discussed in an issue: putting default at the Parameter Object level doesn’t get mapped; it should be inside schema, e.g. schema: { default: 0 }. [3] 3) Answer to the specific question: “OpenAPI 3.1 required parameter with default value semantics” - If a parameter has required: true, then by definition clients must always provide it, so default value semantics are not applicable for validation/absence—because the value will not be missing. This is consistent with Swagger’s guidance that default + required “does not make sense… default value is never used.” [2] Practical guidance - If you want “client may omit the parameter; server uses default”, set required: false (or omit required) and set schema.default to the desired value. [2] - If you want “client must provide the parameter”, set required: true and do not depend on default for missing values. [2][1] Example (optional query param with default) parameters: - name: page in: query required: false schema: type: integer default: 0 Example (required param) parameters: - name: page in: query required: true schema: type: integer # (no default relied upon for absence)
Citations:
- 1: https://spec.openapis.org/oas/v3.1.0.html
- 2: https://swagger.io/docs%2Fspecification%2Fdescribing-parameters%2F%2F
- 3: https://stackoverflow.com/questions/72433670/openapi-spec-default-value-of-query-param-is-ignored/72434298
🏁 Script executed:
# Check the git history of the openapi.json file to see if model parameter changed recently
cd api-reference && git log --oneline -20 openapi.json 2>/dev/null || echo "No git history available"Repository: fishaudio/docs
Length of output: 109
🏁 Script executed:
# Search for the model parameter definition in the file to understand full context
rg -A 20 -B 5 '"name": "model"' api-reference/openapi.json | head -100Repository: fishaudio/docs
Length of output: 1471
🏁 Script executed:
# Check if there are any other references to the model parameter or TTS endpoint
rg -i "tts|model.*header" api-reference/openapi.json | head -20Repository: fishaudio/docs
Length of output: 2944
🏁 Script executed:
# Check what changed in the recent commit to understand if required field was modified
git show 18b3e99 --statRepository: fishaudio/docs
Length of output: 9593
🏁 Script executed:
# Get more detail on what changed to the model parameter specifically
git show 18b3e99 -- api-reference/openapi.json | grep -A 30 -B 5 '"name": "model"' | head -80Repository: fishaudio/docs
Length of output: 1999
Fix semantic contradiction: required: true with default value is invalid in OpenAPI 3.1.
The model header has both "required": true and "default": "s2-pro", which violates OpenAPI 3.1 specification. Per OpenAPI semantics, defaults are only meaningful for optional parameters; if a parameter is required, clients must always provide it, making the default unreachable and generating invalid SDK code.
Either set "required": false (clients may omit; server uses default) or remove the default field entirely (clients must provide a value).
Suggested fix
{
"in": "header",
"name": "model",
"description": "Specify which TTS model to use. We recommend `s2-pro`.",
- "required": true,
+ "required": false,
"schema": {
"default": "s2-pro",
"enum": [
"s1",
"s2-pro"
],
"title": "Model",
"type": "string"
},
"deprecated": false
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "parameters": [ | |
| { | |
| "in": "header", | |
| "name": "model", | |
| "description": "Specify which TTS model to use. We recommend `s2-pro`.", | |
| "required": true, | |
| "schema": { | |
| "default": "s2-pro", | |
| "enum": [ | |
| "s1", | |
| "s2-pro" | |
| ], | |
| "title": "Model", | |
| "type": "string" | |
| }, | |
| "deprecated": false | |
| } | |
| ], | |
| "parameters": [ | |
| { | |
| "in": "header", | |
| "name": "model", | |
| "description": "Specify which TTS model to use. We recommend `s2-pro`.", | |
| "required": false, | |
| "schema": { | |
| "default": "s2-pro", | |
| "enum": [ | |
| "s1", | |
| "s2-pro" | |
| ], | |
| "title": "Model", | |
| "type": "string" | |
| }, | |
| "deprecated": false | |
| } | |
| ], |
🤖 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 2405 - 2422, The OpenAPI parameter
"model" currently has a semantic contradiction: it is marked required:true while
also providing a default ("s2-pro"); choose one resolution—either remove the
default field from the "model" header parameter so it remains required and
clients must supply it, or set "required": false so the default "s2-pro" is
meaningful; update the "model" parameter entry in the parameters array
accordingly (leave its enum/title/type intact) and ensure only one of required
or default is present.
| "required": true, | ||
| "schema": { | ||
| "type": "string", | ||
| "default": "s2-pro", | ||
| "enum": [ | ||
| "s1", | ||
| "s2-pro" | ||
| ] | ||
| ], | ||
| "title": "Model", | ||
| "type": "string" | ||
| }, | ||
| "deprecated": false | ||
| } | ||
| ], |
There was a problem hiding this comment.
Same required/default inconsistency on the timestamp stream endpoint.
The new /v1/tts/stream/with-timestamp parameter declaration mirrors the same pattern: required: true with a default of "s2-pro". Apply the same fix here for consistency and to avoid OpenAPI-3.1 spec ambiguity.
🤖 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 2586 - 2598, The parameter
declaration for the /v1/tts/stream/with-timestamp endpoint has `required: true`
but also a `default: "s2-pro"`, which is inconsistent; update the parameter in
the OpenAPI fragment that defines the Model (enum ["s1","s2-pro"]) by removing
the `default: "s2-pro"` or alternatively set `required: false`—prefer removing
the default so the parameter remains required and the enum/title/type remain
unchanged.
1 participant
Summary
Testing
Summary by CodeRabbit
New Features
modelparameter to TTS API for model selection.Documentation