TTS API 연동 및 사용 가이드

작성자 Tykitys Access 편집팀 · 업데이트됨 2026-11-19

이 페이지에서는 Tykitys Access TTS API를 연동하고 활용하는 방법을 안내합니다. 시각적 피로나 학습 장애가 있는 독자를 위한 텍스트 음성 변환 서비스를 구축하는 출판사와 개발자를 위해, API 키 발급부터 실제 코드 작성까지 단계별로 정리했습니다. 복잡한 설정 없이 표준 JSON 형식과 OpenAI SDK 호환성을 활용해 빠르게 통합할 수 있습니다.

문자 제한, 속도 제한, 지원 언어 및 목소리 목록과 같은 핵심 규정을 명확히 확인하세요. curl 예제와 Python 코드 샘플을 통해 첫 번째 요청을 바로 테스트하고, 에러 처리 및 결제 정보까지 한 번에 파악할 수 있습니다. 이 가이드는 API 연동에 필요한 모든 기술적 세부사항을 포함되어 있습니다.

TTS API 연동 및 사용 가이드

자주 묻는 질문

API 키는 어떻게 얻나요?

홈페이지의 /get-api-key/ 페이지에서 Google 또는 이메일로 가입하세요. 계정 생성 시 API 키가 즉시 발급되며, 필요 시 기존 키를 폐기하고 새 키를 언제든지 발행할 수 있습니다. 각 사이트별 독립 계정이므로 해당 도메인에서 직접 관리하시면 됩니다.

curl 예제는 어디에 있나요?

API 키 발급 페이지(/get-api-key/)에서 바로 사용 가능한 curl 예제를 확인하실 수 있습니다. 페이지에는 키, 잔액, 사용량 정보가 함께 표시되며, 복사하여 즉시 테스트할 수 있도록 준비되어 있습니다.

오픈AI SDK를 사용할 수 있나요?

네, 요청 형식이 OpenAI 스피치 엔드포인트와 동일하므로 공식 OpenAI SDK를 사용할 수 있습니다. base_url을 https://api.tykitys.info/v1로 변경하고 발급받은 API 키를 인증 헤더에 설정하면 바로 연동할 수 있습니다.

base_url은 어떻게 변경하나요?

OpenAI SDK를 사용 중이라면 base_url을 https://api.tykitys.info/v1로 변경하세요. 그 후 Authorization 헤더에 'Bearer tts-...' 형식의 API 키를 설정하면 동일한 요청 방식으로 음성 생성 API를 호출할 수 있습니다.

지원되는 모델은 무엇인가요?

tts-1과 tts-1-hd 두 가지 모델을 지원합니다. 두 모델은 동일한 엔진을 사용하며 가격도 동일합니다. 요청 시 model 필드에 이 중 하나를 지정하면 됩니다. 모델에 따라 음질이나 가격 차이는 없습니다.

응답 형식은 어떻게 되나요?

성공적인 요청 시 오디오 파일이 응답 본문에 직접 반환됩니다. mp3, wav, opus, flac, pcm 중 response_format으로 원하는 형식을 지정할 수 있으며, 지정하지 않을 경우 기본값이 적용됩니다. 실패 시에는 관련 에러 메시지가 반환됩니다.

에러 메시지는 어떻게 해석하나요?

응답 상태 코드를 확인하세요. 일반적으로 4xx는 인증 오류나 잘못된 요청을 의미합니다. 요청 제한(60회/분)을 초과했거나 텍스트가 4096자를 넘었을 때에도 에러가 발생할 수 있습니다. JSON 응답의 error 필드에서 상세 원인을 확인하세요.

요청 제한은 어떻게 되나요?

API 키당 분당 60회까지 요청할 수 있습니다. 첫 충전 전에는 분당 10회로 제한됩니다. 긴 텍스트는 4096자 단위로 나누어 요청하므로, 실제 처리 시간에는 영향을 미칠 수 있으나 요청 횟수 제한은 동일하게 적용됩니다.

스트리밍은 지원되나요?

아니요, 스트리밍은 지원되지 않습니다. 텍스트를 전송하면 전체 음성 합성 완료 후 오디오 파일이 반환됩니다. 실시간 부분 오디오나 웹소켓 연결은 제공되지 않으므로, 전체 파일 다운로드 후 재생하는 방식을 사용해야 합니다.

SSML은 지원되나요?

아니요, SSML은 지원되지 않습니다. 음성의 억양이나 발음 기호를 세밀하게 제어하려면 SSML이 필요하지만, 본 API는 기본 텍스트만 입력받아 처리합니다. 속도와 목소리 설정 외에 추가적인 음성 제어 기능은 현재 제공하지 않습니다.

