StepFun Contextual TTS (par défaut stepaudio-2.5-tts)
Générez de la parole en chinois / japonais avec le TTS contextuel de StepFun — l'émotion et la prosodie passent par une description en langage naturel, et non par des étiquettes fixes. Le modèle par défaut est stepaudio-2.5-tts (celui utilisé par le script fourni) : lors d'un A/B aveugle le 2026-09-16 sur nos propres cas, le 2.5 a gagné les paires neutre / jiao / fille-vive 3:2. Choisissez stepaudio-3-tts lorsque la ligne est chuchotée ou avec une prosodie inline-() lourde — v3 a gagné exactement ces deux paires ; v3 élève également la limite de instruction à 500 caractères (2.5 est à 200). ⚠️ Ne synthétisez jamais de voix clonées avec v3 — la parole v3 accepte les ID de timbre cloné sans erreur mais revient silencieusement à une voix féminine par défaut — cause racine = toute la chaîne de clonage de StepFun reste dans la famille 2.5 (l'API de création de clonage n'accepte que 2.5/step-tts-2/step-tts-mini, v3 n'en fait pas partie ; le côté synthèse v3 pour le clonage n'est pas publié). Les clones créés par les deux générations sont tous perdus sur v3 : clone step-tts-2 SIM 0.272, nouveau clone créé avec 2.5 SIM 0.195 (ancrage 0.773), même ID sur 2.5 0.743/0.678.
Compagnon : pour la transcription avec
stepaudio-3-asr-max(le modèle frère), utilisez le skillstepfun-asr— ils partagent une clé API mais vivent sur des points de terminaison différents avec des structures de corps différentes.
Pourquoi ce skill existe — deux pièges non évidents qui coûtent des heures si vous ne les connaissez pas :
stepaudio-3-ttsrejettevoice_label(la méthode step-tts-2) — vérifié sur v3 le 2026-09-16 : HTTP 400voice_label is not supported for this model. L'émotion/la prosodie passe parinstruction(description en langage naturel, ≤500 caractères sur v3 — 200 était la limite de 2.5) et les parenthèses()inline dans le texte lui-même.- Le comportement de censure est spécifique à la version du modèle — la liste de déclencheurs de l'ère 2.5 (死 / 消失 / termes politiques sensibles →
censorship_block) n'a pas été déclenchée sur v3 lors d'un test d'un seul échantillon le 2026-09-16 ; considérez la censure comme présente mais revérifiez par déclencheur avant de construire des cartes de réécriture. Les options de l'ère 2.5 se trouvent dansreferences/migration_from_v2.md.
Configuration et authentification
La clé API se trouve dans $STEPFUN_API_KEY (recommandé) ou ${CLAUDE_PLUGIN_DATA}/config.json (solution de repli pour la persistance entre sessions). Tous les scripts fournis essaient d'abord la variable d'environnement, puis le fichier de configuration.
Première configuration (une ligne) :
mkdir -p "${CLAUDE_PLUGIN_DATA}" && cat > "${CLAUDE_PLUGIN_DATA}/config.json" <<EOF
{"api_key": "<collez la clé ici>"}
EOF
Si l'utilisateur n'a pas défini de clé, demandez-lui de la coller (ne devinez pas / n'utilisez pas d'espace réservé). Les clés API StepFun sont disponibles sur https://platform.stepfun.com/ → API Keys. Utilisez une clé Normale, pas une clé Plan (les clés Plan sont limitées aux modèles de texte et échouent silencieusement sur les points de terminaison audio).
Tâches courantes — arbre de décision
| L'utilisateur veut... | Script | Détail clé |
|---|---|---|
| Synthétiser 1–500 caractères chinois avec émotion | scripts/tts_generate.py | Utilisez instruction pour l'humeur, () pour la prosodie inline |
| Synthétiser un texte long (500–1000 caractères) | scripts/tts_generate.py | 1000 caractères est la limite maximale ; fractionnez aux limites sémantiques au-dessus |
| Générer par lots des lignes vocales pour un jeu/une app | scripts/tts_generate.py --batch <jsonl> | Gérez le repli censorship_block individuellement |
| Comparer A/B deux modèles TTS | scripts/ab_compare.sh | Compare la durée/la taille dans deux répertoires |
Migrer depuis step-tts-2 / stepaudio-2.5-tts | voir references/migration_from_v2.md | voice_label.emotion → réécriture instruction + liste de censure de l'ère 2.5 |
Points de départ
- Synthétiser une seule ligne : Exécutez
python3 scripts/tts_generate.py --text "你好" --out /tmp/hello.mp3 --instruction "温暖的希望感". Pour un contrôle précis, lisez la section « Contextual TTS » ci-dessous. - Depuis le code : ce script est l'enveloppe du point de terminaison dans
llm-registry—llmreg.wrapper_for("stepfun-tts").tts_generate.synthesize(api_key=…, text=…, model=…, extra={…}).extraest fusionné dans le corps de la requête tel quel ; avec{"timestamp": True, "return_url": True}le serveur répond avec une enveloppe JSON ({"data": {"url", "subtitles"}}) qui revient sousjsonau lieu deaudio_bytes(vérifié le 2026-09-19). Les paramètres ne sont pas facturés — envoyez ce dont vous avez besoin. Les appels directs/v1/audio/speechailleurs sont bloqués par le hookllm-entry-guard. - Une migration complète de
step-tts-2→ TTS contextuel : lisezreferences/migration_from_v2.mddu début à la fin avant de toucher au code. Il contientINSTRUCTION_MAP, le motif de liste SKIP_CENSORED, et la stratégie de répertoire de sortie pour un A/B non destructif (écrit pour 2.5 ; les mécanismes de migration sont identiques sur v3).
TTS contextuel — au-delà des étiquettes d'émotion
La fonctionnalité phare de stepaudio-3-tts est que vous cessez de mapper les émotions à des balises fixes et commencez à décrire ce que vous voulez en langage naturel. Deux couches :
Contexte global (paramètre instruction) — définit le ton général de l'énoncé entier. ≤500 caractères sur v3 (2.5 était à 200 ; une instruction de 300 caractères vérifiée acceptée sur v3 le 2026-09-16). Considérez-le comme une indication de mise en scène pour un comédien de doublage.
instruction : "克制的悲伤,语气低沉柔弱,像快要消失一样"
Contexte inline (parenthèses () dans input) — directives intra-phrase. Le contenu entre parenthèses est consommé comme des directions et n'est PAS lu à haute voix. Utilisez-le pour un contrôle précis des pauses, de la respiration, de l'emphase ou des changements d'émotion en milieu de phrase.
input : "(试探着问)你好吗?(开心地)太好了!(突然沉下来)不过...我快要消失了。"
Exemples qui ont fonctionné en pratique (vérifiés le 2026-04-23 sur 2.5 ; les cinq revérifiés sur v3 le 2026-09-16, y compris ces cas d'instruction et de prosodie inline) :
instruction : "活泼俏皮,像是在撒娇,带点嘴硬"— accélère visiblement le débit par rapport au neutreinstruction : "耳语声,气声很重,几乎听不清"— produit un chuchotement/souffle audibleinput : "你好(停顿一下)我是蕾格(轻声)今天(加重)的天气真不错。"— directives inline toutes respectées
Ce que stepaudio-3-tts n'accepte PAS — le paramètre voice_label. Erreur sur v3 : voice_label is not supported for this model (2.5 disait ...for v2 models). C'est le piège de migration n°1 depuis step-tts-2.
Schémas d'erreur courants (erreurs réelles, correctifs réels)
| Réponse d'erreur | Cause réelle | Correctif |
|---|---|---|
"voice_label is not supported for this model" (v3) / "...for v2 models" (2.5) | Envoyé voice_label à un modèle TTS contextuel | Supprimez voice_label ; mettez la même intention dans instruction en langage naturel |
"The content you provided or machine outputted is blocked." type: censorship_block | Mot sensible (ère 2.5 : 死 / 消失 / etc. ; déclencheurs v3 non vérifiés) | Réécrivez la phrase OU repliez-vous sur step-tts-2 pour cette ligne spécifique (modèle mixte est acceptable) |
| Troncature audio silencieuse (entrée > 1000 caractères) | Limite maximale dépassée | Fractionnez aux limites sémantiques ; ne tronquez pas en milieu de phrase |
Plus dans references/known_issues.md.
Quand lire les références
references/api_reference.md— JSON exact de requête/réponse pour/v1/audio/speech, tous les champs, réponses d'erreur. Lisez-le lorsque vous écrivez des appels HTTP bruts au lieu d'utiliser les scripts fournis.references/migration_from_v2.md— guide complet pour déplacer un projet step-tts-2 vers le TTS contextuel. Contient le tableau de réécriture émotion→instruction, la stratégie de répertoire A/B, les points de décision, et les données de compromis vitesse/qualité d'avril 2026 (écrites pour 2.5). Lisez-le avant tout travail de migration.references/known_issues.md— motifs de censure, inflation de durée TTS, piège de nommage des paramètres de la famille v2, limite maximale de 1000 caractères. Vérification de l'ère 2.5 ; revérifiez sur v3 avant de vous fier à une entrée spécifique. Lisez-le lors du débogage de sorties anormales ou de l'évaluation de l'adoption.
Invariants de conception (ne les cassez pas)
- Sortie A/B non destructive — lors de la régénération d'un corpus avec un nouveau modèle, écrivez dans un répertoire parallèle (
voice/zh_v3/), ne remplacez jamais le corpus de production. Le guide de migration montre pourquoi. - Gestion de la censure par ligne — si 2/29 lignes obtiennent
censorship_block, n'échouez pas le lot. Enregistrez les ID ignorés, continuez. Le repli avec modèle mixte (step-tts-2 pour les 2 ignorées) est normal. - Ne dupliquez pas la logique voice_label dans le nouveau code — tout nouveau code TTS ciblant stepaudio-3-tts doit uniquement utiliser
instruction+ inline(). N'écrivez pas de branche qui émet conditionnellementvoice_label.
Faits spécifiques à v3 (vérifiés le 2026-09-16)
- Voix officielles : 60+ via
GET /v1/audio/system_voices?model=stepaudio-3-tts— la liste 2.5 est entièrement héritée, plus de nouvelles voix (par exempleLisa/Alfieaux noms anglais, 上海话shanghaifemale/shanghaimale). - Voix clonées (复刻) : n'utilisez PAS
stepaudio-3-tts— cause racine identifiée le 2026-09-16 : toute la pile de clonage de StepFun est encore dans la famille 2.5. L'API de création (POST /v1/audio/voices) n'accepte questepaudio-2.5-tts/step-tts-2/step-tts-mini, et/v1/audio/speechde v3 revient silencieusement à une voix féminine par défaut pour TOUT ID cloné — SIM 0.272 (clone step-tts-2) et 0.195 (nouveau clone créé avec 2.5) contre l'ancrage 0.773 ; les mêmes ID sur 2.5 obtiennent 0.743/0.678. Synthétisez les clones avecstepaudio-2.5-tts(meilleur SIM) oustep-tts-2. - Pas de streaming WebSocket pour v3 (au 2026-09-16) :
wss://api.stepfun.com/v1/realtime/audio?model=stepaudio-3-ttsest rejeté à la poignée de main (404), tandis que 2.5 streame encore là. Besoin d'horodatages de sous-titres au niveau du caractère sur v3 ? Utilisez RESTtimestamp:true + return_url:true(les sous-titres arrivent dans le JSON de réponsedata.subtitles[], ms par caractère, axe absolu cumulé) — lestream_format:"audio"nu ne peut pas transporter de sous-titres (serveur 400).
Tarification (vérifiée le 2026-09-16, volatile)
- Synthèse
stepaudio-3-tts: 2,5 元 / 10 000 caractères (page officielle du modèle, 2026-09-16 — moins cher que l'ère 2.5 ~5,8) - Clonage vocal zero-shot : 9,9 元 / timbre
Revérifiez sur https://platform.stepfun.com/docs/zh/guides/pricing/details avant de citer aux parties prenantes.