> ## Documentation Index > Fetch the complete documentation index at: https://docs.supertoneapi.com/llms.txt > Use this file to discover all available pages before exploring further. # 음성 생성 > 텍스트로부터 완성된 오디오 파일을 생성합니다. 가장 일반적으로 사용되는 Supertone TTS 호출입니다. 요청 필드, 출력 포맷, 응답 구조 및 결과 저장 방법을 다룹니다. 이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 [영어 원문](/en/docs/text-to-speech/create-speech)을 함께 확인해 주세요. `create_speech`는 텍스트를 완성된 오디오 파일로 변환합니다. 전체 오디오가 응답 본문으로 반환되어 곧바로 저장하거나 재생할 수 있습니다. 생성이 끝나기 전에 재생을 시작하는 등, 합성되는 즉시 오디오 청크를 스트리밍해야 하는 경우에는 [Stream speech](/ko/docs/text-to-speech/stream-speech)를 참고해 주십시오. ## 기본 사용법 ```python theme={"dark"} import os from supertone import Supertone VOICE_ID = "20160a4c5ba38967330c84" # replace with your voice ID with Supertone(api_key=os.environ["SUPERTONE_API_KEY"]) as client: response = client.text_to_speech.create_speech( voice_id=VOICE_ID, text="Hello from Supertone.", language="en", model="sona_speech_1", output_format="wav", ) with open("speech.wav", "wb") as f: f.write(response.result.read()) ``` ```typescript theme={"dark"} import { Supertone } from "@supertone/supertone"; import * as fs from "node:fs"; const VOICE_ID = "20160a4c5ba38967330c84"; // replace with your voice ID const client = new Supertone({ apiKey: process.env.SUPERTONE_API_KEY }); const response = await client.textToSpeech.createSpeech({ voiceId: VOICE_ID, apiConvertTextToSpeechUsingCharacterRequest: { text: "Hello from Supertone.", language: "en", model: "sona_speech_1", outputFormat: "wav", }, }); if (response.result instanceof Uint8Array) { fs.writeFileSync("speech.wav", response.result); } else if (response.result && "getReader" in response.result) { const reader = (response.result as ReadableStream).getReader(); const chunks: Uint8Array[] = []; while (true) { const { done, value } = await reader.read(); if (done) break; if (value) chunks.push(value); } fs.writeFileSync("speech.wav", Buffer.concat(chunks)); } ``` ```bash theme={"dark"} VOICE_ID="20160a4c5ba38967330c84" # replace with your voice ID curl -X POST "https://supertoneapi.com/v1/text-to-speech/$VOICE_ID" \ -H "x-sup-api-key: $SUPERTONE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "text": "Hello from Supertone.", "language": "en", "model": "sona_speech_1", "output_format": "wav" }' \ --output speech.wav ``` ## 요청 필드 | Field | Required | Description | | ------------------ | :------: | --------------------------------------------------------------------------------------------------------------------------- | | `voice_id` | ✅ | 경로 파라미터입니다. 캐릭터를 식별합니다. | | `text` | ✅ | 합성할 텍스트입니다. **API 호출당 최대 300자**입니다(SDK는 더 긴 텍스트를 자동으로 분할합니다). | | `language` | ✅ | 언어 코드입니다. 보이스와 모델이 모두 지원해야 합니다. | | `style` | — | 감정 스타일입니다(예: `neutral`, `happy`). 미지정 시 보이스의 `styles` 배열 중 첫 번째 값이 기본으로 적용됩니다. | | `model` | — | TTS 모델입니다. 기본값: `sona_speech_1`. [모델](/ko/docs/core-concepts/models)을 참고해 주십시오. | | `output_format` | — | `wav`(기본값) 또는 `mp3`입니다. 아래 [출력 포맷](#output-formats)을 참고해 주십시오. | | `voice_settings` | — | 피치, 억양, 속도 등을 조정합니다. [Voice settings](/ko/docs/text-to-speech/voice-settings)를 참고해 주십시오. | | `include_phonemes` | — | `true`인 경우 음소 심볼과 타임스탬프를 반환합니다. [Pronunciation and phonemes](/ko/docs/text-to-speech/pronunciation-and-phonemes)를 참고해 주십시오. | | `normalized_text` | — | 발음 정규화된 보조 텍스트입니다(현재 `sona_speech_2` 계열의 일본어용). [Normalized text](/ko/docs/text-to-speech/normalized-text)를 참고해 주십시오. | 전체 스키마는 [Create speech (API reference)](/ko/api-reference/endpoints/text-to-speech)를 참고해 주십시오. ## 출력 포맷 | Format | `output_format` value | Content type | Use when | | --------- | --------------------- | ------------ | -------------------------------------------------------------- | | WAV (기본값) | `wav` | `audio/wav` | 무손실 오디오가 필요할 때 사용합니다. 프로덕션 오디오 파이프라인, 후처리, 게임/애니메이션 에셋에 적합합니다. | | MP3 | `mp3` | `audio/mpeg` | 최종 사용자 기기로 전달할 때 파일 크기를 줄이고 싶고, 무손실 품질이 필요하지 않을 때 사용합니다. | `output_format`을 생략하면 API는 기본값으로 `wav`를 사용합니다. 동일한 옵션이 [Stream speech](/ko/docs/text-to-speech/stream-speech)에도 적용되며, 청크는 요청한 포맷의 바이너리로 반환됩니다. ## 응답 기본적으로 API는 응답 본문에 **바이너리 오디오**를 반환합니다. 응답에는 다음 두 가지 유용한 헤더가 포함됩니다. | Header | Meaning | | ---------------- | ----------------------------------------------------- | | `Content-Type` | `audio/wav` 또는 `audio/mpeg`로, `output_format`과 일치합니다. | | `X-Audio-Length` | 생성된 오디오의 길이(초, float)입니다. | ### `include_phonemes=true`인 경우 음소 타임스탬프를 사용하도록 설정하면 응답이 **JSON으로 전환**되며, base64로 인코딩된 오디오 페이로드와 함께 음소 배열이 포함됩니다. ```json theme={"dark"} { "audio_base64": "UklGRnoGAABXQVZF...", "phonemes": { "symbols": ["", "h", "ɐ", "ɡ", "ʌ", ""], "start_times_seconds": [0, 0.092, 0.197, 0.255, 0.29, 0.58], "durations_seconds": [0.092, 0.104, 0.058, 0.034, 0.29, 0.162] } } ``` 전체 구조는 [Pronunciation and phonemes](/ko/docs/text-to-speech/pronunciation-and-phonemes)를 참고해 주십시오. ## 결과 저장 ```python theme={"dark"} response = client.text_to_speech.create_speech(...) with open("speech.wav", "wb") as f: f.write(response.result.read()) ``` ```typescript theme={"dark"} import * as fs from "node:fs"; const response = await client.textToSpeech.createSpeech(...); if (response.result instanceof Uint8Array) { fs.writeFileSync("speech.wav", response.result); } else if (response.result && "getReader" in response.result) { const reader = (response.result as ReadableStream).getReader(); const chunks: Uint8Array[] = []; while (true) { const { done, value } = await reader.read(); if (done) break; if (value) chunks.push(value); } fs.writeFileSync("speech.wav", Buffer.concat(chunks)); } ``` ## 팁 * **스타일이 중요합니다.** 보이스마다 기본 스타일이 다를 수 있습니다. `style`을 명시적으로 지정하거나, 시작 시 [Get voice](/ko/api-reference/endpoints/get-voice)를 한 번 호출하여 해당 보이스의 기본값을 확인해 주십시오. * **생성 전에 예측하기.** [`predict_duration`](/ko/docs/production/cost-and-usage#predict-duration)은 크레딧을 소모하지 않고 예상 오디오 길이를 반환합니다. UI 힌트나 비용 예측에 유용합니다. * **긴 텍스트.** Raw API는 `text`를 300자로 제한합니다. Python 및 TypeScript SDK는 자동으로 분할, 생성, 병합을 수행합니다. [Long text](/ko/docs/text-to-speech/long-text)를 참고해 주십시오. * **빈 입력이나 매우 짧은 입력**은 부자연스러운 결과를 만들 수 있습니다. 최소한 짧은 완전한 문장 한 개 이상을 입력해 주십시오. ## 관련 문서 빠른 모델과 고품질 TTS 모델 중에서 선택할 수 있습니다. 300자를 초과하는 텍스트로부터 오디오를 생성합니다. 피치, 억양, 속도를 조정합니다. 전체 요청 및 응답 스키마입니다.