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도 받습니다.

모든 응답에 total, count, offset, has_more가 포함되므로 추측 없이 페이징할 수 있습니다. type을 제외한 같은 파라미터가 GET /api/v1/voices/clones와 GET /api/v1/voices/designs에서도 동작합니다.

curl "https://api.vocallab.ai/api/v1/voices?q=narrator&limit=20" \
  -H "Authorization: Bearer vl_live_..."

{ "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,
    "supportsTemperature": false, "supportsDeliveryMode": true },
  { "key": "v-flash",  "label": "VocalLab Studio Flash", "steerable": false, "costMultiplier": 0.75,
    "supportsTemperature": false, "supportsDeliveryMode": false },
  { "key": "v-pro",    "label": "VocalLab Pro",          "steerable": false, "costMultiplier": 1,
    "supportsTemperature": true,  "supportsDeliveryMode": false },
  { "key": "v-lite",   "label": "VocalLab Lite",         "steerable": false, "costMultiplier": 0.5,
    "supportsTemperature": true,  "supportsDeliveryMode": false }
] }

POST /api/v1/tts

음성을 생성합니다.

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회, Max는 120회의 속도 제한 준수).

{ "id": "...", "status": "pending", "audio_base64": "data:audio/mp3;base64,...",
  "audio_url": null, "stream_url": "https://api.vocallab.ai/api/v1/tts/.../audio",
  "captions_url": "https://api.vocallab.ai/api/v1/tts/.../captions",
  "format": "MP3", "model": "v-pro", "points_used": 12 }

모델 및 비용. v-flash는 ¾(points = ⌈ characters ÷ 20 ⌉), v-lite는 절반(÷ 30) 포인트로 청구됩니다(v-pro/v-studio는 ÷ 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://...",
  "stream_url": "https://api.vocallab.ai/api/v1/tts/.../audio",
  "captions_url": "https://api.vocallab.ai/api/v1/tts/.../captions", "format": "MP3" }

GET /api/v1/tts/:id/audio

완성된 클립의 오디오 바이트를 직접 스트리밍합니다. base64 audio_base64 블롭의 대안입니다. inline으로 제공되어(브라우저나 미디어 플레이어에서 재생) HTTP Range 헤더를 지원하므로 탐색할 수 있습니다. 클립이 아직 마무리되는 동안에는 409를 반환합니다. GET /api/v1/tts/:id를 폴링하여 status가 ready가 될 때까지 기다린 후 스트리밍하세요.

curl -L https://api.vocallab.ai/api/v1/tts/GENERATION_ID/audio \
  -H "Authorization: Bearer vl_live_..." \
  -o speech.mp3

동일한 링크가 POST /api/v1/tts와 GET /api/v1/tts/:id의 stream_url로도 반환됩니다.

GET /api/v1/tts/:id/captions

생성된 음성의 자막을 .srt 파일로 반환합니다. 큐는 실제 발화에 맞춰(합성과 함께 반환되는 단어 단위 타이밍으로) 만들어지며, [emotion] 마크업이나 <break /> 일시정지는 모두 제거되어 실제로 말한 단어만 파일에 들어갑니다.

자막은 오디오 파일이 아니라 저장된 타이밍으로 만들어지므로 status가 아직 pending인 동안에도 바로 사용할 수 있습니다.

curl -L "https://api.vocallab.ai/api/v1/tts/GENERATION_ID/captions" \
  -H "Authorization: Bearer vl_live_..." \
  -o speech.srt

1
00:00:00,000 --> 00:00:01,240
Hello from VocalLab,

2
00:00:01,240 --> 00:00:03,100
this is your narrator speaking.

format=json인 경우:

{ "id": "...", "mode": "phrase", "duration": 3.1,
  "srt": "1\n00:00:00,000 --> 00:00:01,240\nHello from VocalLab,\n\n...",
  "words": [ { "word": "Hello", "start": 0, "end": 0.32 } ] }

