Communitygithub.com

StepFun TTS Contextual (padrão stepaudio-2.5-tts)

Gera fala em chinês/japonês com o TTS Contextual da StepFun — emoção e prosódia via descrição em linguagem natural, sem rótulos fixos. Substitui o voice_label do step-tts-2 por instruções de texto.

O que é StepFun TTS Contextual (padrão stepaudio-2.5-tts)?

Este skill integra a API de TTS Contextual da StepFun (modelos stepaudio-2.5-tts e stepaudio-3-tts) ao assistente de IA, permitindo síntese de voz em chinês e japonês com controle fino de emoção e prosódia. Em vez de usar tags fixas como no step-tts-2, o skill utiliza descrições em linguagem natural (campo `instruction`) e diretivas inline entre parênteses no próprio texto, proporcionando resultados mais naturais e expressivos. Suporta tanto linhas individuais quanto geração em lote via arquivos JSONL, além de comparação A/B entre modelos. É ideal para dublagem de jogos, assistentes de voz, e qualquer aplicação que exija controle emocional ou de prosódia. A API é autenticada pela chave `$STEPFUN_API_KEY` (ou arquivo de configuração). Importante: o modelo v3 (stepaudio-3-tts) não aceita o parâmetro `voice_label` (apenas `instruction` e inline `()`) e não deve ser usado com vozes clonadas (que funcionam apenas nos modelos 2.5 e step-tts-2). Para transcrição, o skill irmão `stepfun-asr` deve ser usado.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/daymade/claude-code-skills/tree/HEAD/daymade-audio/stepfun-tts

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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 skill stepfun-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:

  1. stepaudio-3-tts rejeita voice_label (o método do step-tts-2) — verificado no v3 em 2026-09-16: HTTP 400 voice_label is not supported for this model. Emoção/prosódia são controladas por instruction (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.
  2. 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 em references/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...ScriptDetalhe importante
Sintetizar 1–500 caracteres em chinês com emoçãoscripts/tts_generate.pyUse instruction para o tom, () para prosódia inline
Sintetizar texto longo (500–1000 caracteres)scripts/tts_generate.py1000 caracteres é o limite absoluto; divida em fronteiras semânticas acima disso
Gerar em lote falas para jogos/aplicativosscripts/tts_generate.py --batch <jsonl>Trate cada falha censorship_block individualmente
Comparar dois modelos TTS (A/B)scripts/ab_compare.shCompara duração/tamanho entre dois diretórios
Migrar do step-tts-2 / stepaudio-2.5-ttsveja references/migration_from_v2.mdvoice_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 sob json em vez de audio_bytes (verificado em 2026-09-19). Parâmetros não são cobrados — envie o que precisar. Chamadas diretas a /v1/audio/speech vindas de fora são bloqueadas pelo hook llm-entry-guard.
  • Uma migração completa de step-tts-2 → TTS Contextual: leia references/migration_from_v2.md de ponta a ponta antes de tocar no código. Ele contém o INSTRUCTION_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 neutro
  • instruction: "耳语声,气声很重,几乎听不清" — produz sussurro/respiração audível
  • input: "你好(停顿一下)我是蕾格(轻声)今天(加重)的天气真不错。" — 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 erroCausa realCorreção
"voice_label is not supported for this model" (v3) / "...for v2 models" (2.5)Enviou voice_label para um modelo TTS ContextualRemova voice_label; coloque a mesma intenção em instruction como linguagem natural
"The content you provided or machine outputted is blocked." type: censorship_blockPalavra 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 excedidoDivida 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)

  1. 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ê.
  2. 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.
  3. 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 emita voice_label condicionalmente.

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/Alfie com 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ó aceita stepaudio-2.5-tts / step-tts-2 / step-tts-mini, e o /v1/audio/speech do 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 com stepaudio-2.5-tts (melhor SIM) ou step-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 REST timestamp:true + return_url:true (as legendas chegam no JSON da resposta data.subtitles[], em ms por caractere, eixo absoluto acumulado) — o stream_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.

Individual skills in this repo

This repo contains 9 individual skills — each has its own dedicated page.

daymade/claude-code-skills

