docs(tts): document the language field by Kilerd · Pull Request #258 · fishaudio/docs

Kilerd · 2026-10-16T08:44:33Z

Documents the optional TTS request field language (FISH-1399, part of FISH-1394). It is live in production, and TTSRequest.language is already in https://api.fish.audio/openapi.json (platform-api#2433).

language is a BCP-47 tag of the text (en, es-MX, zh-CN, zh-TW). It is used only by text normalization and word-timestamp alignment, not by the speech model. Omitted, empty or auto keeps per-chunk detection. Tags without rules skip normalization, with no error. The official SDKs don't expose it yet, so examples use raw HTTP.

Text to Speech (features/text-to-speech.mdx): new Language section with a curl example and the behavior (default, Spain vs Mexican Spanish, zh-TW, unsupported tags, mixed-language text, normalize: false, 400 validation, which routes accept it). New Supported normalization languages table: 13 rows, 42 tags. Spain/Mexico Spanish and Simplified/Traditional Chinese are separate rows, and an es vs es-MX reading example follows the table.
WebSocket schema (api-reference/asyncapi.yml): language property on WebSocketTTSRequest, which applies to the whole session. Also fixes the normalize description, which still said English and Chinese only.
Fine-grained Control overview: points to language where normalization is discussed.
fish-audio-api skill: new language row, a corrected normalize row, a session note for the WebSocket start event, and a 400 entry.
Changelog: October 16, 2026 entry.

Not touched: api-reference/endpoint/openapi-v1/* and api-reference/openapi.json. Those update through the scheduled schema sync. The open sync PR #251 was last refreshed at 03:06 UTC today and doesn't have language yet, so the next 03:00 run should add it. SDK reference pages and the compat/ElevenLabs pages are also unchanged, because the compat gateway still ignores language_code.

The check-openapi job compares the committed openapi.json against the live schema. It fails on every open PR until the sync PR is merged, so it isn't caused by this change.

^{Need help on this PR? Tag @codesmith-bot with what you need.}

Summary by CodeRabbit

Documentation
- Documented the optional TTS language field for HTTP, SSE, and WebSocket requests, including its effects on text normalization and word timestamps.
- Clarified language detection defaults, supported formats, validation errors, and behavior for unsupported languages.
- Added examples and a changelog entry; noted that official SDKs do not yet expose the field.

Add the optional TTS `language` field (BCP-47 tag) to the non-generated pages: a Language section and a supported normalization languages table on the Text to Speech page, the WebSocket start event schema in asyncapi.yml, the fine-grained control overview, the fish-audio-api agent skill, and the changelog. The OpenAPI-generated reference pages pick the field up from the scheduled schema sync. Refs FISH-1399

mintlify · 2026-10-16T08:44:37Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
hanabiaiinc	🟢 Ready	View Preview	Oct 16, 2026, 8:52 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

coderabbitai · 2026-10-16T08:44:52Z

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 52 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults
Review profile: CHILL
Plan: Advanced
Run ID: a44f0e79-41ab-4641-ae3e-07ac42ff0015

📥 Commits

Reviewing files that changed from the base of the PR and between adb0b35 and 2416a72.

📒 Files selected for processing: 1

api-reference/openapi.json

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults
Review profile: CHILL
Plan: Advanced
Run ID: 37d4ca26-410e-4e78-97db-4d6de8c1de9f

📥 Commits

Reviewing files that changed from the base of the PR and between 9a84be3 and adb0b35.

📒 Files selected for processing: 5

.mintlify/skills/fish-audio-api/SKILL.md
api-reference/asyncapi.yml
developer-guide/core-features/fine-grained-control.mdx
developer-guide/getting-started/changelog.mdx
features/text-to-speech.mdx

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

The documentation adds an optional TTS language field and describes its effects on text normalization and word timestamps, its validation and defaults, and the request interfaces that support it.

Changes: TTS language field

Layer / File(s)	Summary
Language field and normalization behavior `api-reference/asyncapi.yml`, `features/text-to-speech.mdx`, `.mintlify/skills/fish-audio-api/SKILL.md`	The API reference and TTS documentation describe the optional `language` field, validation rules, automatic detection, normalization behavior, and supported normalization languages.
Guide and WebSocket documentation `.mintlify/skills/fish-audio-api/SKILL.md`, `developer-guide/core-features/fine-grained-control.mdx`, `developer-guide/getting-started/changelog.mdx`	The guide and changelog describe language selection for normalization and timestamps. The WebSocket start-event documentation states that `request.language` applies to the whole session.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Suggested reviewers: oslatt

Merge Risk: ⚪ Minimal · up to adb0b

The language-field documentation is ready to merge after normal checks; no concrete blocking issue was identified.

Pre-merge checks: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely identifies the main change: documenting the TTS language field.
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (5 skipped: 5 unsupported.)

✨ Finishing Touches: 💡 1

🛠️ Fix failing CI checks: 💡

Commit to this branch
Create a new PR

🧪 Generate unit tests (beta)

Commit to this branch
Create a new PR

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Pull the current https://api.fish.audio/openapi.json (npm run update:openapi), which now has TTSRequest.language from platform-api#2433, so the check-openapi job passes and the generated API reference matches the Language docs in this PR.

mintlify Bot deployed to staging October 16, 2026 08:45

View deployment

chore: update OpenAPI schema

2416a72

Pull the current https://api.fish.audio/openapi.json (npm run update:openapi), which now has TTSRequest.language from platform-api#2433, so the check-openapi job passes and the generated API reference matches the Language docs in this PR.

mintlify Bot deployed to staging October 16, 2026 08:52

View deployment

Kilerd merged commit 98d19e2 into main Oct 16, 2026
6 checks passed

Kilerd deleted the docs/tts-language-field branch October 16, 2026 08:56

Kilerd mentioned this pull request Oct 16, 2026

docs(compat): say that elevenlabs language_code now maps to the fish language field #259

Merged

Navigation Menu

Repository navigation

docs(tts): document the language field - #258

docs(tts): document the language field#258
Kilerd merged 2 commits into
mainfrom
docs/tts-language-field

Kilerd commented Oct 16, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

mintlify Bot commented Oct 16, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Oct 16, 2026 •

edited

Loading

Review limit reached

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

Kilerd commented Oct 16, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

mintlify Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Kilerd commented Oct 16, 2026 •

edited by coderabbitai Bot

Loading

mintlify Bot commented Oct 16, 2026 •

edited

Loading

coderabbitai Bot commented Oct 16, 2026 •

edited

Loading