StepFun Contextual TTS (predeterminado stepaudio-2.5-tts)
Genera voz en chino/japonés con StepFun Contextual TTS: la emoción y la prosodia se controlan mediante descripciones en lenguaje natural, no etiquetas fijas. El modelo predeterminado es stepaudio-2.5-tts (el que usa el script incluido): en una comparación A/B ciega del 2026-09-16 con nuestros propios casos, 2.5 ganó los pares neutral / jiao / lively-girl 3:2. Elige stepaudio-3-tts cuando la línea sea un susurro o tenga prosodia intensa con () en línea — v3 ganó exactamente esos dos pares; v3 también eleva el límite de instruction a 500 caracteres (2.5 tiene 200). ⚠️ Nunca sintetices voces clonadas con v3 — v3 acepta el ID de voz clonada sin error pero retrocede silenciosamente a la voz femenina predeterminada. La causa raíz: toda la cadena de clonación de StepFun sigue en la familia 2.5 (la API de creación de clones solo acepta 2.5/step-tts-2/step-tts-mini, v3 no está en la lista; la síntesis de clones en v3 no se ha publicado). Los clones creados en ambas generaciones se pierden en v3: clon de step-tts-2 SIM 0.272, clon nuevo creado con 2.5 SIM 0.195 (ancla 0.773), el mismo ID en 2.5 obtiene 0.743/0.678.
Complemento: para transcripción con
stepaudio-3-asr-max(el modelo hermano), usa la habilidadstepfun-asr: comparten clave API pero viven en endpoints diferentes con formatos de cuerpo distintos.
Por qué existe esta habilidad — dos problemas no obvios que cuestan horas si no los conoces:
stepaudio-3-ttsrechazavoice_label(la forma de step-tts-2) — verificado en v3 2026-09-16: HTTP 400voice_label no es compatible con este modelo. La emoción/prosodia se maneja medianteinstruction(descripción en lenguaje natural, ≤500 caracteres en v3 — 200 era el límite de 2.5) y paréntesis()en línea dentro del propio texto.- El comportamiento de censura depende de la versión del modelo — la lista de desencadenantes de la era 2.5 (死 / 消失 / términos políticos sensibles →
censorship_block) no se activó en v3 en una prueba de muestra única del 2026-09-16; trata la censura como presente pero verifica de nuevo por cada desencadenante antes de construir mapas de reescritura. Las opciones de la era 2.5 están enreferences/migration_from_v2.md.
Configuración y autenticación
La clave API reside en $STEPFUN_API_KEY (preferida) o ${CLAUDE_PLUGIN_DATA}/config.json (alternativa para persistencia entre sesiones). Todos los scripts incluidos intentan primero la variable de entorno y luego el archivo de configuración.
Configuración inicial (en una línea):
mkdir -p "${CLAUDE_PLUGIN_DATA}" && cat > "${CLAUDE_PLUGIN_DATA}/config.json" <<EOF
{"api_key": "<pegar clave aquí>"}
EOF
Si el usuario no ha establecido una clave, pídele que la pegue (no adivines / no uses un marcador de posición). Las claves API de StepFun están disponibles en https://platform.stepfun.com/ → API Keys. Usa una clave Normal, no una clave Plan (las claves Plan están restringidas a modelos de texto y fallan silenciosamente en los endpoints de audio).
Tareas comunes — árbol de decisión
| El usuario quiere... | Script | Detalle clave |
|---|---|---|
| Sintetizar 1–500 caracteres en chino con emoción | scripts/tts_generate.py | Usa instruction para el estado de ánimo, () para prosodia en línea |
| Sintetizar texto largo (500–1000 caracteres) | scripts/tts_generate.py | 1000 caracteres es el límite máximo; dividir en límites semánticos por encima de eso |
| Generar por lotes líneas de voz para juegos/aplicaciones | scripts/tts_generate.py --batch <jsonl> | Manejar la alternativa censorship_block individualmente |
| Comparar A/B dos modelos TTS | scripts/ab_compare.sh | Compara duración/tamaño entre dos directorios |
Migrar desde step-tts-2 / stepaudio-2.5-tts | ver references/migration_from_v2.md | voice_label.emotion → reescritura instruction + lista de censura de la era 2.5 |
Puntos de inicio
- Sintetizar una sola línea: Ejecuta
python3 scripts/tts_generate.py --text "你好" --out /tmp/hello.mp3 --instruction "温暖的希望感". Para control detallado, lee la sección "Contextual TTS" a continuación. - Desde código: este script es el envoltorio del endpoint en
llm-registry—llmreg.wrapper_for("stepfun-tts").tts_generate.synthesize(api_key=…, text=…, model=…, extra={…}).extrase fusiona en el cuerpo de la solicitud tal cual; con{"timestamp": True, "return_url": True}el servidor responde con un sobre JSON ({"data": {"url", "subtitles"}}) que vuelve bajojsonen lugar deaudio_bytes(verificado 2026-09-19). Los parámetros no se facturan — envía lo que necesites. Las llamadas directas a/v1/audio/speechdesde otros lugares están bloqueadas por el hookllm-entry-guard. - Una migración completa de
step-tts-2a Contextual TTS: leereferences/migration_from_v2.mdde principio a fin antes de tocar el código. Contiene elINSTRUCTION_MAP, el patrón de lista SKIP_CENSORED y la estrategia de directorio de salida para A/B no destructivo (escrito para 2.5; los mecanismos de migración son idénticos en v3).
Contextual TTS — más allá de las etiquetas de emoción
La característica principal de stepaudio-3-tts es que dejas de mapear emociones a etiquetas fijas y empiezas a describir lo que quieres en lenguaje natural. Dos capas:
Contexto global (parámetro instruction) — establece el tono general de toda la expresión. ≤500 caracteres en v3 (2.5 tenía 200; una instrucción de 300 caracteres verificada como aceptada en v3 2026-09-16). Piensa en ello como dar dirección de escena a un actor de voz.
instruction: "克制的悲伤,语气低沉柔弱,像快要消失一样"
Contexto en línea (paréntesis () dentro de input) — directivas dentro de la oración. El contenido entre paréntesis se consume como direcciones y NO se lee en voz alta. Úsalo para control preciso de pausas, respiración, énfasis o cambios de emoción en medio de la frase.
input: "(试探着问)你好吗?(开心地)太好了!(突然沉下来)不过...我快要消失了。"
Ejemplos que funcionaron en la práctica (verificado 2026-04-23 en 2.5; los cinco re-verificados en v3 2026-09-16, incluidos estos casos de instrucción y prosodia en línea):
instruction: "活泼俏皮,像是在撒娇,带点嘴硬"— acelera visiblemente la entrega respecto a neutralinstruction: "耳语声,气声很重,几乎听不清"— produce susurro/respiración audibleinput: "你好(停顿一下)我是蕾格(轻声)今天(加重)的天气真不错。"— directivas en línea respetadas todas
Lo que stepaudio-3-tts NO aceptará — el parámetro voice_label. Error en v3: voice_label no es compatible con este modelo (2.5 decía ...para modelos v2). Esta es la principal trampa de migración desde step-tts-2.
Patrones de error comunes (errores reales, soluciones reales)
| Respuesta de error | Causa real | Solución |
|---|---|---|
"voice_label no es compatible con este modelo" (v3) / "...para modelos v2" (2.5) | Se envió voice_label a un modelo Contextual TTS | Elimina voice_label; pon la misma intención en instruction como lenguaje natural |
"El contenido que proporcionaste o la máquina generó está bloqueado." tipo: censorship_block | Palabra sensible (era 2.5: 死 / 消失 / etc.; desencadenantes de v3 no verificados) | Reescribe la frase O retrocede a step-tts-2 para esa línea específica (modelo mixto está bien) |
| Truncamiento de audio silencioso (input > 1000 caracteres) | Límite máximo excedido | Divide en límites semánticos; no trunques en medio de una oración |
Más en references/known_issues.md.
Cuándo leer las referencias
references/api_reference.md— JSON exacto de solicitud/respuesta para/v1/audio/speech, todos los campos, respuestas de error. Léelo al escribir llamadas HTTP directas en lugar de usar los scripts incluidos.references/migration_from_v2.md— guía completa para mover un proyecto de step-tts-2 a Contextual TTS. Contiene la tabla de reescritura emoción→instruction, la estrategia de directorio A/B, los puntos de control de decisión y los datos de compensación velocidad/calidad de abril de 2026 (escritos contra 2.5). Léelo antes de cualquier trabajo de migración.references/known_issues.md— patrones de censura, inflación de duración TTS, error de nomenclatura de parámetros de la familia v2, límite máximo de 1000 caracteres. Verificación de la era 2.5; re-verifica en v3 antes de confiar en una entrada específica. Léelo al depurar salidas anómalas o evaluar si adoptar.
Invariantes de diseño (no romper estos)
- Salida A/B no destructiva — al regenerar un corpus con un nuevo modelo, escribe en un directorio paralelo (
voice/zh_v3/), nunca sobrescribas el corpus de producción. La guía de migración muestra por qué. - Manejo de censura por línea — si 2/29 líneas obtienen
censorship_block, no falles el lote. Registra los IDs omitidos, continúa. La alternativa de modelo mixto (step-tts-2 para las 2 omitidas) es normal. - No dupliques la lógica de voice_label en código nuevo — cualquier código TTS nuevo que apunte a stepaudio-3-tts debe usar solo
instruction+()en línea. No escribas una rama que emita condicionalmentevoice_label.
Datos específicos de v3 (verificados 2026-09-16)
- Voces oficiales: 60+ mediante
GET /v1/audio/system_voices?model=stepaudio-3-tts— la lista de 2.5 se hereda completamente, más voces nuevas (por ejemplo, nombres en inglésLisa/Alfie, shanghainésshanghaifemale/shanghaimale). - Voces clonadas (复刻): NO uses
stepaudio-3-tts— causa raíz confirmada 2026-09-16: toda la pila de clonación de StepFun sigue siendo de la familia 2.5. La API de creación (POST /v1/audio/voices) solo aceptastepaudio-2.5-tts/step-tts-2/step-tts-mini, y v3/v1/audio/speechretrocede silenciosamente a una voz femenina predeterminada para CUALQUIER ID clonado — SIM 0.272 (clon de step-tts-2) y 0.195 (clon nuevo creado con 2.5) frente al ancla 0.773; los mismos IDs en 2.5 obtienen 0.743/0.678. Sintetiza clones constepaudio-2.5-tts(mejor SIM) ostep-tts-2. - Sin transmisión WebSocket para v3 (a partir de 2026-09-16):
wss://api.stepfun.com/v1/realtime/audio?model=stepaudio-3-ttsse rechaza en el handshake (404), mientras que 2.5 todavía transmite allí. ¿Necesitas marcas de tiempo de subtítulos a nivel de carácter en v3? Usa RESTtimestamp:true + return_url:true(los subtítulos llegan en el JSON de respuestadata.subtitles[], nivel de carácter en ms, eje absoluto acumulado) — el simplestream_format:"audio"no puede transportar subtítulos (servidor 400).
Precios (verificados 2026-09-16, volátiles)
stepaudio-3-ttssíntesis: 2.5 元 / 10,000 caracteres (página oficial del modelo, 2026-09-16 — más barato que los ~5.8 de la era 2.5)- Clonación de voz zero-shot: 9.9 元 / timbre
Vuelve a verificar en https://platform.stepfun.com/docs/zh/guides/pricing/details antes de citar a las partes interesadas.