This skill should be used when comparing two videos to analyze compression results or quality differences. Generates interactive HTML reports with quality metrics (PSNR, SSIM) and frame-by-frame visual comparisons. Triggers when users mention "compare videos", "video quality", "compression analysis", "before/after compression", or request quality assessment of compressed videos.

daymade/claude-code-skills

Download YouTube videos and HLS streams (m3u8) from platforms like Mux, Vimeo, etc. using yt-dlp and ffmpeg. Use this skill when users request downloading videos, extracting audio, handling protected streams with authentication headers, or troubleshooting download issues like nsig extraction failures, 403 errors, or cookie extraction problems.

daymade/local-conversation-history

Entry point for local AI conversation history across providers. Routes a request to the one skill that owns it, by platform (Claude Code, OpenAI Codex, Kimi CLI) and action (read evidence vs continue interrupted work), and owns the one job none of them own alone: a single inventory spanning all three providers. Use when the provider is unknown or plural ("our history", "what have I been working on", "which chats did I have"), when the user wants Kimi CLI history at all, when it is unclear whether they need evidence or resumption, or when they ask for this skill by name. Vague recall that names no platform ("we discussed this once, when was it?") belongs here rather than to a single-provider reader, because a Claude-only answer to an unscoped question cannot support an absence claim. When the platform and the action are both already clear, load that executor skill directly instead — except Kimi CLI, which has no reader or continuation skill of its own and always routes through here.

daymade/ppt-creator

Create professional slide decks from topics or documents. Generates structured content with data-driven charts, speaker notes, and complete PPTX files. Applies persuasive storytelling principles (Pyramid Principle, assertion-evidence). Supports multiple formats (Marp, PowerPoint). Use for presentations, pitches, slide decks, or keynotes.

daymade/prompt-optimizer

Transform vague prompts into precise, well-structured specifications using EARS (Easy Approach to Requirements Syntax) methodology. This skill should be used when users provide loose requirements, ambiguous feature descriptions, or need to enhance prompts for AI-generated code, products, or documents. Triggers include requests to "optimize my prompt", "improve this requirement", "make this more specific", or when raw requirements lack detail and structure.

daymade/qa-expert

This skill should be used when establishing comprehensive QA testing processes for any software project. Use when creating test strategies, writing test cases following Google Testing Standards, executing test plans, tracking bugs with P0-P4 classification, calculating quality metrics, or generating progress reports. Includes autonomous execution capability via master prompts and complete documentation templates for third-party QA team handoffs. Implements OWASP security testing and achieves 90% coverage targets.

daymade/read-claude-code-history

Reads, searches, and exports local Claude Code history without resuming work. Covers recent session inventory, exact session timelines, verbatim human input including queued mid-turn prompts, full-event keyword search, hybrid recall when wording changed, end-state triage, and deleted-file recovery across active Claude homes plus registered archives. Use whenever the user asks what they or Claude said, wants a Claude Code session ID or original context, remembers prior work vaguely, needs an old file from a transcript, or must prove what a Claude session contained before continuing it. Also owns the only Kimi CLI surface, via its Kimi inventory and search flags. For Codex history use read-codex-history; when the request names no platform at all or spans providers, start at local-conversation-history.

daymade/read-codex-history

Reads, searches, and exports local OpenAI Codex history without continuing the old task. Lists recent Codex sessions, extracts exact prompt-ledger inputs by Session, locates a rollout by verified session_meta identity, reconstructs one chronological user/assistant timeline with fork and compaction lineage, and performs bounded keyword search across live and archived rollouts. Use whenever the user asks what they told Codex, wants recent original inputs, a Codex Session ID, full prior context, fork ancestry, or evidence of what a Codex run did. For Claude Code history use read-claude-code-history.

daymade/twitter-reader

Fetch Twitter/X post content including long-form Articles with full images and metadata. Use when Claude needs to retrieve tweet/article content, author info, engagement metrics, and embedded media. Supports individual posts and X Articles (long-form content). Automatically downloads all images to local attachments folder and generates complete Markdown with proper image references. Preferred over Jina for X Articles with images.

Habilidades Relacionadas