[leng-yue]

Summary

New accounts start with no API credit, and s2.1-pro-free is the TTS model they can call for free. The Python SDK already forwards any model value as the request header, so it worked at runtime. But the Model type did not list it, so type checkers rejected the call the docs now show (client.tts.convert(..., model="s2.1-pro-free")). Linear: FISH-1664.

• feat(types): add "s2.1-pro-free" to Model (src/fishaudio/types/shared.py), plus a unit test that it is sent as the model header.
• docs(readme):
  • "Selecting a model" also shows model="s2.1-pro-free";
  • the fish.audio API-key link carries utm_source=github&utm_medium=sdk-readme&utm_content=python, so README signups can be attributed. The README has no separate signup link.

The default model is unchanged (s2.1-pro on main). Changing it is an owner decision; the options are listed in the FISH-1662/1664 write-up.

Testing

• uv run poe format, lint, typecheck (ty): pass.
• uv run poe test: 158 passed, including the new test_convert_with_free_model.
• Integration tests were not run (they need an API key).

Notes

PyPI is still on 1.3.0 (2026-03-10), whose Model has no s2.1 models at all. This change only reaches users once main is released.

🤖 Generated with Claude Code

---

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

Summary by CodeRabbit

• New Features
  • Added support for the s2.1-pro-free and drama-3 text-to-speech models, including in synchronous conversion requests.
• Bug Fixes
  • Opus bitrates are now serialized in bits per second; automatic bitrate values remain unchanged.
• Documentation
  • Expanded the text-to-speech model-selection example to include s2.1-pro-free and drama-3.
  • Updated the API-key page link to include tracking parameters.

Update: Model now also accepts drama-3, with a README example and a unit test (owner request).

Also fixes opus: since platform-api #625 the API takes opus_bitrate in bps. The SDK sent kbps, so every format="opus" request returned HTTP 400 ("Invalid opus bitrate 32"); the integration test test_tts_with_different_formats caught it once CI had a valid key. TTSConfig and TTSRequest keep their public kbps values, and the request serializer converts them to bps. A unit test covers it.

[coderabbitai]

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 92aecb15-7928-49ac-9b5f-6acc66754bdf

Commits

Reviewing files that changed from the base of the PR and between b90a207 and f9c2420.

Files selected for processing: 2

• src/fishaudio/types/tts.py
• tests/unit/test_types.py

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

Walkthrough

The PR adds s2.1-pro-free and drama-3 to the accepted model values, updates README examples, and adds conversion tests. It also serializes positive Opus bitrate values in thousands of bits per second and adds UTM parameters to the README API-key link.

Changes: TTS model support

Layer / File(s)	Summary
Add TTS model examples and test conversions src/fishaudio/types/shared.py, README.md, tests/unit/test_tts.py	The model type accepts s2.1-pro-free and drama-3. The README shows examples for both, and tests check the model header and returned audio bytes.

Opus bitrate serialization

Layer / File(s)	Summary
Serialize Opus bitrate values src/fishaudio/types/tts.py, tests/unit/test_types.py	TTSRequest multiplies positive opus_bitrate values by 1,000 during serialization. It leaves zero and negative values unchanged. Tests cover the default, an explicit positive value, and a negative value.

API-key URL tracking

Layer / File(s)	Summary
Add API-key URL tracking parameters README.md	The API-key URL adds utm_source=github, utm_medium=sdk-readme, and utm_content=python.

Priority: Normal

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

Change: Feature

Suggested reviewers: twangodev

Merge Risk: Minimal · up to f9c24

No concrete current-head defect or merge-blocking risk was identified.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly identifies the main change: adding s2.1-pro-free and drama-3 to Model. It also accurately mentions the README updates and linked issue.
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

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 1 functions across 4 files.

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• 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

• X
• Mastodon
• Reddit
• LinkedIn

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines	Coverage Δ
src/fishaudio/types/shared.py	100.00% <100.00%> (ø)
src/fishaudio/types/tts.py	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

🟢 Approval recommended

There are no active review issues blocking the addition of typed support for s2.1-pro-free.

No open issues 🎉

What changed in this PR

Adds typed support for s2.1-pro-free in the Python SDK so callers can select the free TTS model without type-checker errors. The default model remains s2.1-pro.

Changes:

• Adds s2.1-pro-free to the Model literal type.
• Adds a unit test verifying the free model is forwarded in the request header.
• Documents free-model usage and adds attribution parameters to the API-key link.

File	Description
tests/​unit/​test_tts.py	Tests free-model header forwarding and returned audio.
src/​fishaudio/​types/​shared.py	Includes s2.1-pro-free in the accepted model type.
README.md	Adds a free-model example and API-key link tracking parameters.

_{Review effort: Balanced}

[leng-yue]

Note for reviewers: the Integration Tests job fails on this PR with 401 Invalid token across all tests. The repo secret FISH_API_KEY (last set 2025-11-13) no longer authenticates, so this affects every PR, not this diff (types + README only). Unit tests, lint and type-check pass. The secret needs a fresh key from an account with API credit.