API генерации речи (Speech)

Обновлено 2026-09-18 · команда Suno-API

Описание эндпоинта

Speech превращает текст выступления или описание в одну строку в аудио «речи/выступления», при желании с фоновой музыкой. Подходит для выступлений, тостов, закадрового текста, сценариев озвучки, аудиоконтента и похожих задач.

Обратите внимание: этот эндпоинт создаёт речевое аудио, а не спетую песню (нет мелодии и нет вокального исполнения). Если нужно пение, используйте API генерации в простом режиме или API генерации в расширенном режиме.

Эндпоинт: POST /api/music/speech

Оплата: платно, сейчас по умолчанию 0,6 ¥ за вызов. За вызов обычно возвращаются 2 аудио; фактически списанная сумма следует текущей конфигурации цен в бэк-офисе.

Max Mode / Variety: эндпоинт поддерживает необязательные параметры max_mode и variety (0-4). При включённом max_mode этот вызов тарифицируется по двойной цене (0,6 → 1,2 ¥ за вызов); variety не стоит ничего дополнительно. Что они означают и как их отправлять — в разделе «Расширенные параметры» Обзора нового API.

Время ожидания и тайм-ауты (важно): это синхронный эндпоинт — заказ принимается и передаётся в генерацию только при получении ответа. По измерениям большинство запросов отвечают за секунды (1–10 с); но, как и у других синхронных генеративных эндпоинтов, в крайних случаях это может занять больше времени. Установите тайм-аут клиента 300 секунд или больше; отсутствие ответа не означает, что ничего не сгенерировано, и не повторяйте запрос сразу после тайм-аута (это дублирует заказ и списывает деньги повторно). Если соединение оборвалось, проверьте позже через GET /api/music/songs. См. «Время ожидания и настройка тайм-аута» в Обзоре нового API.

Соответствие контенту: платформа проверяет текст на авторские права и политику контента. Если он признан содержащим защищённые материалы (например, цитирование чужих слов песни или дословный текст известного произведения), этот вызов завершается ошибкой и вся сумма возвращается автоматически. Перепишите своими словами или превратите цитату в пересказ и попробуйте снова.

Параметры запроса

Headers

Параметры тела

Этот эндпоинт не поддерживает duration: при передаче возвращается HTTP 400, без тихого игнорирования. Длительность выступления определяется длиной содержимого script.

Примеры запроса

Минимальный запрос (только текст)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Добрый день, коллеги и друзья! Сегодня моё выступление о том, как беречь время и идти вперёд."
  }'

Полный запрос (с тоном, полом и выключенной фоновой музыкой)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Good evening everyone, thank you all for coming to celebrate this special day with us.",
    "tone": "warm and slow, wedding reception",
    "song_title": "Wedding Toast",
    "gender": "f",
    "backing_music": false,
    "model": "suno-v6"
  }'

Пример на Python

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/speech',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'script': 'Добрый день, коллеги. Доложу о прогрессе за эту неделю.',
        'tone': 'ровно и чётко, отчёт на совещании',
        'gender': 'male',
        'backing_music': True,
    },
    timeout=300,
)
response.raise_for_status()
items = response.json()          # обычно 2 записи
for item in items:
    print(item['song_id'], item['status'])

Пояснения к параметрам

script (текст выступления, обязателен)

• Вставьте то, что хотите произнести; можно также написать одно описание и позволить модели составить текст выступления (например «напутствие в перерыве для команды, проигрывающей двадцать очков, от тихого шёпота до крика во всю силу»).
• Переносы строк, абзацы и ремарки вроде [пауза] можно писать прямо в тексте, и модель по возможности их соблюдёт.
• Лимит — 3000 символов (считаются символы Unicode; один иероглиф считается за 1); при превышении возвращается 400 и списания нет.

tone (тон и обстановка, необязательно)

Описывает, как говорить, а не что говорить. Стоит указать четыре вида сведений: тон, темп/ритм, эмоцию, обстановку.

