Skip to main content

Voice Design Référence de l’API

Utilisez l'API HTTP Voice Design pour créer, lister, consulter et supprimer des voix personnalisées.

Guide utilisateur : Voice Design.

Endpoint

  • China (Beijing)
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customizationRemplacez {WorkspaceId} par votre ID d'espace de travail réel.
Alibaba Cloud Model Studio a publié des domaines spécifiques à chaque espace de travail pour les régions China (Beijing). Ces nouveaux domaines dédiés offrent des performances supérieures et une stabilité accrue pour les requêtes d'inférence. Nous vous recommandons de migrer vers ces nouveaux domaines :
  • China (Beijing) : passez de dashscope.aliyuncs.com à {WorkspaceId}.cn-beijing.maas.aliyuncs.com
Remplacez {WorkspaceId} par votre ID d'espace de travail réel. Les domaines existants restent pleinement fonctionnels.

En-têtes de requête

Paramètre

Type

Obligatoire

Description

Authorization

string

Oui

Jeton d'autorisation au format Bearer <your_api_key>. Remplacez <your_api_key> par votre clé API réelle.

Content-Type

string

Oui

Type MIME du corps de la requête. Définissez cette valeur sur application/json.

Créer une voix

Corps de la requête

Les exemples suivants utilisent la configuration de la région China (Beijing). Remplacez {WorkspaceId} par votre identifiant réel d’espace de travail.
curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "create_voice",
        "target_model": "cosyvoice-v3.5-plus",
        "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.",
        "preview_text": "Dear listeners, hello everyone. Welcome to the evening news.",
        "prefix": "announcer",
        "language_hints": ["en"]
    },
    "parameters": {
        "sample_rate": 24000,
        "response_format": "wav"
    }
}'
modelstring(Obligatoire)Modèle de conception de voix. Valeurs valides :
  • voice-enrollment : conception de voix CosyVoice.
inputobject(Obligatoire)Objet des paramètres d'entrée.

Propriétés

action string(Obligatoire)Type d'opération.
  • CosyVoice (voice-enrollment) : définissez sur create_voice.
target_model string(Obligatoire)Modèle de synthèse vocale (TTS) sous-jacent à la voix. Cette valeur doit correspondre au modèle utilisé lors de l'appel à l'API TTS. Toute incompatibilité entraîne l'échec de la synthèse.voice_prompt string(Obligatoire)Description textuelle des caractéristiques vocales souhaitées. Seuls le chinois et l'anglais sont pris en charge.
  • CosyVoice (voice-enrollment) : 500 caractères maximum.
preview_text string(Obligatoire)Texte servant à générer l'audio de prévisualisation.
  • CosyVoice (voice-enrollment) : 200 caractères maximum. Le chinois et l'anglais sont pris en charge.
prefix string(Obligatoire)
S'applique uniquement à CosyVoice (lorsque le modèle est voice-enrollment).
Préfixe du nom de la voix. Seuls les chiffres et les lettres sont autorisés, avec un maximum de 10 caractères. Le nom de voix généré suit le format : {target_model}-vd-{prefix}-{unique_id}language_hints array[string](Facultatif)
S'applique uniquement à CosyVoice (lorsque le modèle est voice-enrollment).
Indications de langue pour la voix générée. Ce paramètre détermine les caractéristiques linguistiques et les schémas de prononciation de la voix. Définissez-le sur la langue correspondant à votre cas d'utilisation. La langue spécifiée doit correspondre à celle du preview_text.Actuellement, seul le premier élément est utilisé.Valeurs valides :
  • zh : chinois
  • en : anglais
Par défaut : ["zh"].
parametersobject(Facultatif)Configuration de la conception de voix.

Propriétés

sample_rate int(Facultatif)Fréquence d'échantillonnage de l'audio de prévisualisation, en Hz.
  • CosyVoice : 16000, 24000 ou 48000.
Par défaut : 24000.response_format string(Facultatif)Format de l'audio de prévisualisation.
  • CosyVoice : pcm, wav ou mp3.
Par défaut : wav.

Corps de la réponse

{
    "output": {
        "preview_audio": {
            "data": "{base64_encoded_audio}",
            "sample_rate": 24000,
            "response_format": "wav"
        },
        "target_model": "cosyvoice-v3.5-plus",
        "voice_id": "cosyvoice-v3.5-plus-vd-announcer-xxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}
request_idstringIdentifiant unique de cette requête.
outputobjectDonnées renvoyées par le modèle.

Propriétés

voice_idstringIdentifiant de la voix. Utilisez-le dans le paramètre voice de l'API TTS.preview_audioobjectDonnées audio de prévisualisation.

Propriétés

data stringDonnées audio de prévisualisation, encodées en Base64.sample_rate intFréquence d'échantillonnage de l'audio de prévisualisation, en Hz.response_format stringFormat de l'audio de prévisualisation.
target_modelstringModèle TTS sous-jacent à la voix.
usageobjectInformations d'utilisation pour cette requête.

Propriétés

count integerNombre de voix créées. Toujours égal à 1.

Lister les voix

Corps de la requête

Les exemples suivants utilisent la configuration de la région China (Beijing). Remplacez {WorkspaceId} par votre identifiant réel d’espace de travail.
curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "list_voice",
        "prefix": "myvoice",
        "page_size": 10,
        "page_index": 0
    }
}'
modelstring(Obligatoire)Modèle de conception de voix. Valeurs valides :
  • voice-enrollment : conception de voix CosyVoice.
