API generowania mowy (Speech)

Zaktualizowano 2026-09-18 · zespół Suno-API

Opis punktu końcowego

Speech zamienia tekst wystąpienia lub jednozdaniowy opis w audio „mowy/wystąpienia”, opcjonalnie z muzyką w tle. Nadaje się do wystąpień, toastów, narracji, tekstów lektorskich, treści audio i podobnych zastosowań.

Uwaga: ten punkt końcowy tworzy audio mowy, a nie śpiewany utwór (bez melodii i bez śpiewanego wokalu). Jeśli potrzebujesz śpiewu, użyj API generowania w trybie prostym lub API generowania w trybie niestandardowym.

Punkt końcowy: POST /api/music/speech

Rozliczenie: Płatne, obecnie domyślnie 0,6 juana za wywołanie. Jedno wywołanie zwykle zwraca 2 pliki audio; faktycznie pobierana kwota zależy od konfiguracji cen w panelu administracyjnym.

Max Mode / Variety: ten punkt końcowy obsługuje opcjonalne parametry max_mode i variety (0-4). Przy włączonym max_mode to wywołanie jest rozliczane po podwójnej cenie (0,6 → 1,2 ¥ za wywołanie); variety nie kosztuje nic dodatkowo. Znaczenie i sposób wysyłania opisano w sekcji „Parametry zaawansowane” Przeglądu nowego API.

Czasy oczekiwania i limity czasu (ważne): to punkt końcowy synchroniczny — zamówienie zostaje przyjęte i przekazane do generowania dopiero, gdy przyjdzie odpowiedź. Z pomiarów wynika, że większość żądań odpowiada w kilka sekund (1-10 s); ale jak przy innych synchronicznych punktach końcowych generowania, w skrajnych przypadkach może to potrwać dłużej. Ustaw limit czasu klienta na 300 sekund lub więcej; brak odpowiedzi nie oznacza, że nic nie zostało wygenerowane, a ponawianie od razu po limicie czasu duplikuje zamówienie i pobiera opłatę ponownie. Jeśli połączenie się zerwało, sprawdź później przez GET /api/music/songs. Zobacz „Czasy oczekiwania i ustawienia limitu czasu” w Przeglądzie nowego API.

Zgodność treści: platforma sprawdza tekst pod kątem praw autorskich i polityki treści. Jeśli zostanie uznany za materiał chroniony (na przykład cytowanie cudzego tekstu piosenki albo dosłownego tekstu znanego utworu), to wywołanie kończy się niepowodzeniem, a cała kwota jest automatycznie zwracana. Zmień tekst na własne sformułowanie albo zamień cytat na parafrazę i spróbuj ponownie.

Parametry żądania

Headers

Parametry treści

Ten punkt końcowy nie obsługuje duration: przekazanie go zwraca HTTP 400, nie jest po cichu ignorowane. Długość wystąpienia zależy od długości treści script.

Przykładowe żądania

Żądanie minimalne (tylko tekst)

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": "Dzień dobry wszystkim! Dziś moje wystąpienie dotyczy tego, jak dobrze wykorzystywać czas i iść naprzód."
  }'

Pełne żądanie (z tonem, płcią i wyłączoną muzyką w tle)

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"
  }'

Przykład w Pythonie

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/speech',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'script': 'Dzień dobry, koledzy. Przedstawię postępy z tego tygodnia.',
        'tone': 'spokojnie i wyraźnie, raport na spotkaniu',
        'gender': 'male',
        'backing_music': True,
    },
    timeout=300,
)
response.raise_for_status()
items = response.json()          # zwykle 2 pozycje
for item in items:
    print(item['song_id'], item['status'])

Opis parametrów

script (wystąpienie, wymagane)

• Wklej treść, którą chcesz wygłosić; możesz też napisać jedno zdanie opisu i pozwolić modelowi napisać wystąpienie (na przykład „mowa motywacyjna w przerwie dla drużyny przegrywającej dwudziestoma punktami, od cichego szeptu do pełnego krzyku”).
• Znaki nowej linii, akapity i didaskalia typu [pauza] można wpisywać bezpośrednio, a model będzie ich przestrzegał w miarę możliwości.
• Limit to 3000 znaków (liczone w znakach Unicode; jeden znak chiński liczy się jako 1); powyżej zwracane jest 400 i nic nie jest pobierane.

tone (ton i scena, opcjonalne)

Opisuje, jak mówić, a nie co mówić. Warto podać cztery rodzaje informacji: ton, tempo/rytm, emocję i miejsce.

Energicznie i mocno, tempo od wolnego do szybkiego, wyraźne pauzy; aula szkolna, przed całą społecznością szkolną
Ciepło i łagodnie, spokojne tempo; przyjęcie weselne
Spokojnie i powściągliwie, równo i wyraźnie; raport dla zarządu

