O que StepFun TTS Contextual (padrão stepaudio-2.5-tts) faz?
Gere fala em chinês / japonês com o TTS Contextual da StepFun — emoção e prosódia são controladas por descrições em linguagem natural, sem rótulos fixos. O modelo padrão é stepaudio-2.5-tts (usado pelo script incluído): em um teste cego A/B feito em 2026-09-16 com nossos próprios casos, o 2.5 venceu os pares neutro / jiao / garota-viva por 3:2. Escolha stepaudio-3-tts quando a frase exigir sussurro ou prosódia inline com () — o v3 venceu exatamente esses dois pares; o v3 também eleva o limite de instruction para 500 caracteres (2.5 é 200). ⚠️ Nunca sintetize vozes clonadas com o v3 — o v3 aceita o ID de voz clonada sem erro, mas silenciosamente cai para uma voz feminina padrão — a causa raiz é que todo o pipeline de clonagem da StepFun ainda está na família 2.5 (a API de criação de clones só aceita 2.5/step-tts-2/step-tts-mini, o v3 não está listado; a funcionalidade de clonagem no lado da síntese do v3 não foi lançada). Clones criados em ambas as gerações são perdidos no v3: clone step-tts-2 com SIM 0,272, clone novo criado no 2.5 com SIM 0,195 (âncora 0,773), enquanto no 2.5 o mesmo ID atinge 0,743/0,678.
Complementar: para transcrição com
stepaudio-3-asr-max(o modelo irmão), use o skillstepfun-asr— eles compartilham a chave de API, mas vivem em endpoints diferentes com formatos de corpo diferentes.
Por que este skill existe — duas armadilhas não óbvias que custam horas se você não conhecê-las:
stepaudio-3-ttsrejeitavoice_label(o método do step-tts-2) — verificado no v3 em 2026-09-16: HTTP 400voice_label is not supported for this model. Emoção/prosódia são controladas porinstruction(descrição em linguagem natural, ≤500 caracteres no v3 — 200 era o limite do 2.5) e por parênteses()inline dentro do próprio texto.- O comportamento de censura é específico da versão do modelo — a lista de gatilhos da era 2.5 (死 / 消失 / termos políticos sensíveis →
censorship_block) não disparou no v3 em uma amostra única em 2026-09-16; trate a censura como presente, mas reverifique cada gatilho antes de construir mapas de reescrita. As opções da era 2.5 estão emreferences/migration_from_v2.md.
Configuração e autenticação
A chave da API reside em $STEPFUN_API_KEY (preferencial) ou em ${CLAUDE_PLUGIN_DATA}/config.json (fallback para persistência entre sessões). Todos os scripts incluídos tentam primeiro a variável de ambiente, depois o arquivo de configuração.
Configuração inicial (um comando):
mkdir -p "${CLAUDE_PLUGIN_DATA}" && cat > "${CLAUDE_PLUGIN_DATA}/config.json" <<EOF
{"api_key": "<cole sua chave aqui>"}
EOF
Se o usuário ainda não definiu uma chave, peça para ele colá-la (não tente adivinhar / não use um placeholder). As chaves da API StepFun estão disponíveis em https://platform.stepfun.com/ → API Keys. Use uma chave Normal, não uma chave Plan (chaves Plan são restritas a modelos de texto e falham silenciosamente em endpoints de áudio).
Tarefas comuns — árvore de decisão
| O usuário quer... | Script | Detalhe importante |
|---|---|---|
| Sintetizar 1–500 caracteres em chinês com emoção | scripts/tts_generate.py | Use instruction para o tom, () para prosódia inline |
| Sintetizar texto longo (500–1000 caracteres) | scripts/tts_generate.py | 1000 caracteres é o limite absoluto; divida em fronteiras semânticas acima disso |
| Gerar em lote falas para jogos/aplicativos | scripts/tts_generate.py --batch <jsonl> | Trate cada falha censorship_block individualmente |
| Comparar dois modelos TTS (A/B) | scripts/ab_compare.sh | Compara duração/tamanho entre dois diretórios |
Migrar do step-tts-2 / stepaudio-2.5-tts | veja references/migration_from_v2.md | voice_label.emotion → reescrita para instruction + lista de censura da era 2.5 |
Pontos de partida
- Sintetizar uma única linha: Execute
python3 scripts/tts_generate.py --text "你好" --out /tmp/hello.mp3 --instruction "温暖的希望感". Para controle mais refinado, leia a seção "TTS Contextual" abaixo. - A partir de código: este script é o invólucro do endpoint em
llm-registry—llmreg.wrapper_for("stepfun-tts").tts_generate.synthesize(api_key=…, text=…, model=…, extra={…}).extraé mesclado ao corpo da requisição como está; com{"timestamp": True, "return_url": True}o servidor responde com um envelope JSON ({"data": {"url", "subtitles"}}) que retorna sobjsonem vez deaudio_bytes(verificado em 2026-09-19). Parâmetros não são cobrados — envie o que precisar. Chamadas diretas a/v1/audio/speechvindas de fora são bloqueadas pelo hookllm-entry-guard. - Uma migração completa de
step-tts-2→ TTS Contextual: leiareferences/migration_from_v2.mdde ponta a ponta antes de tocar no código. Ele contém oINSTRUCTION_MAP, o padrão da lista SKIP_CENSORED e a estratégia de diretório de saída para A/B não destrutivo (escrito para 2.5; a mecânica de migração é idêntica no v3).
TTS Contextual — além dos rótulos de emoção
A principal funcionalidade do stepaudio-3-tts é que você para de mapear emoções para tags fixas e começa a descrever o que deseja em linguagem natural. Duas camadas:
Contexto global (parâmetro instruction) — define o tom geral de toda a frase. ≤500 caracteres no v3 (2.5 era 200; uma instrução de 300 caracteres foi verificada como aceita no v3 em 2026-09-16). Pense nisso como dar direção de cena a um dublador.
instruction: "克制的悲伤,语气低沉柔弱,像快要消失一样"
Contexto inline (parênteses () dentro do input) — diretivas dentro da frase. O conteúdo entre parênteses é consumido como direção e NÃO é lido em voz alta. Use para controle preciso de pausas, respiração, ênfase ou mudanças de emoção no meio da frase.
input: "(试探着问)你好吗?(开心地)太好了!(突然沉下来)不过...我快要消失了。"
Exemplos que funcionaram na prática (verificados em 2026-04-23 no 2.5; todos os cinco verificados novamente no v3 em 2026-09-16, incluindo estes casos de instrução e prosódia inline):
instruction: "活泼俏皮,像是在撒娇,带点嘴硬"— acelera visivelmente a fala em comparação com o neutroinstruction: "耳语声,气声很重,几乎听不清"— produz sussurro/respiração audívelinput: "你好(停顿一下)我是蕾格(轻声)今天(加重)的天气真不错。"— diretivas inline todas respeitadas
O que o stepaudio-3-tts NÃO aceitará — o parâmetro voice_label. Erro no v3: voice_label is not supported for this model (2.5 dizia ...for v2 models). Esta é a principal armadilha de migração do step-tts-2.
Padrões de erro comuns (erros reais, correções reais)
| Resposta de erro | Causa real | Correção |
|---|---|---|
"voice_label is not supported for this model" (v3) / "...for v2 models" (2.5) | Enviou voice_label para um modelo TTS Contextual | Remova voice_label; coloque a mesma intenção em instruction como linguagem natural |
"The content you provided or machine outputted is blocked." type: censorship_block | Palavra sensível (era 2.5: 死 / 消失 / etc.; gatilhos do v3 não verificados) | Reescreva a frase OU use step-tts-2 como fallback para essa linha específica (modelos mistos é ok) |
| Corte de áudio silencioso (input > 1000 caracteres) | Limite máximo excedido | Divida em fronteiras semânticas; não corte no meio de uma frase |
Mais em references/known_issues.md.
Quando ler as referências
references/api_reference.md— JSON exato de requisição/resposta para/v1/audio/speech, todos os campos, respostas de erro. Leia ao fazer chamadas HTTP brutas em vez de usar os scripts incluídos.references/migration_from_v2.md— guia completo para migrar um projeto step-tts-2 para TTS Contextual. Contém a tabela de reescrita emoção→instruction, a estratégia de diretórios A/B, pontos de verificação de decisão e os dados de trade-off velocidade/qualidade de 2026-04 (escritos para 2.5). Leia antes de qualquer trabalho de migração.references/known_issues.md— padrões de censura, inflação de duração do TTS, pegadinha de nomenclatura de parâmetros da família v2, limite máximo de 1000 caracteres. Verificação da era 2.5; reverifique no v3 antes de confiar em uma entrada específica. Leia ao depurar saídas anômalas ou avaliar se deve adotar.
Invariantes de design (não quebre estes)
- Saída A/B não destrutiva — ao regenerar um corpus com um novo modelo, escreva em um diretório paralelo (
voice/zh_v3/), nunca sobrescreva o corpus de produção. O guia de migração mostra o porquê. - Tratamento de censura por linha — se 2/29 linhas receberem
censorship_block, não falhe o lote. Registre os IDs ignorados, continue. O fallback com modelo misto (step-tts-2 para as 2 linhas ignoradas) é normal. - Não duplique lógica de voice_label em código novo — qualquer novo código TTS direcionado ao stepaudio-3-tts deve usar apenas
instruction+ inline(). Não escreva um ramo que emitavoice_labelcondicionalmente.
Fatos específicos do v3 (verificados em 2026-09-16)
- Vozes oficiais: 60+ via
GET /v1/audio/system_voices?model=stepaudio-3-tts— a lista do 2.5 é totalmente herdada, além de novas vozes (ex.:Lisa/Alfiecom nomes em inglês, 上海话shanghaifemale/shanghaimale). - Vozes clonadas (复刻): NÃO use
stepaudio-3-tts— causa raiz descoberta em 2026-09-16: toda a pilha de clonagem da StepFun ainda é da família 2.5. A API de criação (POST /v1/audio/voices) só aceitastepaudio-2.5-tts/step-tts-2/step-tts-mini, e o/v1/audio/speechdo v3 silenciosamente cai para uma voz feminina padrão para QUALQUER ID clonado — SIM 0,272 (clone step-tts-2) e 0,195 (clone novo criado no 2.5) vs a âncora 0,773; os mesmos IDs no 2.5 pontuam 0,743/0,678. Sintetize clones comstepaudio-2.5-tts(melhor SIM) oustep-tts-2. - Sem streaming WebSocket para v3 (desde 2026-09-16):
wss://api.stepfun.com/v1/realtime/audio?model=stepaudio-3-ttsé rejeitado no handshake (404), enquanto o 2.5 ainda faz streaming lá. Precisa de timestamps de legenda em nível de caractere no v3? Use RESTtimestamp:true + return_url:true(as legendas chegam no JSON da respostadata.subtitles[], em ms por caractere, eixo absoluto acumulado) — ostream_format:"audio"puro não pode transportar legendas (servidor retorna 400).
Preços (verificados em 2026-09-16, voláteis)
- Síntese
stepaudio-3-tts: 2,5 元 / 10.000 caracteres (página oficial do modelo, 2026-09-16 — mais barato que os ~5,8 da era 2.5) - Clonagem de voz zero-shot: 9,9 元 / timbre
Reveja em https://platform.stepfun.com/docs/zh/guides/pricing/details antes de citar para stakeholders.