Voice Clone TTS

The enum values printed on this page are a snapshot. The machine-readable source of truth is the Enum Catalog — where the two disagree, that one wins.

Provide text and a voice (speaker) to synthesize speech in that voice (voice cloning). No file upload required — the input is text.

Create Task

Basics

Item	Value
Method	POST
Path	/task/audio_tts_clone
Content-Type	application/json
Auth	Authorization header (pass the API Key directly)

Request Body

Field	Type	Required	Default	Description
text	string	Yes	—	Text to synthesize; non-empty, up to 5000 characters
speaker	string	Yes	—	Voice code (see "Available Voices" below)
text_lang	string	No	the voice's language	Target language (BCP-47, e.g. zh-CN). Usually unnecessary — the voice already determines the language; omit it and the voice's own language is used
output_format	string	No	wav	Output audio format: wav or mp3
refresh	boolean	No	false	Force re-synthesis (skip the cache) for a fresh take; cloud voices only
speed	number	No	voice preset	Speech speed factor (1.0 = normal). The valid range differs per voice — use the speed_range returned by the voice list endpoint; some voices do not support speed control (their speed_range has min and max both 1.0). Out-of-range values are rejected up front: no task is created and nothing is billed
subtitle_format	string	No	no subtitle	Pass srt to also receive a .srt subtitle file (UTF-8, no BOM, LF line endings). Timings come from this run's per-sentence timeline and match the audio exactly; overly long sentences are split into multiple lines for the canvas, and the lines of one sentence share its time span in proportion to their length; no extra charge. Omit it and nothing is generated — the outputs stay exactly as before. srt is currently the only accepted value; anything else returns a parameter error
strip_punctuation	boolean	No	true	Punctuation stripping, affecting only the text of the bonus .srt subtitle from subtitle_format: stripping is on by default (punctuation looks poor in subtitles) — Chinese ， 。 and English , . are replaced with spaces, in-word forms are exempt (decimals 3.5, domains example.com, thousands separators 1,000 stay intact), and all other punctuation (quotes, question marks, exclamation marks, dashes, etc.) is kept; consecutive spaces collapse to one and line edges are trimmed. Timecodes, line counts, the audio, and segments are unchanged. Pass false explicitly to keep punctuation intact
canvas	integer[]	No	[1080, 1920] (portrait)	Output canvas [width, height] as two positive integers, accepted only together with subtitle_format (sending it alone returns a parameter error). Subtitles split overly long sentences into multiple lines for this canvas — portrait splits more finely than landscape; omit it and the portrait default is used, so pass [1920, 1080] explicitly for landscape videos. Affects subtitle line breaks only; the audio and segments are unchanged
text_split_method	string	No	voice preset (usually cut1)	How long text is split, effective for self-trained (gpt_sovits) voices only; cloud voices currently ignore it and will reject it after an observation period (date to be announced), so do not send it for cloud voices — cloud voices already produce one sentence per segment, so you do not need this parameter to split sentences. It determines the granularity of segments (subtitles break there first, then overly long sentences are split into lines for the canvas): cut1 = group up to 4 sentences, cut2 = about 50 characters, cut3 = at Chinese full stops, cut4 = at English periods, cut5 = at every punctuation mark (one sentence each), cut0 = no split. Pass cut5 to break subtitles at every sentence end
fragment_interval	number	No	voice preset	Pause between sentences, in seconds; effective for Tonghe in-house (gpt_sovits) voices only. Valid range [0.05, 1.0] seconds (inclusive — both endpoints are accepted); out-of-range values return a parameter error and are never silently clamped — no task is created and nothing is billed. ⚠️ Cloud voices return an explicit error if you pass it, which is the opposite of text_split_method above (cloud voices ignore that one) — do not assume from that row that passing this one is merely a no-op. Omit it and the voice's own tuned preset is used; the output is byte-for-byte identical to what it was before this parameter shipped

Available Voices (speaker)

