StepFun 맥락 TTS (기본 stepaudio-2.5-tts)은(는) 무엇을 하나요?
StepFun의 맥락 TTS로 중국어/일본어 음성을 생성합니다. 감정과 운율은 고정된 레이블이 아닌 자연어 설명을 통해 제어합니다. **기본 모델은 stepaudio-2.5-tts**입니다(번들 스크립트가 사용하는 모델). 2026-09-16 자체 사례에 대한 블라인드 A/B 테스트에서 2.5는 중립 / 娇 / lively-girl 쌍에서 3:2로 우세했습니다. 속삭임이나 무거운 인라인 () 운율이 필요한 경우 stepaudio-3-tts를 선택하세요 — v3는 해당 두 쌍에서 정확히 승리했습니다. 또한 v3는 instruction 한도를 500자로 올립니다(2.5는 200자). ⚠️ 클론 음성을 v3로 합성하지 마세요 — v3 음성은 복제 음색 ID를 수용하지만 오류 없이 자동으로 기본 여성 음성으로 대체됩니다. 근본 원인은 StepFun의 전체 복제 파이프라인이 2.5 제품군에 머물러 있기 때문입니다(복제 생성 API는 2.5/step-tts-2/step-tts-mini만 허용하며 v3는 목록에 없음). 두 세대에서 생성된 클론은 v3에서 모두 손실됩니다: step-tts-2 클론 SIM 0.272, 2.5에서 생성된 새 클론 SIM 0.195(앵커 0.773), 2.5에서 동일 ID는 0.743/0.678.
참고:
stepaudio-3-asr-max(형제 모델)를 사용한 전사의 경우stepfun-asr스킬을 사용하세요. 두 모델은 API 키를 공유하지만 다른 엔드포인트와 다른 본문 형식을 사용합니다.
이 스킬이 존재하는 이유 — 알지 못하면 많은 시간을 낭비할 수 있는 두 가지 명확하지 않은 함정 때문입니다:
stepaudio-3-tts는voice_label을 거부합니다(step-tts-2 방식). 2026-09-16 v3에서 확인: HTTP 400voice_label is not supported for this model. 감정/운율은instruction(자연어 설명, v3에서 ≤500자 — 200자는 2.5 제한)과 텍스트 자체 내의 인라인()괄호를 통해 전달됩니다.- 검열 동작은 모델 버전에 따라 다릅니다. 2.5 시대의 트리거 목록(死 / 消失 / 민감한 정치 용어 →
censorship_block)은 2026-09-16 단일 샘플 프로브에서 v3에서 발생하지 않았습니다. 검열이 존재한다고 간주하되 재작성 맵을 구축하기 전에 트리거당 다시 확인하세요. 2.5 시대 옵션은references/migration_from_v2.md에 있습니다.
구성 및 인증
API 키는 $STEPFUN_API_KEY(권장) 또는 ${CLAUDE_PLUGIN_DATA}/config.json(세션 간 지속성을 위한 대체)에 있습니다. 번들된 모든 스크립트는 먼저 환경 변수를 시도한 다음 구성을 시도합니다.
최초 설정(한 줄):
mkdir -p "${CLAUDE_PLUGIN_DATA}" && cat > "${CLAUDE_PLUGIN_DATA}/config.json" <<EOF
{"api_key": "<키를 여기에 붙여넣기>"}
EOF
사용자가 키를 설정하지 않은 경우, 키를 붙여넣도록 요청하세요(추측하지 말고 자리 표시자를 사용하지 마세요). StepFun API 키는 https://platform.stepfun.com/ → API Keys에서 얻을 수 있습니다. Plan 키가 아닌 Normal 키를 사용하세요(Plan 키는 텍스트 모델로 제한되며 오디오 엔드포인트에서 자동으로 실패합니다).
일반적인 작업 — 결정 트리
| 사용자 원하는 것... | 스크립트 | 주요 세부 사항 |
|---|---|---|
| 감정을 포함한 1–500자 중국어 합성 | scripts/tts_generate.py | 분위기에 instruction 사용, 인라인 운율에 () 사용 |
| 긴 텍스트(500–1000자) 합성 | scripts/tts_generate.py | 1000자는 하드 상한; 그 이상은 의미 경계에서 분할 |
| 게임/앱 대사 일괄 생성 | scripts/tts_generate.py --batch <jsonl> | 각각에 대해 censorship_block 대체를 개별적으로 처리 |
| 두 TTS 모델 A/B 비교 | scripts/ab_compare.sh | 두 디렉터리 간의 지속 시간/크기 비교 |
step-tts-2 / stepaudio-2.5-tts에서 마이그레이션 | references/migration_from_v2.md 참조 | voice_label.emotion → instruction 재작성 + 2.5 시대 검열 목록 |
시작점
- 단일 라인 합성:
python3 scripts/tts_generate.py --text "你好" --out /tmp/hello.mp3 --instruction "溫暖的希望感"을 실행하세요. 세부 제어는 아래 "맥락 TTS" 섹션을 읽으세요. - 코드에서: 이 스크립트는
llm-registry의 엔드포인트 래퍼입니다 —llmreg.wrapper_for("stepfun-tts").tts_generate.synthesize(api_key=…, text=…, model=…, extra={…}).extra는 요청 본문에 그대로 병합됩니다.{"timestamp": True, "return_url": True}를 사용하면 서버가{"data": {"url", "subtitles"}}형식의 JSON 응답을 반환합니다(json아래에audio_bytes대신, 2026-09-19 확인). 매개변수는 청구되지 않습니다. 필요한 것을 보내세요. 다른 곳에서/v1/audio/speech를 직접 호출하면llm-entry-guard훅에 의해 차단됩니다. - step-tts-2에서 맥락 TTS로의 전체 마이그레이션: 코드를 만지기 전에
references/migration_from_v2.md를 끝까지 읽으세요.INSTRUCTION_MAP, SKIP_CENSORED 목록 패턴, 비파괴 A/B를 위한 출력 디렉터리 전략이 있습니다(2.5용으로 작성되었지만 마이그레이션 메커니즘은 v3에서 동일합니다).
맥락 TTS — 감정 레이블을 넘어서
stepaudio-3-tts의 핵심 기능은 감정을 고정된 태그에 매핑하는 것을 중단하고 원하는 것을 자연어로 설명하기 시작한다는 것입니다. 두 가지 계층:
전역 맥락(instruction 매개변수) — 전체 발화의 전반적인 분위기를 설정합니다. v3에서 ≤500자(2.5는 200자; 300자 instruction이 v3에서 수락됨 2026-09-16 확인). 성우에게 무대 지시를 내리는 것으로 생각하세요.
instruction: "克制的悲伤,语气低沉柔弱,像快要消失一样"
인라인 맥락(input 내의 () 괄호) — 문장 내 지시사항. 괄호 안의 내용은 지시사항으로 소비되며 소리내어 읽히지 않습니다. 일시 중지, 호흡, 강조 또는 문장 중간 감정 변화의 정밀한 제어에 사용합니다.
input: "(试探着问)你好吗?(开心地)太好了!(突然沉下来)不过...我快要消失了。"
실제로 작동한 예(2.5에서 2026-04-23 확인, 모든 5개는 v3에서 2026-09-16 재확인, instruction 및 인라인 운율 사례 포함):
instruction: "活泼俏皮,像是在撒娇,带点嘴硬"— 중립에 비해 전달 속도가 눈에 띄게 빨라짐instruction: "耳语声,气声很重,几乎听不清"— 들리는 속삭임/호흡 생성input: "你好(停顿一下)我是蕾格(轻声)今天(加重)的天气真不错。"— 인라인 지시사항 모두 준수
stepaudio-3-tts가 허용하지 않는 것 — voice_label 매개변수. v3 오류: voice_label is not supported for this model(2.5는 ...for v2 models라고 표시). step-tts-2에서 마이그레이션할 때 가장 중요한 함정입니다.
일반적인 오류 패턴(실제 오류, 실제 수정)
| 오류 응답 | 실제 원인 | 수정 |
|---|---|---|
"voice_label is not supported for this model" (v3) / "...for v2 models" (2.5) | 맥락 TTS 모델에 voice_label 전송 | voice_label 제거; 동일한 의도를 자연어로 instruction에 넣음 |
"The content you provided or machine outputted is blocked." type: censorship_block | 민감한 단어(2.5 시대: 死 / 消失 / 등; v3 트리거는 확인되지 않음) | 구문을 다시 작성하거나 특정 라인에 대해 step-tts-2로 대체(혼합 모델 사용 가능) |
| 자동 오디오 잘림(입력 > 1000자) | 하드 상한 초과 | 의미 경계에서 분할; 문장 중간에서 자르지 않음 |
자세한 내용은 references/known_issues.md를 참조하세요.
참고 자료를 읽어야 할 때
references/api_reference.md—/v1/audio/speech의 정확한 요청/응답 JSON, 모든 필드, 오류 응답. 번들 스크립트 대신 원시 HTTP 호출을 작성할 때 읽으세요.references/migration_from_v2.md— step-tts-2 프로젝트를 맥락 TTS로 이동하기 위한 완전한 실행 가이드. 감정→instruction 재작성 표, A/B 디렉터리 전략, 결정 체크포인트, 2026-04 속도/품질 절충 데이터(2.5에 대해 작성됨)가 있습니다. 마이그레이션 작업 전에 읽으세요.references/known_issues.md— 검열 패턴, TTS 지속 시간 증가, v2 제품군 매개변수 명명 문제, 1000자 하드 상한. 2.5 시대 확인; 특정 항목에 의존하기 전에 v3에서 재확인하세요. 비정상적인 출력을 디버깅하거나 채택 여부를 평가할 때 읽으세요.
설계 불변 규칙(이것들을 깨지 마세요)
- 비파괴 A/B 출력 — 새 모델로 코퍼스를 재생성할 때 병렬 디렉터리(
voice/zh_v3/)에 쓰고 프로덕션 코퍼스를 절대 덮어쓰지 마세요. 마이그레이션 실행 가이드가 그 이유를 보여줍니다. - 라인별 검열 처리 — 29개 라인 중 2개가
censorship_block을 받더라도 배치를 실패시키지 마세요. 건너뛴 ID를 기록하고 계속 진행하세요. 혼합 모델 대체(건너뛴 2개에 대해 step-tts-2 사용)는 정상입니다. - 새 코드에 voice_label 로직을 복제하지 마세요 — stepaudio-3-tts를 대상으로 하는 새 TTS 코드는
instruction+ 인라인()만 사용해야 합니다. 조건부로voice_label을 내보내는 분기를 작성하지 마세요.
v3 특정 사실(2026-09-16 확인)
- 공식 음성: 60개 이상 (
GET /v1/audio/system_voices?model=stepaudio-3-tts통해) — 2.5 목록을 완전히 상속하며, 새 음성(예: 영어 이름Lisa/Alfie, 상하이어shanghaifemale/shanghaimale)이 추가됨. - 클론(复刻) 음성:
stepaudio-3-tts를 사용하지 마세요 — 2026-09-16 근본 원인 확인: StepFun의 전체 클론 스택은 여전히 2.5 제품군입니다. 생성 API(POST /v1/audio/voices)는stepaudio-2.5-tts/step-tts-2/step-tts-mini만 허용하며 v3/v1/audio/speech는 모든 클론 ID에 대해 자동으로 기본 여성 음성으로 대체됩니다 — SIM 0.272(step-tts-2 클론) 및 0.195(새 2.5 생성 클론) 대 앵커 0.773; 2.5의 동일 ID는 0.743/0.678입니다. 클론은stepaudio-2.5-tts(최상의 SIM) 또는step-tts-2로 합성하세요. - v3에 WebSocket 스트리밍 없음(2026-09-16 기준):
wss://api.stepfun.com/v1/realtime/audio?model=stepaudio-3-tts는 핸드셰이크에서 거부(404)되며, 2.5는 계속 스트리밍됩니다. v3에서 문자 수준의 자막 타임스탬프가 필요하신가요? RESTtimestamp:true + return_url:true사용(자막은 응답 JSONdata.subtitles[]에 도착, 문자 수준 ms, 누적 절대 축) — 일반stream_format:"audio"는 자막을 전달할 수 없습니다(서버 400).
가격(2026-09-16 확인, 변동 가능)
stepaudio-3-tts합성: 2.5元 / 만자(공식 모델 페이지, 2026-09-16 — 2.5 시대 ~5.8보다 저렴)- 제로샷 음성 클로닝: 9.9元 / 음색
이해 관계자에게 인용하기 전에 https://platform.stepfun.com/docs/zh/guides/pricing/details에서 다시 확인하세요.