동일한 링크가 POST /api/v1/tts와 GET /api/v1/tts/:id의 captions_url로도 반환됩니다. 한 번의 호출로 오디오와 SRT를 함께 받으려면 POST /api/v1/tts에 "captions": true를 보내세요.

저장된 단어 타이밍이 없는 생성(일부 오래된 클립)에는 409 captions_unavailable을 반환합니다. 오디오에는 영향이 없습니다.

DELETE /api/v1/tts/:id

본인이 소유한 생성을 영구적으로 삭제합니다. 저장된 오디오 파일과 데이터베이스 레코드를 모두 삭제합니다. 다운로드 후 정리하거나 데이터 삭제 요청을 처리할 때 유용합니다. 존재하지 않거나 본인의 것이 아닌 id는 404를 반환합니다.

curl -X DELETE https://api.vocallab.ai/api/v1/tts/GENERATION_ID \
  -H "Authorization: Bearer vl_live_..."

{ "ok": true, "id": "...", "deleted": true }

GET /api/v1/voices/languages

변경 사항: GET /api/v1/voices/languages는 이제 470개가 넘는 언어와 액센트 변형(en-GB, pt-PT 등)을 반환합니다. code는 BCP-47 태그입니다. 기존 값(EN_US, PT_BR 등)과 Other도 계속 사용할 수 있습니다.

복제와 음성 디자인에 적용되는 언어와 녹음 제한입니다. 목록을 코드에 고정하지 말고 이 엔드포인트를 호출하세요 — Studio 업로드 폼이 사용하는 것과 같은 원본입니다.

{ "languages": [
    { "name": "English", "code": "EN_US", "experimental": false },
    { "name": "Other",   "code": "AUTO",  "experimental": true }
  ],
  "sample_limits": { "max_samples": 1, "max_base64_length": 4194304,
                     "allowed_formats": ["mp3", "wav", "webm"] } }

음성 디자인

녹음 없이 글로 쓴 설명만으로 완전히 새로운 목소리를 만듭니다. 두 번의 호출입니다: 후보 미리듣기를 만들고, 마음에 드는 것을 저장합니다.

POST /api/v1/voices/designs/previews

최대 3개의 후보 보이스를 생성합니다. points가 차감됩니다 — 각 미리듣기는 preview_text의 실제 합성이며 API 요율(미리듣기당 ⌈문자 수 ÷ 15⌉)로 과금됩니다.

아직 저장되는 것은 없으므로 디자인 슬롯을 사용하지는 않지만, 빈 슬롯이 하나 필요합니다. 디자인이 이미 플랜 한도에 도달했다면 409 design_limit을 반환하고 points는 전혀 차감되지 않습니다 — 저장할 수 없는 목소리에 비용을 낼 이유가 없기 때문입니다.

curl -X POST https://api.vocallab.ai/api/v1/voices/designs/previews \
  -H "Authorization: Bearer vl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A warm, unhurried British woman in her forties, low and reassuring, like a documentary narrator.","count":2}'

{ "previews": [
    { "preview_id": "...", "text": "Hello! This is a preview of my voice...",
      "preview_url": "https://api.vocallab.ai/api/v1/audio/..." }
  ],
  "points_used": 12, "expires_in": 1800 }

preview_id는 아직 사용할 수 있는 보이스가 아니며, 약 30분 동안 유효합니다.

저장하지 않은 미리듣기는 폐기됩니다. 새 세트를 만들기 전에 원하는 것을 저장하세요 — 이 엔드포인트를 다시 호출하면 이전 미리듣기가 폐기되어 preview_url이 동작하지 않게 되고, 하나를 저장하면 같은 배치의 나머지가 폐기됩니다. 어느 쪽이든 남는 것은 없습니다.

POST /api/v1/voices/designs

미리듣기를 영구 보이스로 저장합니다. points는 들지 않지만(미리듣기에서 이미 과금) 플랜의 디자인 슬롯을 하나 사용합니다. 반환된 id는 POST /api/v1/tts의 voice로 바로 쓸 수 있습니다.