inputobject(Obligatoire)Objet des paramètres d'entrée.

Propriétés

action string(Obligatoire)Définissez cette valeur sur list_voice.prefix string(Facultatif)
S'applique uniquement à CosyVoice.
Filtrez les voix par préfixe de nom.page_index integer(Facultatif)Index de la page.page_size integer(Facultatif)Nombre d'entrées par page.

Corps de la réponse

{
    "output": {
        "voice_list": [
            {
                "voice_id": "cosyvoice-v3.5-plus-vd-announcer-xxxxxx",
                "gmt_create": "2025-12-10 14:54:09",
                "gmt_modified": "2025-12-10 17:47:48",
                "status": "OK",
                "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.",
                "preview_text": "Dear listeners, hello everyone. Welcome to the evening news."
            }
        ]
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}
request_idstringIdentifiant unique de cette requête.
outputobjectDonnées renvoyées par le modèle.

Propriétés

voice_listarray[object]Liste des voix renvoyées par la requête.

Propriétés

voice_idstringIdentifiant de la voix. Utilisez-le dans le paramètre voice de l'API TTS.gmt_createstringDate de création.gmt_modifiedstringDate de dernière modification.statusstring
Renvoyé par CosyVoice uniquement.
État de la voix. Pour les valeurs valides, consultez « Référence des états de voix ».voice_promptstringTexte de description de la voix.preview_textstringTexte de l'audio de prévisualisation.
usageobjectInformations d'utilisation pour cette requête.

Propriétés

count integerToujours égal à 1.

Consulter les détails d'une voix

Corps de la requête

Les exemples suivants utilisent la configuration de la région China (Beijing). Remplacez {WorkspaceId} par votre identifiant réel d’espace de travail.
curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "query_voice",
        "voice_id": "yourVoiceId"
    }
}'
modelstring(Obligatoire)Modèle de conception de voix. Valeurs valides :
  • voice-enrollment : conception de voix CosyVoice.
inputobject(Obligatoire)Objet des paramètres d'entrée.

Propriétés

action string(Obligatoire)Définissez cette valeur sur query_voice.voice_id string(Obligatoire)
S'applique uniquement à CosyVoice.
ID de la voix à consulter.

Corps de la réponse

{
    "output": {
        "voice_id": "cosyvoice-v3.5-plus-vd-announcer-xxxxxx",
        "gmt_create": "2025-12-10 14:54:09",
        "gmt_modified": "2025-12-10 17:47:48",
        "preview_text": "Dear listeners, hello everyone. Welcome to the evening news.",
        "target_model": "cosyvoice-v3.5-plus",
        "status": "OK",
        "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary."
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}
request_idstringIdentifiant unique de cette requête.
outputobjectDonnées renvoyées par le modèle.

Propriétés

voice_idstringIdentifiant de la voix. Utilisez-le dans le paramètre voice de l'API TTS.gmt_createstringDate de création.gmt_modifiedstringDate de dernière modification.statusstring
Renvoyé par CosyVoice uniquement.
État de la voix. Pour les valeurs valides, consultez « Référence des états de voix ».target_modelstringModèle TTS sous-jacent à la voix.voice_promptstring
Renvoyé par la conception de voix CosyVoice uniquement.
Texte de description de la voix.preview_textstring
Renvoyé par la conception de voix CosyVoice uniquement.
Texte de l'audio de prévisualisation.
usageobjectInformations d'utilisation pour cette requête.

Propriétés

count integerToujours égal à 1.

Supprimer une voix

Corps de la requête

Les exemples suivants utilisent la configuration de la région China (Beijing). Remplacez {WorkspaceId} par votre identifiant réel d’espace de travail.
curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "delete_voice",
        "voice_id": "yourVoiceId"
    }
}'
modelstring(Obligatoire)Modèle de conception de voix. Valeurs valides :
  • voice-enrollment : conception de voix CosyVoice.
inputobject(Obligatoire)Objet des paramètres d'entrée.

Propriétés

action string(Obligatoire)Définissez cette valeur sur delete_voice.voice_id string(Obligatoire)
S'applique uniquement à CosyVoice.
ID de la voix à supprimer.

Corps de la réponse

{
    "output": {},
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}
request_idstringIdentifiant unique de cette requête.
outputobjectDonnées retournées par le modèle. Il s’agit d’un objet vide.
usageobjectInformations d'utilisation pour cette requête.

Propriétés

count integerToujours égal à 1.

Référence des états de voix

Les voix créées passent par un processus de validation. Les états suivants s’appliquent à CosyVoice lorsque model est défini sur voice-enrollment.

État

Description

DEPLOYING

En cours de validation ou de traitement.

OK

Validation réussie. La voix est prête à l'emploi.

UNDEPLOYED

Validation rejetée. La voix est inutilisable.