Document voice upload fields on Create Model

[AlvaroBalbin]

Two separate reports asked how to pass samples when creating a model: #40 ("samples": [], how do I pass it?) and #41 (no correct sample parameter was returned. The sample cannot be edited).

The answer is that samples is not a request field at all, and nothing in the page said so. Checked against https://api.fish.audio/openapi.json for POST /model:

• the request schema has no samples property, in any of the four content types it accepts
• required is ["type", "title", "train_mode", "voices"]
• samples appears only on the 201 response model, as {"default": [], "items": {"$ref": "#/components/schemas/SampleEntity"}}

That empty-list default is what both reporters were looking at in the playground.

The page was only the multipart warning, so this adds the smallest thing that answers the question:

• the four required fields, named
• a multipart/form-data example that repeats voices for several clips, matching the style already used in features/voice-cloning.mdx
• how texts maps to the clips, and that ASR runs when it is omitted
• a note that samples is response-only

No generated files touched. api-reference/openapi.json is deliberately left alone.

Heads up on CI: check-openapi fails here because the committed api-reference/openapi.json is behind the live schema, which is what #107 updates. It is unrelated to this change.

Closes #40
Closes #41

Summary by CodeRabbit

• Documentation
  • Added guidance for uploading voice files when creating a model.
  • Documented required fields, multipart upload formatting, multiple audio clips, and optional transcripts.
  • Clarified that transcripts may be omitted to enable automatic speech recognition.
  • Explained that samples is returned as preview data rather than submitted in the request.

[coderabbitai]

📝 Walkthrough

Walkthrough

The create-model endpoint reference adds instructions for multipart voice uploads, repeated audio and transcript fields, automatic ASR behavior, and the response-only samples field.

Changes

Model upload documentation

Layer / File(s)	Summary
Document voice upload request api-reference/endpoint/model/create-model.mdx	Adds required multipart fields, a curl example with repeated voices entries, optional ordered texts transcripts, ASR behavior when transcripts are omitted, and clarification that samples appears in the response rather than the request.

Estimated code review effort: 1 (Trivial) | ~2 minutes

🚥 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 is concise and accurately describes the main documentation change for Create Model voice upload fields.
Linked Issues check	✅ Passed	The docs now clarify voice upload fields and that samples is response-only, addressing both linked issues.
Out of Scope Changes check	✅ Passed	The change is confined to the Create Model endpoint docs and stays within the documented voice-upload scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 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/endpoint/model/create-model.mdx`:
- Line 20: Update the code fence preceding the curl example in the create-model
documentation from the invalid “bash curl” info string to the valid “bash”
language tag, preserving the example content and project formatting conventions.

🪄 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: f00ad9aa-ab1d-4027-8559-65d938473326

📥 Commits

Reviewing files that changed from the base of the PR and between 1ac2cfe and d35b891.

📒 Files selected for processing (1)

• api-reference/endpoint/model/create-model.mdx

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Use a valid language tag for the code fence.

Change ```bash curl to ```bash; the current info string may prevent MDX renderers from recognizing the block as Bash. As per coding guidelines, all code blocks must include language tags and examples must follow the project’s formatting conventions.

🤖 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/endpoint/model/create-model.mdx` at line 20, Update the code
fence preceding the curl example in the create-model documentation from the
invalid “bash curl” info string to the valid “bash” language tag, preserving the
example content and project formatting conventions.

Source: Coding guidelines