> ## 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 Параметры и способы использования соответствуют официальным; подробные параметры см. в официальной документации. ## I. Обзор В этом документе описано использование синхронного синтеза речи, асинхронного синтеза длинного текста, управления файлами, быстрого клонирования голоса и дизайна голоса по исходному протоколу MiniMax Speech. Синхронный API в одном POST-запросе напрямую возвращает аудио или SSE; асинхронный API сначала возвращает task\_id, затем вызывающая сторона запрашивает статус задачи и получает итоговый файл по file\_id. ### 1.1 Адреса API | Возможность | Метод и путь | | - | - | | Синхронный синтез речи | POST /v3/minimax/v1/t2a\_v2 | | Создание асинхронной задачи синтеза речи | POST /v3/minimax/v1/t2a\_async\_v2 | | Запрос асинхронной задачи синтеза речи | GET /v3/minimax/v1/query/t2a\_async\_query\_v2?task\_id={task_id} | | Загрузка файла | POST /v3/minimax/v1/files/upload | | Запрос файла | GET /v3/minimax/v1/files/retrieve?file\_id={file_id} | | Скачивание файла | GET /v3/minimax/v1/files/retrieve\_content?file\_id={file_id} | | Быстрое клонирование голоса | POST /v3/minimax/v1/voice\_clone | | Дизайн голоса | POST /v3/minimax/v1/voice\_design | Полный адрес — https\://\{api\_domain} плюс путь из таблицы, где \{api\_domain} — используемый вами домен API. ### 1.2 Аутентификация Все запросы требуют API-ключ платформы. Для JSON POST-запросов также необходимо указать тип содержимого: ``` Authorization: Bearer Content-Type: application/json ``` Загрузка файлов использует multipart/form-data; для GET-запросов Content-Type не требуется. ### 1.3 Ответы и доступ к ресурсам API сохраняет исходные поля ответа и структуру ошибок MiniMax. JSON-ответ обычно содержит base\_resp.status\_code и base\_resp.status\_msg; HTTP 200 не обязательно означает успех бизнес-операции, всегда проверяйте base\_resp.status\_code=0. task\_id и file\_id могут выходить за диапазон безопасных целых чисел JavaScript; сохраняйте их как целые числа без потери точности или как строки. Доступ к файлам, задачам и приватным голосам имеют только пользователи платформы, создавшие их; при запросе используйте тот же API-ключ платформы, что и при создании ресурса. ## II. Синхронный синтез речи Официальное описание параметров: [Синхронный синтез речи HTTP](https://platform.minimaxi.com/docs/api-reference/speech-t2a-http) ### 2.1 Вызов API ``` POST https://{api_domain}/v3/minimax/v1/t2a_v2 ``` Основные поля запроса: | Поле | Тип | Обязательно | Описание | | - | - | - | - | | model | string | Да | speech-2.8-hd или speech-2.8-turbo | | text | string | Да | Синтезируемый текст, менее 10 000 символов; при превышении 3 000 символов рекомендуется потоковый вывод | | stream | boolean | Нет | Возвращать ли исходный SSE, по умолчанию false | | voice\_setting | object | Да | Настройки ID голоса, скорости, громкости, тональности и эмоций и т. п. | | audio\_setting | object | Нет | Настройки частоты дискретизации, битрейта, формата и каналов | | language\_boost | string | Нет | Указать язык или auto | | output\_format | string | Нет | hex (по умолчанию) или url; при потоковой передаче поддерживается только hex; URL действителен 24 часа | | subtitle\_enable | boolean | Нет | Возвращать ли субтитры, по умолчанию false | Расширенные поля производителя, такие как pronunciation\_dict, timbre\_weights, voice\_modify, stream\_options, передаются как есть; подробные ограничения см. в официальной документации MiniMax. ### 2.2 Пример вызова ```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" }' ``` Для потокового вызова достаточно установить stream=true и использовать клиент с поддержкой потокового чтения, например curl -N. ### 2.3 Описание ответа ```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" } } ``` Потоковый ответ — исходный SSE. У финального успешного события data.status равен 2, использование указано в extra\_info.usage\_characters. ### 2.4 Тарификация Биллинг выполняется по extra\_info.usage\_characters, окончательно возвращённому вышестоящим провайдером; единица тарификации — каждые 10 000 символов. Неудачные запросы, бизнес-ошибки провайдера и SSE без успешного завершающего события не оплачиваются. Конкретная цена указана на странице тарифов используемого вами сервиса. ## III. Асинхронный синтез длинного текста Официальное описание параметров: [Создание асинхронной задачи](https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-create), [Запрос асинхронной задачи](https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-query) ### 3.1 Создание задачи ``` POST https://{api_domain}/v3/minimax/v1/t2a_async_v2 ``` | Поле | Тип | Обязательно | Описание | | - | - | - | - | | model | string | Да | speech-2.8-hd или speech-2.8-turbo | | text | string | Одно из двух | Синтезируемый текст, до 50 000 символов; взаимоисключающее с text\_file\_id | | text\_file\_id | integer | Одно из двух | Полученный через загрузку файла; поддерживаются txt или zip, текст одного файла менее 1 000 000 символов | | voice\_setting | object | Да | Настройки голоса и параметров речи | | audio\_setting | object | Нет | Настройки выходного аудио | | language\_boost | string | Нет | Указать язык или auto | ### 3.2 Пример создания ```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" } } ``` Сохраните task\_id. Асинхронная задача тарифицируется сразу при успешном создании по usage\_characters из ответа; последующие запросы не тарифицируются повторно. ### 3.3 Запрос задачи ```bash theme={null} curl -X GET 'https://{api_domain}/v3/minimax/v1/query/t2a_async_query_v2?task_id=95157322514444' \ -H 'Authorization: Bearer ' ``` Этот API запроса можно вызывать не более 10 раз в секунду. Статусы: Processing, Success, Failed и Expired; после достижения терминального статуса прекратите опрос. ```json theme={null} { "task_id": 95157322514444, "status": "Success", "file_id": 95157322514496, "base_resp": { "status_code": 0, "status_msg": "success" } } ``` После успешного завершения задачи используйте file\_id для запроса или скачивания файла. В официальной документации MiniMax указано, что URL для скачивания действителен около 9 часов с момента создания; своевременно сохраните результат. ## IV. Управление файлами Официальное описание параметров: [Загрузка файла](https://platform.minimaxi.com/docs/api-reference/file-management-upload), [Запрос файла](https://platform.minimaxi.com/docs/api-reference/file-management-retrieve), [Скачивание файла](https://platform.minimaxi.com/docs/api-reference/file-management-retrieve-content) ### 4.1 Загрузка файла ```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 | Назначение и формат | | - | - | | voice\_clone | Быстрое клонирование исходного аудио; mp3, m4a, wav | | prompt\_audio | Пример аудио для клонирования голоса; mp3, m4a, wav | | t2a\_async\_input | Входной длинный текст для асинхронного синтеза; txt, zip | Запрос должен содержать ровно один purpose и один файл. Максимальный размер тела одного запроса к платформе — 64 MiB; ограничения MiniMax по формату, длительности и размеру для каждого purpose по-прежнему действуют. ### 4.2 Запрос и скачивание ```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 возвращает метаданные файла и download\_url; retrieve\_content напрямую возвращает двоичный файл. Загрузка, запрос и скачивание не тарифицируются. ## V. Быстрое клонирование голоса Официальное описание параметров: [Быстрое клонирование голоса](https://platform.minimaxi.com/docs/api-reference/voice-cloning-clone) ### 5.1 Вызов API и поля ``` POST https://{api_domain}/v3/minimax/v1/voice_clone ``` | Поле | Тип | Обязательно | Описание | | - | - | - | - | | file\_id | integer | Да | ID файла, полученный при загрузке с purpose=voice\_clone; аудио от 10 секунд до 5 минут и не более 20 MB | | voice\_id | string | Да | Пользовательский ID голоса, длина 8–256, начинается с буквы, не должен совпадать с существующим ID | | clone\_prompt | object | Нет | Пример аудио; при использовании prompt\_audio и prompt\_text обязательны | | text | string | Нет | Текст для прослушивания, максимум 1 000 символов | | model | string | Условно обязательно | Обязательно при передаче text; используйте speech-2.8-hd или speech-2.8-turbo | | text\_validation | string | Нет | Ожидаемый текст образца, максимум 200 символов | | accuracy | number | Нет | Порог сходства ASR, 0–1, по умолчанию 0.7 | ### 5.2 Пример вызова и ответ ```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" } } ``` Успешный запрос тарифицируется как один голос. Если в запросе создаётся пробное аудио, платформа не добавляет отдельный SKU синтеза речи. В официальной документации MiniMax указано, что клонированный голос может быть удалён, если в течение 7 дней он не был официально использован для синтеза речи. ## VI. Дизайн голоса Официальное описание параметров: [Дизайн голоса](https://platform.minimaxi.com/docs/api-reference/voice-design-design) ### 6.1 Вызов API и поля ``` POST https://{api_domain}/v3/minimax/v1/voice_design ``` | Поле | Тип | Обязательно | Описание | | - | - | - | - | | prompt | string | Да | Описание целевого голоса | | preview\_text | string | Да | Текст для прослушивания, максимум 500 символов | | voice\_id | string | Нет | Пользовательский ID голоса; если не передан, MiniMax сгенерирует его | | aigc\_watermark | boolean | Нет | Добавлять ли ритмическую метку в конец пробного аудио, по умолчанию false | ### 6.2 Пример вызова и ответ ```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" } } ``` Успешный запрос тарифицируется как один голос; пробное аудио включено в тарификацию данного API и не добавляет отдельный SKU синтеза речи. ## VII. Частые ошибки и примечания | Симптом | Описание и рекомендации | | - | - | | HTTP 200, но base\_resp.status\_code!=0 | Бизнес-ошибка MiniMax; исправьте входные данные согласно status\_msg, не считайте запрос успешным | | HTTP 400 | Некорректные JSON, multipart, имя модели, параметры запроса или обязательные поля | | HTTP 401/403 | Проверьте API-ключ платформы, баланс и права доступа | | HTTP 404 | Файл, задача или приватный голос не существует либо не принадлежит текущему пользователю платформы | | HTTP 429 | Снизьте частоту запросов/опросов и используйте экспоненциальную задержку; асинхронные запросы — не более 10 раз в секунду | | HTTP 5xx | Сохраните ответ и trace ID платформы, затем обратитесь в техподдержку; не повторяйте неидемпотентные запросы создания без контроля | * Поля производителя по возможности передаются как есть, но этот сервис предоставляет только восемь путей, перечисленных в этой статье. * Максимальный размер тела одного запроса и одного SSE-события — 64 MiB. * После отключения клиента сервис может продолжить чтение уже начатого SSE для завершения расчёта использования. * Статус асинхронной задачи необходимо получать через API запроса MiniMax из этой статьи, а не через общий API асинхронных результатов платформы. * Своевременно скачивайте файл после получения URL файла или ID успешного файла; URL и файлы могут устареть. ## VIII. Пример вызова на Python Следующий пример демонстрирует асинхронное создание и опрос. В производственной среде задайте общий тайм-аут, экспоненциальную задержку и максимальное число попыток опроса. ```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.