Энергично и мощно, темп от медленного к быстрому, заметные паузы; актовый зал, перед всеми учениками и учителями
Тепло и мягко, спокойный темп; свадебный банкет
Сдержанно и ровно, размеренно и чётко; доклад совету директоров

Лимит — 1000 символов. Если не передавать, модель определит по содержимому script.

gender / vocal_gender (пол говорящего, необязательно)

• Для мужского голоса передайте m или male, для женского f или female; сервер нормализует их до m / f.
• Оба имени поля работают, используйте любое одно: gender — рекомендуемая форма для этого эндпоинта; если вы уже используете расширенный режим, можно продолжать с vocal_gender.
• Если не передавать — «любой», решает модель.

backing_music (фоновая музыка, необязательно)

• По умолчанию true (с фоновой музыкой), как и в веб-версии Suno.
• false даёт выступление только голосом — удобно, если позже вы хотите добавить свою музыку или дубляж.
• Должно быть логическим значением JSON true / false; строки "true" и "1" тоже принимаются, но рекомендуется логический тип.

model (модель, необязательно)

Все три клиентские модели доступны по одинаковой цене (0,6 ¥ за вызов). Речь создаётся семейством Suno v6; без значения обрабатывается как suno-v6. Если у вас нет явного предпочтения, обычно это поле не нужно.

Проверка параметров и лимиты текста

Следующие случаи возвращают HTTP 400, и все они блокируются до списания, поэтому расходов не возникает:

Лимиты текстовых полей

Превышение тоже возвращает HTTP 400 и не запускает генерацию и не списывает предварительно. Подсчёт по символам Unicode (один иероглиф считается за 1), пробелы в начале и в конце тоже учитываются:

Ошибка выглядит так: script must not exceed 3000 characters; received 4120: первое слово — поле, превысившее лимит, а в конце — фактическое количество, поэтому при 400 можно сразу обрезать по этим двум числам.

Ответ

Ответ — массив песен, полностью такой же, как у других генеративных эндпоинтов (обычно 2 записи). Сохраните song_id и через API запроса песен и истории проверьте итоговый статус и адрес аудио:

[
  {
    "song_id": "b7529174-b495-465b-8c5e-cd21bea2df8c",
    "song_title": "Беречь время",
    "status": "pending",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-10-08T01:00:00Z"
  }
]

Ошибка генерации и возврат средств

Если генерация не удалась, стоимость вызова автоматически возвращается полностью; обращаться в поддержку не нужно. Причина видна в ответе или в error_message API запроса песен и истории.

Самая частая причина — признание контента содержащим защищённые материалы, например:

Your lyrics contain copyrighted material. Please change it and try again.

В этом случае замените текст своими формулировками (или превратите цитату в пересказ) и отправьте снова.

Частые вопросы

В: Почему получается «речь», а не пение? О: Это эндпоинт выступлений, и его выход — речевое аудио. Для пения используйте генеративные эндпоинты или расширенный режим.

В: Почему каждый раз возвращается 2 записи? О: Как и у других генеративных эндпоинтов платформы, одна генерация даёт 2 варианта; запрашивайте их отдельно по song_id и оставьте подходящий.

В: Как управлять длительностью? О: Она определяется длиной script; этот эндпоинт не принимает параметр duration.

В: Можно ли указать голос (например мой клонированный)? О: Текущая версия не поддерживает. Речь использует фиксированный набор голосов, а gender выбирает мужской или женский; если нужен свой голос, используйте соответствующую возможность API создания профиля голоса (рекомендуется).

В: Что будет, если не передать tone? О: Модель определит тон и ритм по содержимому script. Чтобы стабильно воспроизводить стиль, опишите тон, темп и обстановку в tone.

Совместимые поля

В новых интеграциях используйте snake_case единообразно. У остальных полей (script, tone, song_title, backing_music) нет camelCase-алиасов.

Дальнейшие шаги

Получив song_id:

1. Проверьте статус генерации и адрес аудио через API запроса песен и истории;
2. После завершения скачайте или прослушайте через API скачивания и прослушивания медиа песен;
3. Для пакетной загрузки или переноса в своё хранилище см. эндпоинты центра загрузок.