This table is generated from the server-side voice catalog, not maintained by hand. For the full field set (persona, tags, suited subjects, speed range) see Voice Catalog & Search. The "Source (engine)" column mirrors the engine field of the voice catalog endpoint (Tonghe in-house = gpt_sovits, Alibaba Cloud = aliyun, Volcengine = volcengine, Microsoft Azure = azure) and can be used directly as that endpoint's engine filter value; the price per 1,000 characters differs by source, matching the billing tiers of "Voice Clone TTS" on the pricing page. Rows are grouped by source, groups ordered by their lowest price and rows within a group by price ascending. "Demo" plays a sample clip; every voice reads the same line so they can be compared directly. Voices marked "internal members only" are available to Gitruck Cloud internal members; other accounts requesting them receive a parameter error explaining why.

Billing

Billed by the character count of the input text, in units of 1,000 characters.

• Billable units = text character count ÷ 1000 (fractional units are preserved)
• Billing depends only on the text you submit, not on the length of the synthesized audio — slowing the speed makes the audio longer but does not change the charge
• The final charge is rounded up to a whole credit; any non-empty text costs at least 1 credit

The unit price depends on the voice's engine and tier (5–50 credits per 1,000 characters); see the credits_per_kchar field returned by the voice list endpoint, which matches the "Voice Clone TTS" tiers on the pricing page.

How characters are counted

Rule	Detail
Counting basis	Unicode code points — one Chinese, Japanese, or Korean character counts as 1; Latin counts per letter and numbers per digit
Leading/trailing whitespace	Not counted (text is trimmed before validation)
Inner spaces, newlines, punctuation	Counted as 1 each

For example, 1000 characters = 1 unit; synthesized with a voice priced at 5 credits per 1,000 characters, that costs 5 credits.

⚠️ The billing unit changed from "minutes" to "1,000 characters" in August 2026. The earlier wording — "billed by synthesized duration, with billed minutes derived at 240 chars/minute" — is obsolete. That conversion was a pseudo-unit and has been removed: a capability billed per character should state its unit in characters.

During the transition the voice list endpoint returns both credits_per_kchar (current) and credits_per_minute (deprecated, kept only because older docs told users to read it). credits_per_minute will be removed after the announcement period. New integrations should read credits_per_kchar only.

Example Request

curl -X POST https://api.ai-mcn.tv:10000/task/audio_tts_clone \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, welcome to this episode.",
    "speaker": "narrator",
    "output_format": "wav",
    "speed": 1.0
  }'

Success Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178247",
    "task_type": "audio_tts_clone",
    "status": "queued"
  }
}

---

Query Task Result

Basics

Item	Value
Method	GET
Path	/task/audio_tts_clone/{task_id}
Auth	Authorization header (pass the API Key directly)

Response (output_result)

Field	Type	Description
file_id	string	Synthesized audio file ID
download_url	string	Audio download path
speaker	string	Voice code used
voice_id	string	Same as speaker (aligned with the voice list endpoint's field name)
engine	string	Synthesis engine
sample_rate	integer	Audio sample rate (Hz)
duration_ms	integer	Actual audio length in milliseconds. Unrelated to billing — billing depends only on the input text's character count
billed_chars	integer	Character count reported by the upstream engine. Cloud voices only (self-trained gpt_sovits voices do not return this field). ⚠️ It is an upstream usage record, not your billing basis: engines count differently (Volcengine reports upstream usage.text_words, for example), while your charge always follows the rules in "How characters are counted" above
segments	array	Per-sentence timing [{index, text, start_ms, end_ms}]: where each sentence starts and ends in the audio, ready for subtitle alignment and cut points. end_ms includes the sentence-final pause; the timeline is contiguous with no gaps. Always present for cloud voices; for self-trained voices the granularity follows the text_split_method request parameter (see the request table above; the cut1 default groups up to 4 sentences per segment) — pass cut5 for one sentence per segment
subtitle_file_id	string	Subtitle file (.srt) ID. Present only when subtitle_format was requested; empty string if generation failed, with the reason in errors.subtitle
subtitle_file_download_url	string	Subtitle file download path
errors	object	Present only when a bonus artifact was degraded. Subtitle failures are recorded under errors.subtitle — the task is still completed and the audio is unaffected
cache_hit	boolean	Present (and true) only when the synthesis cache was hit — the audio is reused from the previous run

Success Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178247",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "file_id": "537489015178248",
      "download_url": "/download/a1/output_tts.wav",
      "speaker": "narrator",
      "voice_id": "narrator",
      "engine": "gpt_sovits",
      "sample_rate": 32000,
      "duration_ms": 5240,
      "billed_chars": 16,
      "segments": [
        { "index": 0, "text": "First sentence here.", "start_ms": 0, "end_ms": 2600 },
        { "index": 1, "text": "Second sentence here.", "start_ms": 2600, "end_ms": 5240 }
      ]
    },
    "create_time": "2026-06-21T08:00:00Z",
    "update_time": "2026-06-21T08:00:12Z"
  }
}