{ "id": "default-abc123__narrator", "name": "Documentary Narrator", "type": "designed",
  "languages": ["EN_US"], "created_at": "...",
  "preview_url": "https://api.vocallab.ai/api/v1/audio/...", "used": 3, "limit": 20 }

GET /api/v1/voices/designs

디자인한 보이스를 최신순으로, 슬롯 사용량과 함께 반환합니다: { "voices": [...], "used": 3, "limit": 20 }.

DELETE /api/v1/voices/designs/:voiceId

공급자와 라이브러리에서 보이스를 삭제합니다. 유료 플랜에서는 슬롯이 반환됩니다. { "ok": true, "id": "...", "deleted": true }를 반환합니다.

음성 복제

짧은 녹음 하나로 특정 목소리를 재현합니다. 복제는 points가 전혀 들지 않습니다 — 플랜의 복제 슬롯 수로만 제한됩니다. 본인 소유이거나 서면 허가를 받은 목소리만 복제하세요.

POST /api/v1/voices/clones

거의 모든 오디오 파일이 됩니다. audio_base64는 녹음의 순수 base64이며 data: 접두사는 필요 없습니다 — MP3, WAV, M4A, AAC, OGG, FLAC, WebM, MP4의 오디오 트랙 등. 음성 공급자가 그대로 받지 않는 형식은 서버에서 모노 16비트 WAV로 변환됩니다. 웹 앱이 업로드 전에 브라우저에서 하는 것과 같으므로, API가 Studio보다 까다롭지 않습니다.

• 앞부분 30초로 자릅니다 — 더 긴 파일을 보내도 되지만 앞부분만 사용됩니다;
• 스테레오를 모노로 다운믹스하고 32kHz로 리샘플링합니다;
• 너무 큰 파일을 줄입니다 — 24비트 스튜디오 WAV를 직접 손볼 필요가 없습니다.

제한은 디코딩된 바이트가 아니라 base64 문자열에 적용되며 최대 8,000,000자(약 6MB 파일)입니다. 초과하면 413 sample_too_large, 오디오로 읽을 수 없는 파일은 400 unreadable_audio를 반환합니다.

무언가 변경된 경우 응답에 그 내용을 담은 audio_notes 배열이 포함됩니다. 긴 녹음의 앞 30초로 만들어진 복제본이 조용히 생기는 일이 없도록 로그로 남겨 두는 편이 좋습니다:

{ "id": "...", "name": "My Narrator", "type": "clone", "used": 2, "limit": 100,
  "audio_notes": ["Re-encoded to mono 16-bit WAV at 32 kHz — aac isn't a format the provider accepts.",
                  "Trimmed to the first 30s (the sample was 90s)."] }

curl -X POST https://api.vocallab.ai/api/v1/voices/clones \
  -H "Authorization: Bearer vl_live_..." \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"My Narrator\",\"language\":\"English\",\"samples\":[{\"audio_base64\":\"$(base64 -w0 sample.mp3)\"}]}"

{ "id": "default-abc123__my-narrator", "name": "My Narrator", "type": "clone",
  "languages": ["EN_US"], "created_at": "...", "used": 2, "limit": 100 }

GET /api/v1/voices/clones

복제한 보이스를 최신순으로, 슬롯 사용량과 함께 반환합니다: { "voices": [...], "used": 2, "limit": 100 }.

DELETE /api/v1/voices/clones/:voiceId

공급자와 라이브러리에서 보이스를 삭제합니다. 유료 플랜에서는 슬롯이 반환됩니다. { "ok": true, "id": "...", "deleted": true }를 반환합니다.

슬롯은 별개입니다. 복제 보이스와 디자인 보이스는 예산을 공유하지 않습니다 — 플랜별 수치는 플랜과 제한을 참고하세요. Free 플랜의 한도는 평생 기준이라 삭제해도 슬롯이 반환되지 않습니다. 워크스페이스에서는 멤버가 소유자의 플랜 한도 안에서 작업하며, 디자인 points는 소유자 잔액에서 차감됩니다.

points가 드는 작업

GET /api/v1/me

포인트 잔액과 플랜.

오류

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

가격

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

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

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