Voice Catalog & Search
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.
List every available TTS voice, or describe your content in plain language and let the server recommend voices for it.
Synthesis itself goes through the Voice Clone TTS endpoint; the two endpoints on this page only help you pick a voice.
Voice Catalog
Basics
| Item | Value |
|---|---|
| Method | GET |
| Path | /task/tts/voices |
| Auth | None required |
| Caching | Cache-Control: public, max-age=60 + ETag |
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
engine | string | No | Return only voices from this engine |
maturity | string | No | Return only voices of this maturity: stable / experimental |
Response Fields
| Field | Type | Description |
|---|---|---|
voice_id | string | Voice identifier — this is what you pass as speaker when synthesizing |
display_name | string | Display name |
gender | string | Gender |
languages | string[] | Languages (BCP-47) |
dialect | string | Dialect (e.g. sichuan, dongbei; empty if none) |
persona | string | Persona slot |
desc | string | Voice description (Chinese) |
tags | string[] | Tags covering timbre, character and subject matter |
topics | string[] | Subjects this voice suits |
not_suitable | string | What it does not suit, and why |
speed_range | object | Adjustable speed range {min, max, default}. Differs per voice; min equal to max at 1.0 means the voice does not support speed control |
speech_rate_cpm | number | Estimated wall-clock speech rate (characters per minute): script characters ÷ total synthesized audio duration, pauses between sentences included, taken at the voice's actually effective default synthesis parameters — speed_range.default does not describe that baseline. Use it to estimate how long a script runs in a given voice. An estimate; never used for billing. Present on Chinese voices only (zh-CN / zh-HK / yue-HK) — see below |
speech_rate_basis | string | Where speech_rate_cpm comes from: measured (calibrated by measurement) / derived (computed from acoustic analysis). Always present together with speech_rate_cpm |
styles | string[] | Speaking styles this voice supports (engine-dependent) |
credits_per_kchar | integer | Unit price (credits per 1,000 characters) — the current billing basis. Matches the "Voice Clone TTS" tiers on the pricing page tier for tier |
credits_per_minute | integer | ⚠️ Deprecated (the billing unit changed from minutes to 1,000 characters in August 2026). Emitted alongside credits_per_kchar during the transition only, because older docs told users to read it; it will be removed after the announcement period. Do not use in new integrations |
audition_url | string | Sample clip. Every voice reads the same line, so they can be compared directly |
engine | string | Synthesis engine |
maturity | string | stable / experimental |
experimental | boolean | Present only on experimental voices. See below |
internal_only | boolean | Present only on internal-member voices |
available_to_you | boolean | Whether your identity can use that voice |
Wall-clock speech rate
speech_rate_cpm lets you estimate script length or audio duration per voice — for example, a 3-minute target at 310 characters per minute comes to roughly 930 characters.
- It is an estimate. Actual duration also depends on punctuation, how numbers are read, and pause settings; the service makes no duration guarantee, and the value plays no part in billing (billing uses
credits_per_kchar). - Only Chinese voices carry these two fields. Per-character speech rates are not comparable for English or Japanese, so those voices omit them.
- When data is missing, both fields are omitted together — you will never see
null. Fall back to your own default in that case, and do not present that default as the service's figure. speech_rate_basis: derivedmeans the value is computed from acoustic analysis and has not been calibrated by measurement yet; voices calibrated later switch tomeasured, and the value may change with it.- The baseline is the voice's actually effective default synthesis parameters. For some in-house voices the effective default speed multiplier differs from
speed_range.default, so do not usespeed_range.defaultto rescale this value. - Semantic-search candidates carry the same two fields, so you can estimate script length while choosing a voice.
Experimental voices
Voices carrying experimental: true come with no stability guarantee — the voice may change or be withdrawn, and they are intended for testing only. If your workload needs stability, filter them out with ?maturity=stable.
Internal voices
Voices carrying internal_only: true still appear in the catalog, but only Gitruck Cloud internal members may use them. Other accounts get a parameter error explaining why — there is no silent fallback to a different voice, because a finished video in the wrong voice is worse than a clear error.
Caching
The response carries an ETag. Send it back in If-None-Match on the next request; if nothing changed you get 304 with an empty body.
curl -i "https://api.ai-mcn.tv:10000/task/tts/voices?maturity=stable"
# then, with the ETag you received
curl -i -H 'If-None-Match: "<previous ETag>"' "https://api.ai-mcn.tv:10000/task/tts/voices"
Semantic Search
Describe what you are making in one sentence and get back the closest candidates.
Basics
| Item | Value |
|---|---|
| Method | POST |
| Path | /task/tts/voices/search |
| Content-Type | application/json |
| Auth | Authorization header |
Request Body
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
query | string | Yes | — | Plain-language description of the subject or the feel you want |
top_k | integer | No | 5 | Number of candidates, up to 20 |
filters | object | No | — | Narrow the pool. Keys: engine / persona / gender / dialect; values may be a single value or an array |
Response
Each candidate carries the same fields as the catalog, plus:
| Field | Type | Description |
|---|---|---|
score | number | Similarity |
why | string | Why it matched — persona, key tags, suited subjects |
These are candidates, not a verdict. Picking a voice is an aesthetic call, so the final choice is yours; this endpoint will not drop candidates on your behalf based on score.
Example Request
{
"query": "a low, measured male voice for history storytelling, like an old scholar",
"top_k": 5,
"filters": { "gender": "男" }
}
The more specific the description, the better it works. A query that only states gender does far less than one naming dialect, character and pace together.
Limits
- Search requires auth (it runs an embedding pass, which costs compute); the catalog does not.
- The catalog changes over time — read it from the endpoint rather than hard-coding a voice list.
🤝 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.