언어는 어떻게 설정하나요?

language 파라미터에 ISO 코드를 지정하세요. 지정하지 않으면 스크립트 기반으로 언어가 추측됩니다. 라틴 문자 텍스트는 기본적으로 영어로 간주되므로, 영어가 아닌 다른 라틴 문자 언어일 경우 반드시 language 필드를 명시적으로 설정해야 합니다.

속도는 어떻게 조절하나요?

speed 파라미터를 0.25에서 4.0 사이로 설정하여 속도를 조절할 수 있습니다. 기본값은 1.0이며, 이 값을 높이면 음성이 빨라지고 낮으면 느려집니다. 텍스트의 길이에 따라 생성 시간도 비례하여 증가하거나 감소합니다.

오디오 형식은 어떻게 선택하나요?

response_format 파라미터에 mp3, wav, opus, flac, pcm 중 하나를 지정하세요. 파일 크기와 품질 요구 사항에 따라 적절한 형식을 선택하면 됩니다. mp3는 일반적인 사용에 적합하며, wav나 flac은 원본 품질이 필요할 때 유용합니다.

데이터는 어떻게 처리되나요?

입력 텍스트는 음성 생성에만 사용되며 학습 데이터로 활용되지 않습니다. 생성된 오디오는 응답으로 반환되며 서버에 저장되지 않습니다. 청구 목적으로 요청 시간, 문자 수, 상태 등의 메타데이터만 보관됩니다.

가격은 어떻게 계산되나요?

100만 문자당 $10 ($0.01/1,000자)의 요금이 부과됩니다. 공백과 구두점도 문자 수에 포함됩니다. 실패한 요청의 경우 요금이 전액 환불됩니다.

무료 체험은 어떻게 받나요?

Google로 가입 시 $0.50의 무료 체험 크레딧(약 50,000자)이 7일 동안 제공됩니다. 이메일과 비밀번호로 가입한 계정은 초기 크레딧이 없습니다. 체험 기간 내에는 제한 없이 API를 테스트할 수 있습니다.

USDT로 충전하는 방법은?

TRON 네트워크(TRC-20)의 USDT로만 충전이 가능합니다. 최소 충전 금액은 $5이며, 송금 후 몇 분 내에 자동으로 잔액이 충전됩니다. 신용카드나 페이팔은 지원되지 않으며, 인보이스나 부가세 처리도 이루어지지 않습니다.

지원되는 언어는 무엇인가요?

아랍어, 중국어, 덴마크어, 네덜란드어, 영어, 핀란드어, 프랑스어, 독일어, 그리스어, 히브리어, 힌디어, 이탈리아어, 일본어, 한국어, 말레이어, 노르웨이어, 폴란드어, 포르투갈어, 러시아어, 스페인어, 스와힐리어, 스웨덴어, 터키어 등 23개 언어를 지원합니다.

목소리는 어떻게 선택하나요?

voice 파라미터에 8가지 프리셋 중 하나를 지정하세요. aria, nova, luna, sage(여성)와 felix, milo, atlas, orion(남성)이 있습니다. 각 목소리는 특정한 톤과 분위기를 가지고 있으며, GET /v1/voices 엔드포인트에서 상세 정보를 확인할 수 있습니다.

첫 번째 요청

curl

curl https://api.tykitys.info/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.tykitys.info/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.tykitys.info/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
aria여성
nova여성
luna여성
sage여성
felix남성
milo남성
atlas남성
orion남성
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

API 키 발급

에 대한 소리 파동 일러스트레이션: API 키 발급

Tykitys Access API를 사용하려면 먼저 계정이 필요합니다. /get-api-key/ 페이지에서 Google 또는 이메일로 간편하게 가입할 수 있습니다. Google 로그인은 즉시 $0.50(약 50,000자)의 무료 체험 크레딧을 제공하며, 이메일 가입은 기본 계정으로 생성됩니다.

계정 생성이 완료되면 대시보드에서 API 키를 확인하고 사용할 준비가 됩니다.

계정 만들기

Tykitys Access는 출판사와 접근성 서비스에 특화된 플랫폼입니다. 가입은 사이트의 /get-api-key/ 페이지에서 진행되며, Google 계정 연동 시 바로 체험 크레딧을 받을 수 있습니다.

키 생성

계정 생성과 동시에 고유한 API 키가 발급됩니다. 이 키는 Authorization 헤더에 Bearer tts-... 형식으로 포함되어 인증에 사용됩니다. 키는 계정당 하나만 활성화됩니다.