Limit to 1000 znaków. Bez tej wartości model ocenia na podstawie treści script.

gender / vocal_gender (płeć mówiącego, opcjonalne)

• Dla głosu męskiego przekaż m lub male, dla żeńskiego f lub female; serwer normalizuje je do m / f.
• Obie nazwy pól działają, wystarczy jedna: gender to zalecana forma w tym punkcie końcowym; jeśli używasz już trybu niestandardowego, możesz nadal przekazywać vocal_gender.
• Brak wartości oznacza „dowolny”, decyduje model.

backing_music (muzyka w tle, opcjonalne)

• Domyślnie true (z muzyką w tle), tak jak w wersji webowej Suno.
• false daje wystąpienie tylko z głosem, przydatne, gdy później chcesz dodać własną muzykę lub lektora.
• Musi to być wartość logiczna JSON true / false; ciągi "true" i "1" też są przyjmowane, ale zalecane są wartości logiczne.

model (model, opcjonalne)

Wszystkie trzy modele dla klienta są dostępne w tej samej cenie (0,6 juana za wywołanie). Mowę generuje rodzina Suno v6; bez wartości przyjmowane jest suno-v6. Jeśli nie masz wyraźnych preferencji, zwykle nie trzeba tego pola przekazywać.

Walidacja parametrów i limity tekstu

Poniższe przypadki zwracają HTTP 400, a wszystkie są blokowane przed pobraniem opłaty, więc nie powstaje żaden koszt:

Limity pól tekstowych

Przekroczenie limitu również zwraca HTTP 400 i nie uruchamia generowania ani nie pobiera opłaty z góry. Liczenie odbywa się w znakach Unicode (jeden znak chiński liczy się jako 1) i obejmuje spacje na początku i na końcu:

Błąd ma postać script must not exceed 3000 characters; received 4120: pierwsze słowo to pole, które przekroczyło limit, a końcówka to rzeczywista liczba znaków, więc przy 400 możesz od razu przyciąć tekst według tych dwóch liczb.

Odpowiedź

Odpowiedzią jest tablica utworów dokładnie taka jak w innych punktach końcowych generowania (zwykle 2 pozycje); zapisz song_id i użyj API zapytań o utwory i historii, aby sprawdzić stan końcowy i adres audio:

[
  {
    "song_id": "b7529174-b495-465b-8c5e-cd21bea2df8c",
    "song_title": "Dobrze wykorzystać czas",
    "status": "pending",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-10-08T01:00:00Z"
  }
]

Niepowodzenie generowania i zwroty

Gdy generowanie się nie powiedzie, opłata za to wywołanie jest automatycznie zwracana w całości; nie trzeba kontaktować się z pomocą techniczną. Przyczynę widać w odpowiedzi lub w error_message API zapytań o utwory i historii.

Najczęstszą przyczyną jest uznanie treści za materiał chroniony, na przykład:

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

W takiej sytuacji zamień tekst na własne sformułowanie (albo zamień cytat na parafrazę) i wyślij ponownie.

Częste pytania

P: Dlaczego wynikiem jest „mowa”, a nie śpiew? O: To punkt końcowy wystąpień, a jego wynikiem jest audio mowy. Do śpiewu użyj punktów końcowych generowania lub trybu niestandardowego.

P: Dlaczego za każdym razem zwracane są 2 pozycje? O: Jak w innych punktach końcowych generowania na platformie, jedno generowanie daje 2 kandydatów; odpytaj je osobno po song_id i zostaw ten, który ci odpowiada.

P: Jak kontrolować długość? O: Decyduje o niej długość script; ten punkt końcowy nie przyjmuje parametru duration.

P: Czy mogę wskazać głos (na przykład swój sklonowany)? O: Obecna wersja tego nie obsługuje. Mowa używa stałego zestawu głosów, a gender wybiera męski lub żeński; jeśli potrzebujesz własnego głosu, użyj odpowiedniej funkcji API tworzenia profilu głosu (zalecane).

P: Co się stanie, jeśli nie przekażę tone? O: Model sam oceni ton i rytm na podstawie treści script. Aby stabilnie odtwarzać jakiś styl, wpisz ton, tempo i miejsce w tone.

Pola zgodne

Przy nowych integracjach używaj konsekwentnie snake_case. Pozostałe pola (script, tone, song_title, backing_music) nie mają aliasów camelCase.

Następne kroki

Gdy masz song_id:

1. Użyj API zapytań o utwory i historii, aby sprawdzić status generowania i adres audio;
2. Po zakończeniu użyj API pobierania i odsłuchu mediów utworów, aby pobrać lub odsłuchać;
3. W sprawie pobierania wsadowego lub przenoszenia do własnego magazynu zobacz punkty końcowe centrum pobierania.