[codex] Align create model guide with API

[Kilerd]

What changed

• Aligned the Creating Voice Models guide with the current Create Model API request and response shape.
• Replaced the legacy Python SDK example with FishAudio().voices.create(...).
• Updated REST examples to use multipart form data, required type=tts and train_mode=fast, and the REST _id response field.
• Clarified that Python SDK exposes the model identifier as voice.id, while REST and JavaScript examples use _id.
• Updated model settings for enhance_audio_quality default true and added generate_sample.
• Fixed TTS follow-up examples to use reference_id.

Why

The guide mixed older SDK usage and stale field names with the current Create Model API. This made the docs disagree with the OpenAPI schema and could lead users to send invalid requests or read the wrong response field.

Validation

• ./node_modules/.bin/prettier --check developer-guide/core-features/creating-models.mdx api-reference/endpoint/model/create-model.mdx
• npm run check:openapi

Note: mint validate was also attempted and reached repository-wide pre-existing warnings in snippets/temp files unrelated to this change.

Summary by CodeRabbit

• Documentation
  • Updated API reference documentation for the model creation endpoint with clearer request formatting guidance.
  • Refreshed developer guide for creating voice models with revised code examples and improved SDK integration steps.
  • Enhanced troubleshooting and best practices sections with expanded guidance.

[mintlify]

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

Project	Status	Preview	Updated (UTC)
hanabiaiinc	🟢 Ready	View Preview	May 13, 2026, 6:39 AM

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

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR refreshes documentation for voice model creation across the API reference and developer guide. It updates the Create Model endpoint reference with clarified multipart/form-data guidance, replaces SDK code examples with current FishAudio client patterns, modernizes REST API examples, refines model settings tables, and expands troubleshooting and best-practices sections.

Changes

Voice Model Creation Documentation

Layer / File(s)	Summary
API Reference Endpoint Documentation api-reference/endpoint/model/create-model.mdx	Frontmatter quoting is normalized and the request encoding warning is rewritten to specify multipart/form-data with automatic client boundary handling, removing prior application/msgpack mention.
Model Creation SDK Examples developer-guide/core-features/creating-models.mdx	Web UI steps are consolidated, Python SDK example is replaced with FishAudio client using client.voices.create(...) with in-memory reads, and JavaScript SDK example is updated to async FishAudioClient calling voices.ivc.create(...) with error handling and state logging.
REST API Direct Examples and Model Settings developer-guide/core-features/creating-models.mdx	Direct API documentation is updated with refreshed cURL and Python REST examples, JavaScript REST example is rewritten to use FormData and fetch, and model settings tables are updated with current parameter descriptions, defaults, and option values.
Audio Setup, Transcripts, and Model Usage developer-guide/core-features/creating-models.mdx	Audio requirements formatting is adjusted, Python transcript-addition example is replaced with explicit requests.post(...) call, a mandatory note is added stating transcript count must match audio file count, and Using Your Model examples switch to SDK-based TTS with client.tts.convert(...) (Python) and fishAudio.textToSpeech.convert(...) (JavaScript) with file output.
Troubleshooting, Best Practices, and Support developer-guide/core-features/creating-models.mdx	Troubleshooting section expands common-issue guidance, best-practices list is revised with clarified recommendations, and support contact email is adjusted to appear as a dedicated list item.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested labels

python

Poem

🐰 A rabbit hops through docs with care,
SDK examples fresh and fair,
REST API guidance crystal clear,
Multipart boundaries without fear—
Voice models bloom when docs guide true!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title '[codex] Align create model guide with API' clearly summarizes the main objective: aligning documentation with the current API implementation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/create-model-api-alignment

---

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 and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

developer-guide/core-features/creating-models.mdx (1)

19-53: ⚡ Quick win

Add a short prerequisites block before procedural steps.

This guide now has multiple executable flows, but it doesn’t list prerequisites up front (API key, SDK install/runtime, sample audio files). Adding that near the first procedure will reduce setup friction and support failures.

As per coding guidelines, "Include prerequisites at the start of procedural content".

Also applies to: 113-123

🤖 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 `@developer-guide/core-features/creating-models.mdx` around lines 19 - 53, Add
a short "Prerequisites" block and insert it before the first procedural section
(i.e., before the <Steps> block under "Web Interface") and likewise before other
procedural flows such as the "Using the API" / "Using the SDK" sections; this
block should list required items like an account and API key, required
SDK/runtime versions (e.g., pip/npm install steps), minimum sample audio
requirements (number of files and minimum duration per file), and any
environment or permission requirements so readers can complete the subsequent
<Step> and code examples without unknown preconditions.

🤖 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.

Nitpick comments:
In `@developer-guide/core-features/creating-models.mdx`:
- Around line 19-53: Add a short "Prerequisites" block and insert it before the
first procedural section (i.e., before the <Steps> block under "Web Interface")
and likewise before other procedural flows such as the "Using the API" / "Using
the SDK" sections; this block should list required items like an account and API
key, required SDK/runtime versions (e.g., pip/npm install steps), minimum sample
audio requirements (number of files and minimum duration per file), and any
environment or permission requirements so readers can complete the subsequent
<Step> and code examples without unknown preconditions.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 90c832db-d44a-4756-b42f-ce5e77a16dae

📥 Commits

Reviewing files that changed from the base of the PR and between fc585de and 5657e6f.

📒 Files selected for processing (2)

• api-reference/endpoint/model/create-model.mdx
• developer-guide/core-features/creating-models.mdx