키 관리

보안을 위해 기존 키를 무효화하고 새 키를 발급할 수 있습니다. 새 키를 생성하면 이전 키는 즉시 사용 불가 처리됩니다. 대시보드에서 현재 키 상태와 남은 크레딧을 실시간으로 확인할 수 있습니다.

첫 번째 요청

에 대한 소리 파동 일러스트레이션: 첫 번째 요청

API를 연동하여 텍스트를 음성으로 변환하는 첫 번째 단계를 확인하세요. 인증 키를 사용하여 API 엔드포인트에 요청을 보내면 오디오 파일이 반환됩니다.

아래 curl 예제와 JSON 구조를 참고하여 실제 연동을 테스트해 보세요. 실패한 요청은 요금이 부과되지 않습니다.

curl 예제

가장 빠른 테스트 방법은 curl 명령어를 사용하는 것입니다. 아래 명령어는 'tts-1' 모델을 사용하여 텍스트를 음성으로 변환합니다.

curl -X POST https://api.tykitys.info/v1/audio/speech -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model": "tts-1", "input": "안녕하세요, 이것은 테스트 음성입니다.", "voice": "aria"}'

JSON 요청

요청 본문은 JSON 형식이어야 합니다. 필수 필드는 model, input, voice입니다. input은 최대 4,096자까지 가능하고, spaces와 punctuation도 문자 수에 포함됩니다.

model은 'tts-1' 또는 'tts-1-hd'를 선택할 수 있으며 엔진과 가격은 동일합니다. voice는 aria, nova, luna 등 8가지 프리셋 중 하나여야 합니다.

  • model: tts-1 또는 tts-1-hd
  • input: 변환할 텍스트 (최대 4,096자)
  • voice: aria, nova, luna, sage, felix, milo, atlas, orion

응답 예제

성공적인 요청은 바이너리 오디오 파일을 반환합니다. 기본 응답 형식은 mp3이며, opus, wav, flac, pcm도 지원됩니다.

오디오 파일은 직접 다운로드하거나 저장할 수 있습니다. 요청 처리 시간은 텍스트 길이에 따라 다르며, 짧은 문장도 몇 초이 걸릴 수 있습니다.

오픈AI SDK 사용

에 대한 소리 파동 일러스트레이션: 오픈AI SDK 사용

Tykitys API는 OpenAI speech 엔드포인트와 동일한 형식을 따르므로, 기존 OpenAI SDK를 그대로 사용할 수 있습니다. base_url을 Tykitys API 주소로 변경하기만 하면 연동이 완료됩니다.

이 방식은 OpenAI SDK를 설치하여 Python, Node.js 등 다양한 환경에서 빠르게 테스트할 수 있게 해줍니다.

base_url 변경

요청 시 base_url을 https://api.tykitys.info/v1로 설정합니다. 이 설정만 변경하면 인증 키와 요청 형식은 기존 OpenAI SDK와 호환됩니다.

SDK 설치

가장 일반적인 Python 환경의 경우 openai 패키지를 설치하면 됩니다. pip install openai 명령어로 간단히 설치할 수 있습니다.

다른 언어 SDK도 동일하게 구성하며, 인증은 Bearer 토큰을 통해 처리됩니다.

코드 예제

다음 Python 코드는 TTS 요청을 보내는 기본 예제입니다.

from openai import OpenAI client = OpenAI( base_url="https://api.tykitys.info/v1", api_key="tts-your-api-key" ) with client.audio.speech.create( model="tts-1", voice="nova", input="시청각 장애 독자를 위한 텍스트 음성 변환 테스트입니다.", ) as response: with open("output.mp3", "wb") as f: f.write(response.content)

엔드포인트

에 대한 소리 파동 일러스트레이션: 엔드포인트

API는 세 가지 주요 엔드포인트를 제공합니다. 음성 합성 요청은 POST /v1/audio/speech로 처리되며, 사용 가능한 목소리와 모델 목록은 GET /v1/voices와 GET /v1/models에서 확인할 수 있습니다.

POST /v1/audio/speech

텍스트를 오디오 파일로 변환하는 핵심 엔드포인트입니다. JSON 형식으로 모델, 입력 텍스트, 목소리 등을 지정하여 요청합니다.

  • Endpoint: POST https://api.tykitys.info/v1/audio/speech
  • Body: JSON (model, input, voice, response_format, speed)

GET /v1/voices

