> ## Documentation Index > Fetch the complete documentation index at: https://docs.jiekou.ai/llms.txt > Use this file to discover all available pages before exploring further. # MiniMax Speech Les paramètres et le mode d'utilisation sont alignés sur la version officielle ; pour les paramètres détaillés, reportez-vous directement à la documentation officielle. ## I. Vue d'ensemble Ce document explique comment utiliser la synthèse vocale synchrone, la synthèse vocale asynchrone de textes longs, la gestion de fichiers, le clonage rapide de voix et la conception de voix via le protocole d'origine MiniMax Speech. L'interface synchrone renvoie directement l'audio ou un flux SSE dans une requête POST ; l'interface asynchrone renvoie d'abord un task\_id, puis l'appelant interroge l'état de la tâche et récupère le fichier de résultat via file\_id. ### 1.1 Adresse de l'interface | Capacité | Méthode et chemin | | - | - | | Synthèse vocale synchrone | POST /v3/minimax/v1/t2a\_v2 | | Créer une tâche vocale asynchrone | POST /v3/minimax/v1/t2a\_async\_v2 | | Interroger une tâche vocale asynchrone | GET /v3/minimax/v1/query/t2a\_async\_query\_v2?task\_id={task_id} | | Téléverser un fichier | POST /v3/minimax/v1/files/upload | | Interroger un fichier | GET /v3/minimax/v1/files/retrieve?file\_id={file_id} | | Télécharger un fichier | GET /v3/minimax/v1/files/retrieve\_content?file\_id={file_id} | | Clonage rapide de voix | POST /v3/minimax/v1/voice\_clone | | Conception de voix | POST /v3/minimax/v1/voice\_design | L'adresse complète correspond à https\://\{api\_domain} suivi du chemin indiqué dans le tableau, où \{api\_domain} est le domaine API que vous utilisez. ### 1.2 Authentification Toutes les requêtes nécessitent une clé API de la plateforme. Les requêtes POST JSON doivent également spécifier le type de contenu : ``` Authorization: Bearer Content-Type: application/json ``` Le téléversement de fichiers utilise multipart/form-data ; les requêtes GET ne nécessitent pas de Content-Type. ### 1.3 Réponses et accès aux ressources L'interface conserve les champs de réponse et la structure d'erreur d'origine de MiniMax. Les réponses JSON contiennent généralement base\_resp.status\_code et base\_resp.status\_msg ; un HTTP 200 ne signifie pas nécessairement un succès métier, vérifiez toujours base\_resp.status\_code=0. task\_id et file\_id peuvent dépasser la plage des entiers sûrs de JavaScript ; enregistrez-les sous forme d'entiers sans perte ou de chaînes de caractères. Les fichiers, les tâches et les voix privées ne sont accessibles qu'à l'utilisateur de la plateforme qui les a créés ; lors de l'interrogation, utilisez la même clé API de plateforme que celle utilisée lors de la création des ressources. ## II. Synthèse vocale synchrone Documentation officielle des paramètres : [Synthèse vocale synchrone HTTP](https://platform.minimaxi.com/docs/api-reference/speech-t2a-http) ### 2.1 Appeler l'interface ``` POST https://{api_domain}/v3/minimax/v1/t2a_v2 ``` Champs de requête courants : | Champ | Type | Obligatoire | Description | | - | - | - | - | | model | string | Oui | speech-2.8-hd ou speech-2.8-turbo | | text | string | Oui | Texte à synthétiser, moins de 10 000 caractères ; au-delà de 3 000 caractères, une sortie en streaming est recommandée | | stream | boolean | Non | Indique si un flux SSE d'origine doit être renvoyé ; par défaut false | | voice\_setting | object | Oui | Réglages de l'ID de voix, de la vitesse, du volume, de la hauteur et de l'émotion, etc. | | audio\_setting | object | Non | Réglages de la fréquence d'échantillonnage, du débit, du format et des canaux | | language\_boost | string | Non | Langue spécifiée ou auto | | output\_format | string | Non | hex (par défaut) ou url ; le streaming ne prend en charge que hex, la validité de l'URL est de 24 heures | | subtitle\_enable | boolean | Non | Indique si les sous-titres doivent être renvoyés ; par défaut false | Les champs d'extension d'origine tels que pronunciation\_dict, timbre\_weights, voice\_modify, stream\_options, etc. sont transmis tels quels ; pour les contraintes détaillées, reportez-vous à la documentation officielle MiniMax. ### 2.2 Exemple d'appel ```bash theme={null} curl -X POST 'https://{api_domain}/v3/minimax/v1/t2a_v2' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "model": "speech-2.8-hd", "text": "Welcome to our service.", "stream": false, "voice_setting": { "voice_id": "male-qn-qingse", "speed": 1, "vol": 1, "pitch": 0 }, "audio_setting": { "sample_rate": 32000, "bitrate": 128000, "format": "mp3", "channel": 1 }, "output_format": "url" }' ``` Pour un appel en streaming, il suffit de définir stream=true et d'utiliser un client prenant en charge la lecture en streaming, par exemple curl -N. ### 2.3 Description de la réponse ```json theme={null} { "data": { "audio": "https://example.com/audio.mp3", "status": 2 }, "extra_info": { "usage_characters": 26, "audio_length": 9900, "audio_format": "mp3" }, "trace_id": "provider-trace-id", "base_resp": { "status_code": 0, "status_msg": "success" } } ``` La réponse en streaming est un flux SSE d'origine. Dans l'événement de succès final, data.status vaut 2 et l'utilisation se trouve dans extra\_info.usage\_characters. ### 2.4 Facturation La facturation est basée sur extra\_info.usage\_characters finalement renvoyé par le fournisseur amont, avec une unité de facturation par 10 000 caractères. Les requêtes échouées, les erreurs métier d'origine et les flux SSE sans événement de terminaison réussi ne sont pas facturés. Le prix unitaire exact dépend de la page tarifaire du service que vous utilisez. ## III. Synthèse vocale asynchrone de textes longs Documentation officielle des paramètres : [Créer une tâche asynchrone](https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-create), [Interroger une tâche asynchrone](https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-query) ### 3.1 Créer une tâche ``` POST https://{api_domain}/v3/minimax/v1/t2a_async_v2 ``` | Champ | Type | Obligatoire | Description | | - | - | - | - | | model | string | Oui | speech-2.8-hd ou speech-2.8-turbo | | text | string | Choix exclusif | Texte à synthétiser, jusqu'à 50 000 caractères ; choix exclusif avec text\_file\_id | | text\_file\_id | integer | Choix exclusif | Obtenu via le téléversement de fichier ; prend en charge txt ou zip, le texte d'un fichier individuel doit contenir moins de 1 000 000 de caractères | | voice\_setting | object | Oui | Paramètres de voix et de synthèse vocale | | audio\_setting | object | Non | Réglages de l'audio de sortie | | language\_boost | string | Non | Langue spécifiée ou auto | ### 3.2 Exemple de création ```bash theme={null} curl -X POST 'https://{api_domain}/v3/minimax/v1/t2a_async_v2' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "model": "speech-2.8-turbo", "text": "A longer narration.", "voice_setting": { "voice_id": "audiobook_male_1", "speed": 1, "vol": 1, "pitch": 0 } }' ``` ```json theme={null} { "task_id": 95157322514444, "task_token": "provider-task-token", "file_id": 95157322514444, "usage_characters": 101, "base_resp": { "status_code": 0, "status_msg": "success" } } ``` Veuillez conserver le task\_id. La facturation intervient dès la création réussie de la tâche asynchrone, selon le usage\_characters de la réponse ; les interrogations ultérieures ne sont pas facturées à nouveau. ### 3.3 Interroger une tâche ```bash theme={null} curl -X GET 'https://{api_domain}/v3/minimax/v1/query/t2a_async_query_v2?task_id=95157322514444' \ -H 'Authorization: Bearer ' ``` Cette interface d'interrogation peut être appelée au maximum 10 fois par seconde. Les états incluent Processing, Success, Failed et Expired ; arrêtez l'interrogation répétée une fois l'état final atteint. ```json theme={null} { "task_id": 95157322514444, "status": "Success", "file_id": 95157322514496, "base_resp": { "status_code": 0, "status_msg": "success" } } ``` Une fois la tâche réussie, utilisez file\_id pour interroger ou télécharger le fichier. Selon la documentation officielle MiniMax, l'URL de téléchargement est valide environ 9 heures à compter de sa génération ; enregistrez le résultat en temps utile. ## IV. Gestion des fichiers Documentation officielle des paramètres : [Téléversement de fichier](https://platform.minimaxi.com/docs/api-reference/file-management-upload), [Récupération de fichier](https://platform.minimaxi.com/docs/api-reference/file-management-retrieve), [Téléchargement de fichier](https://platform.minimaxi.com/docs/api-reference/file-management-retrieve-content) ### 4.1 Téléverser un fichier ```bash theme={null} curl -X POST 'https://{api_domain}/v3/minimax/v1/files/upload' \ -H 'Authorization: Bearer ' \ -F 'purpose=voice_clone' \ -F 'file=@voice.wav' ``` | purpose | Utilisation et format | | - | - | | voice\_clone | Audio original pour clonage rapide ; mp3, m4a, wav | | prompt\_audio | Audio d'exemple pour le clonage de voix ; mp3, m4a, wav | | t2a\_async\_input | Entrée de texte long asynchrone ; txt, zip | La requête doit contenir obligatoirement et uniquement un purpose et un fichier. La taille maximale du corps d'une requête de plateforme est de 64 MiB ; les limites de format, de durée et de taille de MiniMax pour chaque utilisation s'appliquent toujours. ### 4.2 Interrogation et téléchargement ```bash theme={null} curl -X GET 'https://{api_domain}/v3/minimax/v1/files/retrieve?file_id=95157322514496' \ -H 'Authorization: Bearer ' curl -X GET 'https://{api_domain}/v3/minimax/v1/files/retrieve_content?file_id=95157322514496' \ -H 'Authorization: Bearer ' \ --output result.mp3 ``` retrieve renvoie les métadonnées du fichier et download\_url ; retrieve\_content renvoie directement le fichier binaire. Le téléversement, l'interrogation et le téléchargement ne sont pas facturés. ## V. Clonage rapide de voix Documentation officielle des paramètres : [Clonage rapide de voix](https://platform.minimaxi.com/docs/api-reference/voice-cloning-clone) ### 5.1 Appeler l'interface et champs ``` POST https://{api_domain}/v3/minimax/v1/voice_clone ``` | Champ | Type | Obligatoire | Description | | - | - | - | - | | file\_id | integer | Oui | ID de fichier obtenu via un téléversement avec purpose=voice\_clone ; audio de 10 secondes à 5 minutes et ne dépassant pas 20 MB | | voice\_id | string | Oui | ID de voix personnalisé, longueur 8–256, commençant par une lettre, ne doit pas être dupliqué avec un ID existant | | clone\_prompt | object | Non | Audio d'exemple ; lors de l'utilisation, prompt\_audio et prompt\_text sont tous deux obligatoires | | text | string | Non | Texte d'essai, jusqu'à 1 000 caractères | | model | string | Conditionnellement obligatoire | Obligatoire lors du passage de text ; utilisez speech-2.8-hd ou speech-2.8-turbo | | text\_validation | string | Non | Texte attendu de l'échantillon, jusqu'à 200 caractères | | accuracy | number | Non | Seuil de similarité ASR, 0–1, par défaut 0.7 | ### 5.2 Exemple d'appel et réponse ```bash theme={null} curl -X POST 'https://{api_domain}/v3/minimax/v1/voice_clone' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "file_id": 123456789, "voice_id": "MyVoice001", "need_noise_reduction": false, "need_volume_normalization": false }' ``` ```json theme={null} { "input_sensitive": false, "demo_audio": "", "base_resp": { "status_code": 0, "status_msg": "success" } } ``` Une requête réussie est facturée comme une voix. Si un audio d'essai est généré dans la requête, la plateforme n'ajoute pas de SKU de synthèse vocale supplémentaire. Selon la documentation officielle MiniMax, une voix clonée qui n'a pas été officiellement utilisée pour la synthèse vocale dans les 7 jours peut être supprimée. ## VI. Conception de voix Documentation officielle des paramètres : [Conception de voix](https://platform.minimaxi.com/docs/api-reference/voice-design-design) ### 6.1 Appeler l'interface et champs ``` POST https://{api_domain}/v3/minimax/v1/voice_design ``` | Champ | Type | Obligatoire | Description | | - | - | - | - | | prompt | string | Oui | Description de la voix cible | | preview\_text | string | Oui | Texte d'essai, jusqu'à 500 caractères | | voice\_id | string | Non | ID de voix personnalisé ; s'il n'est pas fourni, il est généré par MiniMax | | aigc\_watermark | boolean | Non | Indique si un marqueur rythmique doit être ajouté à la fin de l'audio d'essai ; par défaut false | ### 6.2 Exemple d'appel et réponse ```bash theme={null} curl -X POST 'https://{api_domain}/v3/minimax/v1/voice_design' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A warm, clear adult narrator with a calm delivery.", "preview_text": "Welcome to our service." }' ``` ```json theme={null} { "voice_id": "ttv-voice-generated-id", "trial_audio": "hex-encoded-audio", "base_resp": { "status_code": 0, "status_msg": "success" } } ``` Une requête réussie est facturée comme une voix ; l'audio d'essai est inclus dans la facturation de cette interface et n'ajoute pas de SKU de synthèse vocale supplémentaire. ## VII. Erreurs courantes et points d'attention | Symptôme | Description et suggestion de traitement | | - | - | | HTTP 200, mais base\_resp.status\_code!=0 | Erreur métier MiniMax ; corrigez l'entrée selon status\_msg, ne la traitez pas comme un succès | | HTTP 400 | JSON, multipart, nom de modèle, paramètres de requête ou champs obligatoires non valides | | HTTP 401/403 | Vérifiez la clé API de la plateforme, le solde et les autorisations | | HTTP 404 | Le fichier, la tâche ou la voix privée n'existe pas, ou n'appartient pas à l'utilisateur actuel de la plateforme | | HTTP 429 | Réduisez la fréquence des requêtes/interrogations et utilisez un backoff exponentiel ; les interrogations asynchrones ne doivent pas dépasser 10 fois par seconde | | HTTP 5xx | Conservez la réponse et le trace ID de la plateforme, puis contactez le support technique ; ne réessayez pas de manière incontrôlée les requêtes de création non idempotentes | * Les champs d'origine sont transmis autant que possible tels quels, mais ce service n'expose que les huit chemins listés dans ce document. * La taille maximale du corps d'une requête et d'un événement SSE individuel est de 64 MiB. * Après la déconnexion du client, le service peut continuer à lire le flux SSE déjà commencé afin de finaliser le décompte de l'utilisation. * Les tâches asynchrones doivent obtenir leur état via l'interface d'interrogation MiniMax de ce document, et non via l'interface générique de résultats asynchrones de la plateforme. * Téléchargez rapidement le fichier après avoir reçu l'URL du fichier ou un ID de fichier réussi ; l'URL et le fichier peuvent expirer. ## VIII. Exemple d'appel en Python L'exemple suivant illustre la création asynchrone et l'interrogation répétée. En production, définissez un délai d'expiration global, un backoff exponentiel et un nombre maximal d'interrogations. ```python theme={null} import os import time import requests api_domain = os.environ["API_DOMAIN"] api_key = os.environ["PLATFORM_API_KEY"] headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", } created = requests.post( f"https://{api_domain}/v3/minimax/v1/t2a_async_v2", headers=headers, json={ "model": "speech-2.8-turbo", "text": "A longer narration.", "voice_setting": {"voice_id": "audiobook_male_1"}, }, timeout=60, ) created.raise_for_status() created_body = created.json() if created_body["base_resp"]["status_code"] != 0: raise RuntimeError(created_body) task_id = created_body["task_id"] while True: response = requests.get( f"https://{api_domain}/v3/minimax/v1/query/t2a_async_query_v2", headers={"Authorization": f"Bearer {api_key}"}, params={"task_id": task_id}, timeout=30, ) response.raise_for_status() task = response.json() if task["base_resp"]["status_code"] != 0: raise RuntimeError(task) if task["status"] == "Success": print(task["file_id"]) break if task["status"] in {"Failed", "Expired"}: raise RuntimeError(task) time.sleep(2) ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.