StepFun Contextual TTS (Standard: stepaudio-2.5-tts)
Generieren Sie chinesische/japanische Sprachausgabe mit StepFuns Contextual TTS – Emotion und Prosodie werden über natürlichsprachliche Beschreibungen gesteuert, nicht über feste Labels. Standardmodell ist stepaudio-2.5-tts (das vom gebündelten Skript verwendet wird): In einem blinden A/B-Test vom 16.09.2026 auf unseren eigenen Fällen gewann 2.5 die neutral/jiao/lively-girl-Paare mit 3:2. Wählen Sie stepaudio-3-tts, wenn die Zeile geflüstert wird oder eine starke inline-()-Prosodie aufweist – v3 gewann genau diese beiden Paare; v3 erhöht zudem das instruction-Limit auf 500 Zeichen (2.5 hat 200). ⚠️ Synthetisieren Sie Klonstimmen niemals mit v3 – v3-Sprache akzeptiert Klonstimmen-IDs zwar ohne Fehler, fällt aber stillschweigend auf die Standard-Frauenstimme zurück – Grund: Die gesamte Klonkette von StepFun bleibt in der 2.5-Familie (die Klonerstellungs-API akzeptiert nur 2.5/step-tts-2/step-tts-mini, v3 ist nicht enthalten; die v3-Synthese-Klonfunktion ist nicht veröffentlicht). Klone beider Generationen gehen auf v3 verloren: step-tts-2-Klon SIM 0.272, neuer 2.5-Klon SIM 0.195 (Anker 0.773), gleiche ID auf 2.5: 0.743/0.678.
Begleitinformation: Für die Transkription mit
stepaudio-3-asr-max(dem Schwestermodel) verwenden Sie diestepfun-asr-Fähigkeit – beide teilen sich einen API-Schlüssel, laufen aber auf verschiedenen Endpunkten mit unterschiedlichen Anfragekörpern.
Warum es diese Fähigkeit gibt – zwei nicht offensichtliche Fallstricke, die Stunden kosten, wenn man sie nicht kennt:
stepaudio-3-ttslehntvoice_labelab (der step-tts-2-Weg) – verifiziert auf v3 am 16.09.2026: HTTP 400voice_label is not supported for this model. Emotion/Prosodie wird überinstruction(natürlichsprachliche Beschreibung, ≤500 Zeichen auf v3 – 200 war das Limit von 2.5) und inline()-Klammern im Text selbst gesteuert.- Das Zensurverhalten ist modellversionsspezifisch – die 2.5-Triggerliste (死 / 消失 / sensible politische Begriffe →
censorship_block) hat bei einer Einzelstichprobe am 16.09.2026 auf v3 nicht ausgelöst; behandeln Sie Zensur als vorhanden, aber überprüfen Sie sie pro Trigger, bevor Sie Umschreibungsmaps erstellen. Die 2.5-Optionen finden Sie inreferences/migration_from_v2.md.
Konfiguration und Authentifizierung
Der API-Schlüssel liegt in $STEPFUN_API_KEY (bevorzugt) oder ${CLAUDE_PLUGIN_DATA}/config.json (Fallback für sitzungsübergreifende Persistenz). Alle gebündelten Skripte versuchen zuerst die Umgebungsvariable, dann die Konfigurationsdatei.
Erstmalige Einrichtung (Einzeiler):
mkdir -p "${CLAUDE_PLUGIN_DATA}" && cat > "${CLAUDE_PLUGIN_DATA}/config.json" <<EOF
{"api_key": "<Schlüssel hier einfügen>"}
EOF
Wenn der Benutzer noch keinen Schlüssel gesetzt hat, bitten Sie ihn, ihn einzufügen (nicht raten/keinen Platzhalter verwenden). StepFun-API-Schlüssel sind verfügbar unter https://platform.stepfun.com/ → API Keys. Verwenden Sie einen Normal-Schlüssel, keinen Plan-Schlüssel (Plan-Schlüssel sind auf Textmodelle beschränkt und schlagen bei Audio-Endpunkten stillschweigend fehl).
Häufige Aufgaben – Entscheidungsmatrix
| Benutzer möchte... | Skript | Wichtiges Detail |
|---|---|---|
| 1–500 Zeichen chinesisch mit Emotion synthetisieren | scripts/tts_generate.py | instruction für Stimmung, () für Inline-Prosodie verwenden |
| Langen Text (500–1000 Zeichen) synthetisieren | scripts/tts_generate.py | 1000 Zeichen sind die harte Grenze; darüber an semantischen Grenzen teilen |
| Stapelverarbeitung von Sprachaufnahmen für Spiele/Apps | scripts/tts_generate.py --batch <jsonl> | censorship_block-Fallbacks einzeln behandeln |
| Zwei TTS-Modelle im A/B-Vergleich testen | scripts/ab_compare.sh | Vergleicht Dauer/Größe über zwei Verzeichnisse hinweg |
Migration von step-tts-2 / stepaudio-2.5-tts | siehe references/migration_from_v2.md | voice_label.emotion → instruction-Umschreibung + 2.5-Zensurliste |
Startpunkte
- Eine einzelne Zeile synthetisieren: Führen Sie
python3 scripts/tts_generate.py --text "你好" --out /tmp/hello.mp3 --instruction "温暖的希望感"aus. Für detaillierte Steuerung lesen Sie den Abschnitt „Contextual TTS“ unten. - Aus Code: Dieses Skript ist der Wrapper des Endpunkts in
llm-registry–llmreg.wrapper_for("stepfun-tts").tts_generate.synthesize(api_key=…, text=…, model=…, extra={…}).extrawird unverändert in den Anforderungskörper eingefügt; mit{"timestamp": True, "return_url": True}antwortet der Server mit einem JSON-Envelope ({"data": {"url", "subtitles"}}), der unterjsonstattaudio_byteszurückkommt (verifiziert am 19.09.2026). Parameter werden nicht berechnet – senden Sie, was Sie brauchen. Direkte/v1/audio/speech-Aufrufe von außerhalb werden durch denllm-entry-guard-Hook blockiert. - Eine vollständige Migration von
step-tts-2→ Contextual TTS: Lesen Siereferences/migration_from_v2.mdvollständig durch, bevor Sie Code berühren. Es enthält dieINSTRUCTION_MAP, das SKIP_CENSORED-Listenmuster und die Ausgabeverzeichnisstrategie für zerstörungsfreie A/B-Tests (für 2.5 geschrieben; die Migrationsmechanik ist auf v3 identisch).
Contextual TTS – Über Emotionslabels hinaus
Das Hauptmerkmal von stepaudio-3-tts ist, dass Sie aufhören, Emotionen festen Tags zuzuordnen, und stattdessen in natürlicher Sprache beschreiben, was Sie möchten. Zwei Ebenen:
Globaler Kontext (instruction-Parameter) – setzt den Gesamtton für die gesamte Äußerung. ≤500 Zeichen auf v3 (2.5 hatte 200; eine 300-Zeichen-Instruktion wurde auf v3 am 16.09.2026 verifiziert akzeptiert). Stellen Sie es sich wie eine Regieanweisung für einen Synchronsprecher vor.
instruction: "克制的悲伤,语气低沉柔弱,像快要消失一样"
Inline-Kontext (()-Klammern innerhalb von input) – Satzinterne Direktiven. In Klammern gesetzter Inhalt wird als Anweisung konsumiert und NICHT vorgelesen. Verwenden Sie dies für präzise Steuerung von Pausen, Atem, Betonung oder emotionswechseln mitten im Satz.
input: "(试探着问)你好吗?(开心地)太好了!(突然沉下来)不过...我快要消失了。"
Beispiele, die in der Praxis funktionierten (verifiziert am 23.04.2026 auf 2.5; alle fünf am 16.09.2026 auf v3 erneut verifiziert, einschließlich dieser Instruktions- und Inline-Prosodiefälle):
instruction: "活泼俏皮,像是在撒娇,带点嘴硬"– beschleunigt die Aussprache sichtbar gegenüber neutralinstruction: "耳语声,气声很重,几乎听不清"– erzeugt hörbares Flüstern/Atmeninput: "你好(停顿一下)我是蕾格(轻声)今天(加重)的天气真不错。"– Inline-Direktiven alle beachtet
Was stepaudio-3-tts NICHT akzeptiert – Der voice_label-Parameter. Fehler auf v3: voice_label is not supported for this model (2.5 sagte ...for v2 models). Dies ist die häufigste Migrationsfalle von step-tts-2.
Häufige Fehlermuster (echte Fehler, echte Lösungen)
| Fehlerantwort | Tatsächliche Ursache | Lösung |
|---|---|---|
"voice_label is not supported for this model" (v3) / "...for v2 models" (2.5) | voice_label an ein Contextual-TTS-Modell gesendet | voice_label entfernen; die gleiche Absicht in instruction als natürliche Sprache einfügen |
"The content you provided or machine outputted is blocked." type: censorship_block | Sensitives Wort (2.5-Ära: 死 / 消失 / etc.; v3-Trigger nicht verifiziert) | Phrase umschreiben ODER für diese Zeile auf step-tts-2 zurückfallen (Modellmischung ist in Ordnung) |
| Stille Audioverkürzung (Eingabe > 1000 Zeichen) | Harte Grenze überschritten | An semantischen Grenzen teilen; nicht mitten im Satz abschneiden |
Mehr in references/known_issues.md.
Wann Referenzen lesen
references/api_reference.md– Exaktes Anfrage-/Antwort-JSON für/v1/audio/speech, alle Felder, Fehlerantworten. Lesen Sie dies, wenn Sie rohe HTTP-Aufrufe statt der gebündelten Skripte schreiben.references/migration_from_v2.md– Vollständiges Playbook für die Migration eines step-tts-2-Projekts zu Contextual TTS. Enthält die Emotion→Instruction-Umschreibungstabelle, die A/B-Verzeichnisstrategie, Entscheidungs-Checkpoints und die Geschwindigkeits-/Qualitätsdaten vom April 2026 (geschrieben für 2.5). Vor jeglicher Migrationsarbeit lesen.references/known_issues.md– Zensurmuster, TTS-Dauerinflation, v2-Familien-Parameternamensfalle, 1000-Zeichen-Hartgrenze. 2.5-Ära-Verifikation; vor Verwendung eines bestimmten Eintrags auf v3 erneut verifizieren. Lesen Sie dies beim Debuggen anomaler Ausgaben oder bei der Evaluierung der Einführung.
Design-Invarianten (nicht verletzen)
- Zerstörungsfreie A/B-Ausgabe – Beim Neugenerieren eines Korpus mit einem neuen Modell in ein paralleles Verzeichnis schreiben (
voice/zh_v3/), niemals den Produktionskorpus überschreiben. Das Migrations-Playbook zeigt warum. - Zeilenweise Zensurbehandlung – Wenn 2/29 Zeilen
censorship_blockerhalten, den Batch nicht abbrechen lassen. Die übersprungenen IDs protokollieren, fortfahren. Der gemischte Modell-Fallback (step-tts-2 für die beiden übersprungenen) ist normal. - Keine Duplizierung von voice_label-Logik in neuem Code – Jeder neue TTS-Code, der auf stepaudio-3-tts abzielt, sollte nur
instruction+ inline()verwenden. Schreiben Sie keinen Zweig, der bedingtvoice_labelausgibt.
v3-spezifische Fakten (verifiziert am 16.09.2026)
- Offizielle Stimmen: 60+ über
GET /v1/audio/system_voices?model=stepaudio-3-tts– die 2.5-Liste wird vollständig übernommen, plus neue Stimmen (z. B. englisch benannteLisa/Alfie, Shanghai-Dialektshanghaifemale/shanghaimale). - Klonstimmen (复刻):
stepaudio-3-ttsNICHT verwenden – Grundursache am 16.09.2026 ermittelt: Der gesamte Klon-Stack von StepFun ist noch in der 2.5-Familie. Die Erstellungs-API (POST /v1/audio/voices) akzeptiert nurstepaudio-2.5-tts/step-tts-2/step-tts-mini, und v3/v1/audio/speechfällt für JEDE Klon-ID stillschweigend auf eine Standard-Frauenstimme zurück – SIM 0.272 (step-tts-2-Klon) und 0.195 (frischer mit 2.5 erstellter Klon) gegenüber dem Anker 0.773; dieselben IDs auf 2.5 erreichen 0.743/0.678. Klone mitstepaudio-2.5-tts(beste SIM) oderstep-tts-2synthetisieren. - Kein WebSocket-Streaming für v3 (Stand 16.09.2026):
wss://api.stepfun.com/v1/realtime/audio?model=stepaudio-3-ttswird beim Handshake abgelehnt (404), während 2.5 dort noch streamt. Benötigen Sie zeichengenaue Subtitle-Zeitstempel auf v3? Verwenden Sie REST mittimestamp:true + return_url:true(Untertitel kommen im Antwort-JSONdata.subtitles[], zeichengenaue Millisekunden, kumulierte absolute Achse) – nacktesstream_format:"audio"kann keine Untertitel transportieren (Server 400).
Preise (verifiziert am 16.09.2026, volatil)
stepaudio-3-tts-Synthese: 2,5 元 / 10.000 Zeichen (offizielle Modellseite, 16.09.2026 – günstiger als die ~5,8 der 2.5-Ära)- Zero-Shot-Stimmklonung: 9,9 元 / Stimme
Vor der Zitierung gegenüber Stakeholdern erneut prüfen unter https://platform.stepfun.com/docs/zh/guides/pricing/details