API 레퍼런스

기본 URL https://api.vocallab.ai. 모든 요청에는 Authorization: Bearer vl_live_...가 필요합니다(API 키 참조).

GET /api/v1/ping

연결 + 인증 테스트. 포인트 잔액을 반환합니다.

{ "ok": true, "points": 12345, "unit": "points (1 pt ≈ 1 second of audio)" }

GET /api/v1/voices

사용할 수 있는 음성 — 공개 카탈로그와 내가 만든 클론 및 디자인 음성. 반환된 id를 생성 시 voice로 사용하세요. 카탈로그 음성은 slug도 사용할 수 있습니다.

{ "voices": [
  { "id": "Ashley", "slug": "warm-natural-female-explainer-voice-for-youtube-podcasts",
    "name": "Warm Natural Female Explainer Voice for YouTube & Podcasts",
    "type": "preset", "languages": ["en"], "category": "Narration" },
  { "id": "default-abc123__my-voice", "name": "My Narrator", "type": "clone", "languages": ["en"] }
] }

GET /api/v1/models

선택 가능한 음성 모델. POST /api/v1/tts에서 key를 model로 전달하세요(기본값 v-pro). API 키는 세 가지 모두 사용할 수 있습니다. 차이점은 음성 모델을 참조하세요.

{ "default": "v-pro", "models": [
  { "key": "v-studio", "label": "VocalLab Studio", "steerable": true,  "costMultiplier": 1 },
  { "key": "v-pro",    "label": "VocalLab Pro",    "steerable": false, "costMultiplier": 1 },
  { "key": "v-lite",   "label": "VocalLab Lite",   "steerable": false, "costMultiplier": 0.5 }
] }

POST /api/v1/tts

음성을 생성합니다.

필드	필수	설명
`text`	예	최대 2,000자. 각 호출은 단일 요청으로 합성됩니다 — 긴 스크립트는 텍스트를 나눠 여러 번 호출하세요
`voice`	예	`/api/v1/voices`의 음성 `id`
`model`	아니요	`v-studio`(최신, 스티어링 가능, 200개 이상 언어), `v-pro`(기본값 — 최고 음질, 15개 언어), 또는 `v-lite`(빠름, ½ 포인트). `GET /api/v1/models` 참조
`speed`	아니요	숫자 `0.5`–`1.5` (단위 `0.05`). 생략 시 음성 기본값
`temperature`	아니요	숫자 `0.7`–`1.5` (단위 `0.05`). 값이 클수록 더 표현적이고 가변적. 생략 시 음성 기본값
`format`	아니요	`MP3`(기본값), `WAV`, `FLAC`, `OGG_OPUS`, `LINEAR16`, `PCM`, `ALAW`, `MULAW` 중 하나
`bit_rate`	아니요	정수 `32000`–`320000`. `MP3`와 `OGG_OPUS`에만 적용(다른 형식에서는 무시)
`sample_rate`	아니요	`8000`, `16000`, `22050`, `24000`, `32000`, `44100`, `48000` (Hz) 중 하나

curl -X POST https://api.vocallab.ai/api/v1/tts \
  -H "Authorization: Bearer vl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from VocalLab","voice":"Ashley"}'

오디오를 인라인(base64)으로 반환하고 id를 함께 제공합니다. 호스팅 URL은 업로드가 완료되면 나타납니다. GET /api/v1/tts/:id로 폴링하세요.

각 요청은 2,000자로 제한되며 정확히 하나의 음성 합성으로 매핑됩니다 — 숨겨진 분할이나 팬아웃이 없어 호출당 비용과 지연 시간이 예측 가능하게 유지됩니다. 요청은 포인트 잔액에서 측정되며 공정 사용 큐를 통해 실행되므로 과도한 자동화가 앱을 차단하지 않습니다. 더 긴 스크립트를 읽으려면 2,000자 이하로 나눠 별도의 호출로 전송하세요(분당 60회 속도 제한 준수).

{ "id": "...", "status": "pending", "audio_base64": "data:audio/mp3;base64,...",
  "audio_url": null, "format": "MP3", "model": "v-pro", "points_used": 12 }

모델 및 비용. v-lite는 v-pro/v-studio의 절반 포인트로 청구됩니다(points = ⌈ characters ÷ 30 ⌉, ÷ 15 대신). v-studio는 표현/스티어링 지시를 따르는 유일한 모델입니다 — 음성 모델과 음성 스티어링을 참조하세요.

일시정지

text 안에 자체 닫힘 <break /> 태그를 넣으면 정확한 길이의 무음을 삽입할 수 있습니다:

{ "text": "잠시 생각해 볼게요 <break time=\"1.5s\" /> 네, 생각해 봤습니다.", "voice": "Ashley" }

초 또는 밀리초 — 1.5s = 1500ms.
요청당 최대 20개의 break 태그, 지원되는 모든 언어에서 사용 가능.
break 태그는 2,000자 제한에 포함되며 자막/SRT에서는 제거됩니다.

GET /api/v1/tts/:id

생성 상태와 준비되면 제공되는 호스팅 오디오 URL.

{ "id": "...", "status": "ready", "audio_url": "https://...", "format": "MP3" }

GET /api/v1/me

포인트 잔액과 플랜.

오류

상태	의미
`401`	API 키 누락 또는 잘못됨
`402`	포인트 부족
`403`	Studio 플랜이 아님
`413`	텍스트가 너무 김
`429`	속도 제한 도달 (키당 분당 60회)

오류는 { "error": { "code": "...", "message": "..." } } 형태입니다.

가격

생성은 포인트 잔액에서 청구되며, 텍스트 길이(최종 오디오 길이가 아님)를 기준으로 계산됩니다:

points = ⌈ characters ÷ 15 ⌉      (API 요율 — 포인트당 약 15자)

⌈ ⌉는 다음 정수 포인트로 올림합니다. 웹 앱은 포인트당 17자를 사용하므로 API에는 소폭(~13%)의 프리미엄이 붙습니다. 포인트는 업스트림 호출 전에 측정됩니다 — 잔액을 초과하는 요청은 402를 반환하며 생성되지 않습니다. 각 응답에는 정확한 points_used가 포함됩니다. 음성은 평균 초당 ~15–17자이므로 1포인트 ≈ 오디오 1초이지만, 정확한 청구는 항상 위 공식을 따릅니다. 자세한 내용은 크레딧 및 분을 참조하세요.