음성 생성 - Supertone API Documentation

이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 영어 원문을 함께 확인해 주세요.

create_speech는 텍스트를 완성된 오디오 파일로 변환합니다. 전체 오디오가 응답 본문으로 반환되어 곧바로 저장하거나 재생할 수 있습니다. 생성이 끝나기 전에 재생을 시작하는 등, 합성되는 즉시 오디오 청크를 스트리밍해야 하는 경우에는 Stream speech를 참고해 주십시오.

기본 사용법

Python
TypeScript
cURL

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())

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<Uint8Array>).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));
}

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`. 모델을 참고해 주십시오.
`output_format`	—	`wav`(기본값) 또는 `mp3`입니다. 아래 출력 포맷을 참고해 주십시오.
`voice_settings`	—	피치, 억양, 속도 등을 조정합니다. Voice settings를 참고해 주십시오.
`include_phonemes`	—	`true`인 경우 음소 심볼과 타임스탬프를 반환합니다. Pronunciation and phonemes를 참고해 주십시오.
`normalized_text`	—	발음 정규화된 보조 텍스트입니다(현재 `sona_speech_2` 계열의 일본어용). Normalized text를 참고해 주십시오.

전체 스키마는 Create speech (API reference)를 참고해 주십시오.

출력 포맷

Format	`output_format` value	Content type	Use when
WAV (기본값)	`wav`	`audio/wav`	무손실 오디오가 필요할 때 사용합니다. 프로덕션 오디오 파이프라인, 후처리, 게임/애니메이션 에셋에 적합합니다.
MP3	`mp3`	`audio/mpeg`	최종 사용자 기기로 전달할 때 파일 크기를 줄이고 싶고, 무손실 품질이 필요하지 않을 때 사용합니다.

output_format을 생략하면 API는 기본값으로 wav를 사용합니다. 동일한 옵션이 Stream speech에도 적용되며, 청크는 요청한 포맷의 바이너리로 반환됩니다.

응답

기본적으로 API는 응답 본문에 바이너리 오디오를 반환합니다. 응답에는 다음 두 가지 유용한 헤더가 포함됩니다.

Header	Meaning
`Content-Type`	`audio/wav` 또는 `audio/mpeg`로, `output_format`과 일치합니다.
`X-Audio-Length`	생성된 오디오의 길이(초, float)입니다.

`include_phonemes=true`인 경우

음소 타임스탬프를 사용하도록 설정하면 응답이 JSON으로 전환되며, base64로 인코딩된 오디오 페이로드와 함께 음소 배열이 포함됩니다.

{
  "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를 참고해 주십시오.

결과 저장

Python
TypeScript

response = client.text_to_speech.create_speech(...)
with open("speech.wav", "wb") as f:
    f.write(response.result.read())

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<Uint8Array>).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를 한 번 호출하여 해당 보이스의 기본값을 확인해 주십시오.
생성 전에 예측하기. predict_duration은 크레딧을 소모하지 않고 예상 오디오 길이를 반환합니다. UI 힌트나 비용 예측에 유용합니다.
긴 텍스트. Raw API는 text를 300자로 제한합니다. Python 및 TypeScript SDK는 자동으로 분할, 생성, 병합을 수행합니다. Long text를 참고해 주십시오.
빈 입력이나 매우 짧은 입력은 부자연스러운 결과를 만들 수 있습니다. 최소한 짧은 완전한 문장 한 개 이상을 입력해 주십시오.

모델 선택

빠른 모델과 고품질 TTS 모델 중에서 선택할 수 있습니다.

긴 텍스트

300자를 초과하는 텍스트로부터 오디오를 생성합니다.

보이스 설정

피치, 억양, 속도를 조정합니다.

API 레퍼런스

전체 요청 및 응답 스키마입니다.

​기본 사용법

​요청 필드

​출력 포맷

​응답

​include_phonemes=true인 경우

​결과 저장

​팁

​관련 문서

모델 선택

긴 텍스트

보이스 설정

API 레퍼런스

기본 사용법

요청 필드

출력 포맷

응답

`include_phonemes=true`인 경우

결과 저장

팁

관련 문서