Soumettre des prompts textuels et des audios de référence via HTTPS pour recevoir des fichiers audio générés. Cette page décrit les requêtes, les réponses et la gestion des erreurs.
Prérequis
Obtenir une clé API et un ID d'espace de travail de la région sélectionnée. Les définir comme variables d'environnement DASHSCOPE_API_KEY et SFM_WORKSPACE_ID. Les exemples ci-dessous utilisent Pékin.
Envoyer des requêtes HTTPS POST au point de terminaison suivant. Remplacer {WorkspaceId} par votre ID d'espace de travail.
- Singapour
- Chine (Pékin)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizerEn-têtes
| En-tête | Obligatoire | Description |
|---|---|---|
| Authorization | Oui | Bearer <API Key> |
| Content-Type | Oui | application/json |
Exemple de requête
output.audio.url de la réponse réelle. L'URL est valide pendant 24 heures. Ne pas utiliser l'URL fictive ci-dessus pour télécharger l'audio.
Paramètres de la requête
model est un champ de premier niveau. Tous les paramètres de génération appartiennent à l'objet input.
| Champ | Type | Obligatoire | Valeur par défaut | Description |
|---|---|---|---|---|
| model | string | Oui | — | ID du modèle. Voir Modèles pris en charge. |
| input | object | Oui | — | Entrée de génération audio. |
| input.text_prompt | string | Oui | — | Description audio ou texte à synthétiser. Utiliser @voice1, @voice2 et @voice3 pour référencer les clips audio dans l'ordre. Les limites de longueur sont indiquées dans le tableau des modèles. |
| input.references | array | Non | — | Clips audio de référence. À omettre pour la génération texte uniquement. Le modèle actuel accepte jusqu'à 3 clips, chacun ne dépassant pas 30 secondes et 10 Mo. |
| input.references[].audio_url | string | Conditionnel | — | URL audio publique accessible au service. Fournir soit ce champ, soit audio_data, mais pas les deux. |
| input.references[].audio_data | string | Conditionnel | — | URI des données audio : data:{mime_type};base64,{base64_encoded_data}. Mutuellement exclusif avec audio_url. |
| input.format | string | Non | wav | Format de sortie : wav, mp3 ou pcm. La sortie Opus n'est pas prise en charge. |
| input.sample_rate | integer | Non | 48000 | Fréquence d'échantillonnage de sortie en Hz : 8000, 16000, 24000, 44100 ou 48000. |
| input.channels | integer | Non | 2 | Nombre de canaux : 1 (mono) ou 2 (stéréo). |
| input.volume | integer | Non | 50 | Volume. Plage : [0, 100]. |
| input.enable_cbr | boolean | Non | false | MP3 uniquement. true active le débit binaire constant (CBR) ; false utilise le débit binaire variable (VBR). |
| input.bit_rate | integer | Non | 128 | CBR MP3 uniquement, en kbps. La sortie réelle dépend de la fréquence d'échantillonnage et des niveaux de débit MP3 pris en charge. Voir ci-dessous. |
| input.quality | integer | Non | 5 | VBR MP3 uniquement. Plage : [0, 9], où 0 correspond à la qualité la plus élevée. |
| input.rate | float | Non | 1.0 | Vitesse de parole. Plage : [0.5, 2.0]. |
| input.seed | integer | Non | 42 | Graine aléatoire au niveau de la requête. |
| input.enable_aigc_tag | boolean | Non | false | Indique s'il faut ajouter un filigrane d'identification AIGC à l'audio généré. |
Débit CBR MP3
| Fréquence d'échantillonnage (Hz) | Débit de sortie minimum (kbps) | Débit de sortie maximum (kbps) |
|---|---|---|
| 8000 | 8 | 64 |
| 16000, 24000 | 8 | 160 |
| 44100, 48000 | 32 | 320 |
Soumettre un audio de référence
Cet exemple Python utilise deux clips audio de référence pour générer une conversation à deux locuteurs. Installer requests, préparer reference1.wav et reference2.wav, chacun contenant un locuteur différent et respectant les limites du modèle, puis définir les variables d'environnement décrites ci-dessus.
Les emplacements suivent l'ordre de la liste references : le premier élément, reference1.wav, correspond à @voice1 ; le deuxième élément, reference2.wav, correspond à @voice2. L'exemple encode chaque clip en Base64 et référence les deux locuteurs dans le prompt.
{"audio_url": "publicly accessible audio URL"} et omettre audio_data. Les numéros de référence suivent l'ordre de la liste et doivent pointer vers des éléments existants.
Paramètres de la réponse
| Champ | Type | Description |
|---|---|---|
| request_id | string | ID de requête pour le dépannage. |
| output.finish_reason | string | "stop" lors d'une terminaison normale. |
| output.audio.data | string | Une chaîne vide pour ce mode de requête. Télécharger l'audio complet depuis output.audio.url. |
| output.audio.url | string | URL de téléchargement de l'audio complet, valide pendant 24 heures. |
| output.audio.id | string | ID de l'audio généré. |
| output.audio.expires_at | integer | Horodatage d'expiration de l'URL de téléchargement. |
| output.audio.duration | float | Durée de l'audio généré en secondes. |
| usage.duration | integer | Durée de l'audio généré arrondie à la seconde entière la plus proche. Ce champ n'est pas utilisé pour calculer les frais de tokens. |
Modèles pris en charge
| ID du modèle | Limite du prompt | Durée maximale générée par requête |
|---|---|---|
| qwen-audio-3.1-tts-next | 3,000 caractères | Podcasts : 240 secondes (4 minutes) ; autres scénarios : 120 secondes |
Gestion des erreurs
Exemple de réponse d'erreur :
| Statut HTTP | code | Action |
|---|---|---|
| 400 | CLIENT_ERROR | Vérifier la longueur du prompt, le nombre et la durée des références, l'exclusivité URL/Base64, les indices de référence et l'utilisation du champ voice non pris en charge. |
| 404 | InvalidParameter | Pour « Model not exist. », vérifier l'ID du modèle, la région et la disponibilité du modèle pour votre compte. |
| 401 | InvalidApiKey | Vérifier la validité de la clé API. |
| 403 | AccessDenied | Vérifier les permissions d'accès au modèle. |
| 429 | Throttling.RateQuota | Réduire le taux de requêtes. |
| 400 | DataInspectionFailed | Vérifier si le prompt ou l'audio de référence respecte les exigences de sécurité du contenu. |
| 500 | InternalError | Conserver le request_id et réessayer ultérieurement ou contacter le support technique. |