Alibaba Cloud Model Studio:Référence de l'API de génération audio

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. Les définir comme variables d'environnement DASHSCOPE_API_KEY et SFM_WORKSPACE_ID.

Envoyer des requêtes HTTPS POST au point de terminaison suivant. Remplacer {WorkspaceId} par votre ID d'espace de travail.

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer

En-têtes

En-tête	Obligatoire	Description
Authorization	Oui	Bearer <API Key>
Content-Type	Oui	application/json

Exemple de requête

curl --request POST \
  "https://$SFM_WORKSPACE_ID.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer" \
  --max-time 300 \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "qwen-audio-3.1-tts-next",
    "input": {
      "text_prompt": "A woman clearly says: Hello, welcome.",
      "format": "wav",
      "sample_rate": 48000,
      "channels": 2
    }
  }'

Exemple de réponse, avec des ID illustratifs et une URL de téléchargement fictive :

{
  "request_id": "example-request-id",
  "output": {
    "finish_reason": "stop",
    "audio": {
      "data": "",
      "url": "https://example.com/generated.wav",
      "id": "audio_example-request-id",
      "expires_at": 1789616932,
      "duration": 1.12
    }
  },
  "usage": {
    "duration": 1
  }
}

Télécharger le fichier en utilisant 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é.

L'audio de référence prend en charge WAV, MP3 et OGG Opus, mais pas le PCM brut. Les formats de référence et de sortie ont des limites différentes : OGG Opus peut être utilisé en entrée, mais Opus ne peut pas être utilisé en sortie.

Soumettre l'audio de référence via une URL ou des données Base64, et non via un ID de voix système ou clonée.

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

La fréquence d'échantillonnage et les niveaux de débit MP3 déterminent le débit de sortie. Le tableau indique les limites de sortie, et non la prise en charge de chaque entier dans chaque plage. Les valeurs hors plage sont contraintes aux limites correspondantes.

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.

import base64
import os
from pathlib import Path

import requests

reference1 = base64.b64encode(Path("reference1.wav").read_bytes()).decode("ascii")
reference2 = base64.b64encode(Path("reference2.wav").read_bytes()).decode("ascii")
workspace_id = os.environ["SFM_WORKSPACE_ID"]
endpoint = (
    f"https://{workspace_id}.cn-beijing.maas.aliyuncs.com"
    "/api/v1/services/audio/tts/SpeechSynthesizer"
)
response = requests.post(
    endpoint,
    headers={
        "Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "qwen-audio-3.1-tts-next",
        "input": {
            "text_prompt": "@voice1 says: It is sunny today. Shall we take a walk? @voice2 replies: Sure, let us go to the park.",
            "references": [
                {"audio_data": f"data:audio/wav;base64,{reference1}"},
                {"audio_data": f"data:audio/wav;base64,{reference2}"}
            ],
            "format": "wav",
        },
    },
    timeout=300,
)
response.raise_for_status()
result = response.json()
audio_response = requests.get(result["output"]["audio"]["url"], timeout=60)
audio_response.raise_for_status()
Path("output.wav").write_bytes(audio_response.content)

Pour utiliser une URL, remplacer l'élément de liste par {"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.

Les requêtes de podcast peuvent générer jusqu'à 240 secondes (4 minutes) d'audio ; les autres scénarios sont limités à 120 secondes par requête. Pour les tarifs, voir Tarification des modèles.

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

Pour les cas d'utilisation, les exemples audio et les conseils sur les prompts, voir Génération audio. Les exemples de ce document utilisent ce modèle.

Gestion des erreurs

Exemple de réponse d'erreur :

{
  "request_id": "example-request-id",
  "code": "CLIENT_ERROR",
  "message": "text_prompt exceeds the maximum length of 3000 characters."
}

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.