Error Codes

Code	HTTP	Description	Resolution
6013	400	Missing required parameter (text / speaker)	Provide the parameter
6016	400	Invalid business parameter (unavailable speaker, empty or overlong text, speed out of range, invalid subtitle_format, invalid canvas or canvas sent without subtitle_format, fragment_interval out of range, fragment_interval passed with a cloud voice, etc.)	Fix per the parameter spec
6502	401	Authentication failed	Check the Authorization header
6201	402	Insufficient quota	Top up in the dashboard
6202	402	Insufficient balance	Top up in the dashboard

Limits

⚠️ Behavior change (2026-09-13): As of 2026-09-13, requests with subtitle_format split overly long sentences into multiple subtitle lines for the canvas; when canvas is omitted the portrait default [1080, 1920] is used, so subtitle lines are shorter than the previous one-cue-per-sentence output. The audio, segments, and each sentence's start and end timings are unchanged. For landscape videos, pass canvas: [1920, 1080] explicitly.

⚠️ Behavior change (2026-08-22): As of 2026-08-22, the bonus .srt subtitle from subtitle_format strips Chinese and English commas and periods from its text by default (strip_punctuation defaults to true), so identical requests produce different subtitle text than before the upgrade; timecodes, line counts, the audio, segments, and all other output fields are unchanged. To keep the previous behavior, pass strip_punctuation: false explicitly.

• Up to 5000 characters per request. Long text is split into sentences and synthesized sentence by sentence server-side, so you do not need to split it — but longer means slower: the slowest engine runs at roughly 0.11 s per character, so 5000 characters takes about 9 minutes.
• Long text is split into sentences server-side, synthesized sentence by sentence and concatenated; no need to split it yourself. Cloud voices synthesize sentences in parallel — long scripts take roughly a third of the serial time (Alibaba voices remain serial for now).
• Resubmitting with identical parameters (text, voice, speed, format) hits the synthesis cache and returns the previous audio (same file_id) almost instantly; billing is unchanged. For a fresh take (synthesis is non-deterministic — every re-synthesis is a new performance), pass "refresh": true.
• Subtitles (subtitle_format) are free: they are generated from the per-sentence timeline this run already produced, so the timings match the audio exactly (millisecond precision, no rounding). Subtitles break where segments break first (for self-trained voices, pass text_split_method: "cut5" to break at every sentence end; cloud voices always produce one sentence per segment), then overly long sentences are split into lines for the canvas.
• Subtitles are a bonus artifact: if generation fails (e.g. the per-sentence timeline is unusable for a particular self-trained run), the task still completes and the audio is returned as usual, with subtitle_file_id empty and the reason in errors.subtitle.
• Sentence pauses are adjustable (fragment_interval): in-house voices let you tighten the gap between sentences. Measured reference: in a 203-second narration, roughly a quarter of the runtime is inter-sentence silence; setting the pause to 0.2 seconds brings the same script down to 171 seconds. Omit it and the voice's own tuned preset is used — the output is byte-for-byte identical to what it was before this parameter shipped.
• Cloud voices do not support adjusting sentence pauses: passing fragment_interval returns a parameter error outright (no task created, nothing billed) rather than being silently ignored — you will not be handed audio that "looks unchanged" and left guessing. For a tighter rhythm, switch to a Tonghe in-house voice.
• Only authorized, quality-approved voices are available (see "Available Voices").
• Voices marked "internal members only" require Gitruck Cloud internal membership; other accounts requesting them receive a parameter error (no silent fallback to another voice).

🤝 Join the Tonghe New Media Network to unlock internal member benefits: network members (internal) get custom-scope full-library material search (video / image / audio, including concept and non-commercial materials, with a commercial-only filter) and exclusive internal voices. Apply at the Creator Network; once approved, an administrator will enable internal access for you.