지원하는 8가지 목소리와 23개 언어 목록을 반환합니다. 각 목소리의 특성과 사용 가능한 포맷을 확인하는 데 유용합니다.

  • Endpoint: GET https://api.tykitys.info/v1/voices
  • Returns: List of voices, languages, and formats

GET /v1/models

사용 가능한 모델(tts-1, tts-1-hd) 정보를 반환합니다. 두 모델은 동일한 엔진과 가격을 가집니다.

  • Endpoint: GET https://api.tykitys.info/v1/models
  • Returns: Available model details

요청 필드

에 대한 소리 파동 일러스트레이션: 요청 필드

API 호출 시 필수로 설정해야 하는 요청 필드들을 설명합니다. 각 필드는 변환할 오디오의 품질과 형식을 결정합니다.

model

"tts-1" 또는 "tts-1-hd" 중 하나를 선택합니다. 두 모델은 동일한 엔진을 사용하며 가격도 동일합니다.

input

음성으로 변환할 텍스트를 입력합니다. 한 번의 요청당 최대 4,096자까지 가능합니다. 공백과 구두점도 문자 수에 포함됩니다.

voice

8가지 미리 설정된 목소리 중 하나를 선택합니다. Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion 중 하나를 사용할 수 있습니다.

response_format

출력 오디오의 형식을 지정합니다. mp3, wav, opus, flac, pcm 중 하나를 선택할 수 있습니다.

응답 형식

에 대한 소리 파동 일러스트레이션: 응답 형식

API는 성공적인 요청에 대해 오디오 파일 자체를 직접 반환합니다. MP3, WAV, FLAC 등 요청 시 지정한 형식으로 응답이 전송되며, 별도의 파일 첨부나 복잡한 파싱 없이 바로 저장하거나 재생할 수 있습니다.

오디오 파일

응답 본문은 요청에서 선택한 형식(mp3, wav, opus, flac, pcm)의 바이너리 데이터입니다. 생성된 오디오에는 합성 음성을 나타내는 무청수 마크가 포함되어 있습니다.

에러 메시지

상태 코드

응답 형식

제한 사항

에 대한 소리 파동 일러스트레이션: 제한 사항

API는 요청을 순차적으로 처리합니다. 따라서 요청이 많아지면 대기 시간이 발생할 수 있습니다.

문자 제한

한 번의 요청으로 최대 4,096자까지 변환할 수 있습니다. 이를 초과하는 긴 텍스트는 여러 부분으로 나누어 처리한 후 오디오 파일을 연결해야 합니다.

속도 제한

API 키당 분당 60회까지 요청이 가능합니다. 첫 충전 전에는 분당 10회로 제한됩니다.

동시 요청

API는 요청을 순차적으로 처리합니다. 따라서 요청이 많아지면 대기 시간이 발생할 수 있습니다.

자주 묻는 질문

에 대한 소리 파동 일러스트레이션: 자주 묻는 질문

API 연동 중 발생할 수 있는 일반적인 문제와 해결 방법을 정리했습니다. 안정적인 서비스 이용을 위해 에러 처리와 재시도 로직을 확인해 주세요.

버전 관리 정책은 현재 v1을 기준으로 안정화되어 있으며, 주요 변경사항은 별도 안내됩니다.

에러 처리

요청 실패 시에도 요금이 부과되지 않습니다. 응답 상태 코드가 4xx 또는 5xx일 경우, JSON 응답 본문에 상세 오류 메시지가 포함되어 있으므로 이를 확인해 주세요. 예를 들어, 문자 수 제한 초과나 유효하지 않은 모델 이름 오류가 발생하면 해당 메시지를 참고하여 요청을 수정하세요.

  • 실패한 요청은 요금이 반환됩니다.
  • 오류 메시지는 JSON 형식으로 반환됩니다.

재시도

일시적인 서버 과부하로 인해 요청이 대기열에 쌓일 수 있습니다. 이 경우 503 상태 코드가 반환되므로, 지수 백오프(exponential backoff) 전략을 사용하여 잠시 후 재시도하는 것을 권장합니다. 짧은 문장은 생성에 몇 초가 걸릴 수 있으므로, 적절한 대기 시간을 설정하세요.

  • 503 에러 시 재시도 권장
  • 지수 백오프 전략 사용

버전 관리

현재 API는 v1을 기준으로 안정화되어 제공됩니다. 주요 엔드포인트 구조와 필드는 변경되지 않을 예정입니다. 향후 호환성 깨짐 변경이 필요할 경우, 별도 안내를 통해 이전 버전의 지원 기간을 공지하겠습니다.

  • 현재 버전: v1
  • 주요 변경 시 별도 공지

