Category: provider
Model Studio CosyVoice Voice Design
Use the CosyVoice voice enrollment API to create designed voices from a natural-language voice description.
Critical model names
Use model="voice-enrollment" and one of these target_model values:
cosyvoice-v3.5-pluscosyvoice-v3.5-flashcosyvoice-v3-pluscosyvoice-v3-flash
Recommended default in this repo:
target_model="cosyvoice-v3.5-plus"
Region and compatibility
cosyvoice-v3.5-plus and cosyvoice-v3.5-flash are available only in China mainland deployment mode (Beijing endpoint).- In international deployment mode (Singapore endpoint),
cosyvoice-v3-plus and cosyvoice-v3-flash do not support voice clone/design.
- The
target_model must match the later speech synthesis model.
Endpoint
- Domestic:
https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
- International:
https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization
Prerequisites
- Set
DASHSCOPE_API_KEY in your environment, or add dashscope_api_key to ~/.alibabacloud/credentials.
Normalized interface (cosyvoice.voice_design)
Request
model (string, optional): fixed to voice-enrollmenttarget_model (string, optional): default cosyvoice-v3.5-plusprefix (string, required): letters/digits only, max 10 charsvoice_prompt (string, required): max 500 chars, Chinese or English onlypreview_text (string, required): max 200 chars, Chinese or Englishlanguage_hints (array[string], optional): zh or en, and should match preview_textsample_rate (int, optional): e.g. 24000response_format (string, optional): e.g. wav
Response
voice_id (string)request_id (string)status (string, optional)
Operational guidance
- Keep
voice_prompt concrete: timbre, age range, pace, emotion, articulation, and scenario.
- If
language_hints is used, it should match the language of preview_text.
- Designed voice names include a
-vd- marker in the generated backend naming convention.
Local helper script
Prepare a normalized request JSON:
python skills/ai/audio/aliyun-cosyvoice-voice-design/scripts/prepare_cosyvoice_design_request.py \
--target-model cosyvoice-v3.5-plus \
--prefix announcer \
--voice-prompt "沉稳的中年男性播音员，低沉有磁性，语速平稳，吐字清晰。" \
--preview-text "各位听众朋友，大家好，欢迎收听晚间新闻。" \
--language-hint zh
Validation
mkdir -p output/aliyun-cosyvoice-voice-design
for f in skills/ai/audio/aliyun-cosyvoice-voice-design/scripts/*.py; do
python3 -m py_compile "$f"
done
echo "py_compile_ok" > output/aliyun-cosyvoice-voice-design/validate.txt
Pass criteria: command exits 0 and output/aliyun-cosyvoice-voice-design/validate.txt is generated.
Output And Evidence
- Save artifacts, command outputs, and API response summaries under
output/aliyun-cosyvoice-voice-design/.
- Include
target_model, prefix, voice_prompt, and preview_text in the evidence file.
References
references/api_reference.mdreferences/sources.md
1---2name: aliyun-cosyvoice-voice-design3description: Use when designing custom voices with Alibaba Cloud Model Studio CosyVoice customization models, especially cosyvoice-v3.5-plus or cosyvoice-v3.5-flash, from a voice prompt plus preview text before using the returned voice_id in TTS.4---5
6Category: provider
7
8# Model Studio CosyVoice Voice Design
9
10Use the CosyVoice voice enrollment API to create designed voices from a natural-language voice description.
11
12## Critical model names
13
14Use `model="voice-enrollment"` and one of these `target_model` values:
15- `cosyvoice-v3.5-plus`
16- `cosyvoice-v3.5-flash`
17- `cosyvoice-v3-plus`
18- `cosyvoice-v3-flash`
19
20Recommended default in this repo:
21- `target_model="cosyvoice-v3.5-plus"`
22
23## Region and compatibility
24
25- `cosyvoice-v3.5-plus` and `cosyvoice-v3.5-flash` are available only in China mainland deployment mode (Beijing endpoint).
26- In international deployment mode (Singapore endpoint), `cosyvoice-v3-plus` and `cosyvoice-v3-flash` do not support voice clone/design.
27- The `target_model` must match the later speech synthesis model.
28
29## Endpoint
30
31- Domestic: `https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization`
32- International: `https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization`
33
34## Prerequisites
35
36- Set `DASHSCOPE_API_KEY` in your environment, or add `dashscope_api_key` to `~/.alibabacloud/credentials`.
37
38## Normalized interface (cosyvoice.voice_design)
39
40### Request
41- `model` (string, optional): fixed to `voice-enrollment`
42- `target_model` (string, optional): default `cosyvoice-v3.5-plus`
43- `prefix` (string, required): letters/digits only, max 10 chars
44- `voice_prompt` (string, required): max 500 chars, Chinese or English only
45- `preview_text` (string, required): max 200 chars, Chinese or English
46- `language_hints` (array[string], optional): `zh` or `en`, and should match `preview_text`
47- `sample_rate` (int, optional): e.g. `24000`
48- `response_format` (string, optional): e.g. `wav`
49
50### Response
51- `voice_id` (string)
52- `request_id` (string)
53- `status` (string, optional)
54
55## Operational guidance
56
57- Keep `voice_prompt` concrete: timbre, age range, pace, emotion, articulation, and scenario.
58- If `language_hints` is used, it should match the language of `preview_text`.
59- Designed voice names include a `-vd-` marker in the generated backend naming convention.
60
61## Local helper script
62
63Prepare a normalized request JSON:
64
65```bash
66python skills/ai/audio/aliyun-cosyvoice-voice-design/scripts/prepare_cosyvoice_design_request.py \
67 --target-model cosyvoice-v3.5-plus \
68 --prefix announcer \
69 --voice-prompt "沉稳的中年男性播音员，低沉有磁性，语速平稳，吐字清晰。" \
70 --preview-text "各位听众朋友，大家好，欢迎收听晚间新闻。" \
71 --language-hint zh
72```
73
74## Validation
75
76```bash
77mkdir -p output/aliyun-cosyvoice-voice-design
78for f in skills/ai/audio/aliyun-cosyvoice-voice-design/scripts/*.py; do
79 python3 -m py_compile "$f"
80done
81echo "py_compile_ok" > output/aliyun-cosyvoice-voice-design/validate.txt
82```
83
84Pass criteria: command exits 0 and `output/aliyun-cosyvoice-voice-design/validate.txt` is generated.
85
86## Output And Evidence
87
88- Save artifacts, command outputs, and API response summaries under `output/aliyun-cosyvoice-voice-design/`.
89- Include `target_model`, `prefix`, `voice_prompt`, and `preview_text` in the evidence file.
90
91## References
92
93- `references/api_reference.md`
94- `references/sources.md`
cinience