가격 및 결제

에 대한 소리 파동 일러스트레이션: 가격 및 결제

Tykitys Access는 복잡한 구독이나 최소 사용량 없이 문자 단위 과금을 제공합니다. 100만 문자당 $10의 정산 가격으로, 실패한 요청은 요금이 청구되지 않습니다.

요금제

$10/100만 문자 ($0.01/1000자)의 단일 요금제를 사용합니다. 월 정액제나 seats 없이 실제 생성된 문자 수만큼만 결제됩니다.

  • 100만 문자당 $10
  • 실패 시 전액 환불
  • 최소 사용량 없음

무료 체험

Google 로그인은 $0.50의 체험 크레딧(약 50,000자)을 7일간 제공합니다. 이메일 가입은 체험금을 지원하지 않습니다. 잔액은 만료되지 않습니다.

USDT 충전

TRON(TRC-20) 네트워크를 통한 USDT 충전만 지원합니다. 최소 충전 금액은 $5이며, 전송 후 몇 분 내에 자동 입금됩니다. 신용카드나 PayPal은 지원되지 않습니다.

  • TRC-20 USDT 전용
  • 최소 $5 충전
  • 자동 입금

지원 언어 및 목소리

에 대한 소리 파동 일러스트레이션: 지원 언어 및 목소리

23개 언어를 지원하며, 아라비아어에서 터키어까지 광범위한 음성을 제공합니다. 모든 목소리는 23개 언어 모두에서 자연스러운 발음으로 작동합니다.

23개 언어 지원

아라비아어, 중국어, 덴마크어, 네덜란드어, 영어, 핀란드어, 프랑스어, 독일어, 그리스어, 히브리어, 힌디어, 이탈리아어, 일본어, 한국어, 말레이어, 노르웨이어, 폴란드어, 포르투갈어, 러시아어, 스페인어, 스와힐리어, 스웨덴어, 터키어를 지원합니다. 베트남어, 인도네시아어, 태국어, 우크라이나어 등은 아직 지원되지 않습니다.

8가지 목소리

8가지 미리 설정된 목소리 중 하나를 선택할 수 있습니다. Aria는 따뜻하고 명확한 내레이터, Nova는 밝고 경쾌한 톤을 제공합니다. Luna는 부드러운 스토리텔링, Sage는 차분한 안내형 성격을 띱니다. Felix는 에너지가 넘치는 홍보용, Milo는 친근한 대화체, Atlas는 중립적인 뉴스, Orion은 깊고 다큐멘터리 같은 목소리를냅니다.

  • Aria: 따뜻하고 명확한 내레이터
  • Nova: 밝고 경쾌한 분위기
  • Luna: 부드러운 스토리텔링
  • Sage: 차분한 안내형
  • Felix: 에너지 넘치는 홍보
  • Milo: 친근한 대화체
  • Atlas: 중립적인 뉴스
  • Orion: 깊고 다큐멘터리 톤

언어 설정

언어 코드를 명시적으로 설정하지 않으면 텍스트의 문자에 따라 언어가 자동으로 감지됩니다. 라틴 문자 텍스트의 경우 기본적으로 영어로 처리되므로, 영어 외의 라틴 문자 텍스트는 반드시 language 필드를 설정해야 합니다.

8개 음성 듣기

아래의 각 샘플은 동일한 문장을 이 API로 생성한 것입니다. 짧은 문장은 몇 초, 긴 텍스트는 실시간 생성 속도에 맞춰 처리되며, 부하가 걸리면 요청이 큐에 쌓일 수 있습니다.

음성 아바타 aria
aria여성
음성 아바타 nova
nova여성
음성 아바타 luna
luna여성
음성 아바타 sage
sage여성
음성 아바타 felix
felix남성
음성 아바타 milo
milo남성
음성 아바타 atlas
atlas남성
음성 아바타 orion
orion남성

23개 언어

모든 음성은 이 언어들을 구사합니다.

출처 및 참고 자료

  1. Wikipedia
  2. LibriTTS-R corpus (OpenSLR 141)
  3. W3C WAI: making audio and video accessible
  4. Node.js documentation
  5. curl documentation
  6. MDN: Web Speech API
  7. OpenAI API reference: create speech
  8. openai-node on GitHub
  9. Creative Commons Attribution 4.0
  10. Python documentation
  11. LibriVox public-domain audiobooks
  12. IETF RFC 7845: Ogg Opus

이 사이트의 다른 콘텐츠