본문으로 건너뛰기

일반 STT

일반 STT API는 음성 파일을 텍스트로 변환하는 HTTP 기반의 REST API입니다.

지원 포맷​

팁

일반 STT API는 음성 파일 포맷 mp4, m4a, mp3, amr, flac, wav을 지원하고 있습니다.

인증 토큰 발급​

일반 STT API는 인증 가이드를 통해 토큰을 발급받은 뒤 사용하실 수 있습니다.


API 목록

MethodURLDescription
POST/v1/transcribe파일 전사 요청
GET/v1/transcribe/{TRANSCRIBE_ID}파일 전사 결과 조회

1) [POST] /v1/transcribe​

저장된 음성 파일에 대해 전사를 요청하는 API입니다.

HTTP 요청​

POST https://openapi.vito.ai/v1/transcribe

요청 헤더​

Authorization: Bearer {YOUR_JWT_TOKEN}
  • scheme: bearer
  • bearerFormat: JWT

요청 바디 (Request body)​

content-type: multipart/form-data

FieldTypeRequired
configRequestConfigrequired
fileBinaryrequired

RequestConfig

NameDescTypeRequiredValueDefault
model_name음성인식 모델stringoptionalsommers, whispersommers
language음성인식 언어, whisper 전용stringoptionalko, detect, multi 등ko
language_candidates언어 감지 후보군, language가 detect 또는 multi일 때만 적용arrayoptional["ko","ja","zh","en"]
use_diarization화자 분리 사용 여부booleanoptionalfalse
diarization.spk_count화자수, use_diarization이 true일 때만 적용integeroptional0 이상의 정수0 (화자수 예측)
use_itn영어/숫자/단위 변환 여부booleanoptionaltrue
use_disfluency_filter간투어 필터 사용 여부booleanoptionaltrue
use_profanity_filter비속어 필터 사용 여부booleanoptionalfalse
use_paragraph_splitter문단 나누기 사용 여부booleanoptionaltrue
paragraph_splitter.max문단의 최대 문자 길이, use_paragraph_splitter이 true일 때만 적용integeroptional1 이상의 정수50
domain음성파일의 종류 (도메인)stringoptionalGENERAL, CALLGENERAL
use_word_timestamp단어별 Timestamp 사용 여부booleanoptionalfalse
keywords키워드 부스팅용 단어 리스트arrayoptional
주의

일반 STT API의 경우 아래와 같은 제약 사항이 있습니다.

  1. POST API 동시처리 제한: 동시처리 가능한 파일 개수는 처리량 제한 정책을 따릅니다. POST API로 요청한 뒤 처리가 완료되기 전까지의 요청 개수를 의미하며, API 처리에 대한 완료는 아래 GET API를 통해 확인 가능합니다.
  2. 최대 인식파일 크기: 2GB, 최대 인식가능 시간: 4시간.
  3. 전사 작업은 요청 순서에 따라 순차적으로 처리됩니다. 최대 인식 가능 시간인 4시간 분량의 음성 파일도 일반적으로 5분 이내에 작업이 시작되지만, 요청이 많은 시간대에는 작업 시작까지 최대 30분 이상 소요될 수 있습니다.

샘플 코드 1​

transcribe.sh
curl -X "POST" \
  "https://openapi.vito.ai/v1/transcribe" \
  -H "accept: application/json" \
  -H "Authorization: Bearer ${YOUR_JWT_TOKEN}" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@sample.wav" \
  -F 'config={}'

샘플 코드 2​

transcribe.sh
curl -X "POST" \
  "https://openapi.vito.ai/v1/transcribe" \
  -H "accept: application/json" \
  -H "Authorization: Bearer ${YOUR_JWT_TOKEN}" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@sample.wav" \
  -F 'config={
    "use_diarization": true,
    "diarization": {
      "spk_count": 2
    },
    "use_itn": false,
    "use_disfluency_filter": false,
    "use_profanity_filter": false,
    "use_paragraph_splitter": true,
    "paragraph_splitter": {
      "max": 50
    }
  }'

응답 바디 (Response Body)​

응답이 성공한 경우 HTTP Status 200과 함께 아래와 같은 응답을 내려줍니다.

{
  "id": "{TRANSCRIBE_ID}"
}

오류 코드​

HTTP StatusCodeNotes
400H0001잘못된 파라미터 요청
400H0010지원하지 않는 파일 포맷
401H0002유효하지 않은 토큰
413H0005파일 사이즈 초과
413H0006파일 길이 초과
429A0001사용량 초과
429A0002동시 처리 제한 초과
500E500서버 오류

아래는 응답이 실패한 경우 가운데 하나의 예시입니다.

{
  "code": "H0001",
  "msg": "unexpected end of JSON input"
}

2) [GET] /v1/transcribe/{TRANSCRIBE_ID}​

  • 음성 파일의 전사 결과를 조회하는 API입니다. 전사 요청 API에서 응답받은 TRANSCRIBE_ID를 사용하여 전사 결과를 조회할 수 있습니다.

HTTP 요청​

GET https://openapi.vito.ai/v1/transcribe/{TRANSCRIBE_ID}

요청 헤더​

Authorization: Bearer {YOUR_JWT_TOKEN}
  • scheme: bearer
  • bearerFormat: JWT

샘플 코드​

get_transcript.sh
curl -X "GET" \
  "https://openapi.vito.ai/v1/transcribe/${TRANSCRIBE_ID}" \
  -H "accept: application/json" \
  -H "Authorization: Bearer ${YOUR_JWT_TOKEN}"

응답 바디 (Response Body)​

응답이 성공한 경우 HTTP Status 200과 함께 아래와 같은 응답을 내려줍니다.

NameDescTypeValue
idtranscribe idstring
status전사 결과 상태stringtranscribing, completed, failed
results.utterances발화 정보array
results.utterances.start_at발화 시작 시각 (ms)integer
results.utterances.duration발화 지속 시간 (ms)integer
results.utterances.msg발화 텍스트string
results.utterances.spk화자/채널 IDinteger
results.utterances.langlanguage로 설정한 언어, 또는 detect/multi인 경우에는 모델이 예측한 언어stringISO 639-1 language code
팁

일반 STT API의 경우, 긴 음성 파일도 지원하기 위하여 Polling 방식으로 구현되어 있습니다. 전사 요청 API에서 응답받은 {TRANSCRIBE_ID}의 상태 값이 transcribing인 경우, 최종 상태(completed 또는 failed)가 될 때까지 주기적으로 조회하여 변환 결과를 확인할 수 있습니다. 권장하는 Polling 주기는 5초입니다. (Polling 주기가 너무 짧을 경우 HTTP Status 429로 요청 제한 초과 응답이 내려갈 수 있습니다.)

status: transcribing

{
  "id": "{TRANSCRIBE_ID}",
  "status": "transcribing"
}

status: completed

{
  "id": "{TRANSCRIBE_ID}",
  "status": "completed",
  "results": {
    "utterances": [
      {
        "start_at": 4737,
        "duration": 2360,
        "msg": "안녕하세요.",
        "spk": 0,
        "lang": "ko"
      },
      {
        "start_at": 8197,
        "duration": 3280,
        "msg": "네, 안녕하세요? 반갑습니다.",
        "spk": 1,
        "lang": "ko"
      }
    ]
  }
}

status: failed

응답은 성공했지만 전사가 실패한 경우 아래와 같은 응답을 내려줍니다.

{
  "id": "{TRANSCRIBE_ID}",
  "status": "failed",
  "error": {
    "code": "{ERROR_CODE}",
    "message": "{MESSAGE}"
  }
}

아래는 예시입니다.

{
  "id": "ZbOOQftrS1ywK_T3ikuveA",
  "status": "failed",
  "error": {
    "code": "E500",
    "message": "internal server error"
  }
}

위와 같은 경우가 지속적으로 발생할 경우, 문의해 주시기 바랍니다.

오류 코드​

HttpStatusCodeNotes
400H0001잘못된 파라미터 요청
401H0002유효하지 않은 토큰
403H0003권한 없음
404H0004전사 결과 없음
410H0007전사 결과 만료됨
429A0003요청 제한 초과
500E500서버 오류

아래는 응답이 실패한 경우 가운데 하나의 예시입니다.

{
  "code": "H0004",
  "msg": "not found"
}

샘플 코드 (단일 예제 + 프리셋)​

아래 하나의 예제 스크립트에서 PRESET 환경변수로 원하는 설정을 조합할 수 있습니다. 기본은 sommers_basic 입니다.

transcribe.py
import json
import os
import time
from typing import Any, Dict, Optional

import requests


class RTZROpenAPIClient:
    """Minimal client for RTZR OpenAPI (auth + STT file).

    - Fetches JWT via /v1/authenticate using client_id/client_secret
    - Submits a file transcription job via /v1/transcribe
    - Polls /v1/transcribe/{id} every few seconds until completed/failed
    """

    def __init__(
        self,
        client_id: Optional[str] = None,
        client_secret: Optional[str] = None,
        base_url: str = "https://openapi.vito.ai",
    ) -> None:
        self.base_url = base_url.rstrip("/")
        self.client_id = client_id or os.getenv("RTZR_CLIENT_ID")
        self.client_secret = client_secret or os.getenv("RTZR_CLIENT_SECRET")
        if not self.client_id or not self.client_secret:
            raise ValueError(
                "Missing credentials. Set RTZR_CLIENT_ID and RTZR_CLIENT_SECRET "
                "environment variables, or pass client_id/client_secret to RTZROpenAPIClient."
            )
        self._sess = requests.Session()
        self._token: Optional[Dict[str, Any]] = None

    @property
    def token(self) -> str:
        # Renew if missing or expiring within 30 minutes
        if self._token is None or self._token.get("expire_at", 0) < time.time() - 1800:
            resp = self._sess.post(
                f"{self.base_url}/v1/authenticate",
                data={"client_id": self.client_id, "client_secret": self.client_secret},
            )
            resp.raise_for_status()
            self._token = resp.json()
        access = self._token.get("access_token")
        if not access:
            raise RuntimeError("authenticate: 'access_token' not found in response")
        return access

    def _auth_headers(self) -> Dict[str, str]:
        return {"Authorization": f"Bearer {self.token}"}

    def transcribe_file(self, file_path: str, config: Dict[str, Any]) -> Dict[str, Any]:
        url = f"{self.base_url}/v1/transcribe"
        with open(file_path, "rb") as f:
            files = {"file": (os.path.basename(file_path), f)}
            data = {"config": json.dumps(config)}
            resp = self._sess.post(url, headers=self._auth_headers(), files=files, data=data)
            resp.raise_for_status()
            return resp.json()

    def get_transcription(self, transcribe_id: str) -> Dict[str, Any]:
        url = f"{self.base_url}/v1/transcribe/{transcribe_id}"
        resp = self._sess.get(url, headers=self._auth_headers())
        resp.raise_for_status()
        return resp.json()

    def wait_for_result(
        self,
        transcribe_id: str,
        poll_interval_sec: int = 5,
        timeout_sec: int = 3600,
    ) -> Dict[str, Any]:
        deadline = time.time() + timeout_sec
        while True:
            if time.time() > deadline:
                raise TimeoutError("Timed out waiting for transcription result")
            result = self.get_transcription(transcribe_id)
            status = result.get("status")
            if status in ("completed", "failed"):
                return result
            time.sleep(poll_interval_sec)


# Preset configurations
PRESETS: Dict[str, Dict[str, Any]] = {
    "sommers_basic": {  # 1) sommers without diarization
        "model_name": "sommers",
        "use_diarization": False,
        "domain": "GENERAL",
    },
    "sommers_call_diarization": {  # 2) sommers + diarization + CALL, spk_count=2
        "model_name": "sommers",
        "domain": "CALL",
        "use_diarization": True,
        "diarization": {"spk_count": 2},
    },
    "whisper_en_diarization": {  # 3) whisper + diarization, language=en
        "model_name": "whisper",
        "language": "en",
        "use_diarization": True,
    },
    # Additional commonly requested options
    "paragraph_split_80": {"use_paragraph_splitter": True, "paragraph_splitter": {"max": 80}},
    "keywords_example": {"keywords": ["stt", "returnzero", "api"]},
    "with_word_timestamps": {"use_word_timestamp": True},
    "disfluency_on": {"use_disfluency_filter": True},
    "profanity_on": {"use_profanity_filter": True},
    "whisper_detect_multi": {
        "model_name": "whisper",
        "language": "multi",
        "language_candidates": ["ko", "en", "ja"],
    },
}


def main():
    audio_path = os.getenv("AUDIO_PATH", "sample.wav")
    preset_name = os.getenv("PRESET", "sommers_basic")

    if preset_name not in PRESETS:
        raise ValueError(f"Unknown PRESET '{preset_name}'. Available: {sorted(PRESETS.keys())}")

    config = PRESETS[preset_name]

    client = RTZROpenAPIClient()

    submit = client.transcribe_file(audio_path, config)
    transcribe_id = submit.get("id")
    result = client.wait_for_result(transcribe_id, poll_interval_sec=5)
    print(json.dumps(result, ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()

사용 가능한 프리셋 목록은 다음과 같습니다.

  • sommers_basic: model_name=sommers, use_diarization=false, domain=GENERAL
  • sommers_call_diarization: model_name=sommers, domain=CALL, use_diarization=true, diarization.spk_count=2
  • whisper_en_diarization: model_name=whisper, language=en, use_diarization=true
  • paragraph_split_80: use_paragraph_splitter=true, paragraph_splitter.max=80
  • keywords_example: keywords=["stt","returnzero","api"]
  • with_word_timestamps: use_word_timestamp=true
  • disfluency_on: use_disfluency_filter=true
  • profanity_on: use_profanity_filter=true
  • whisper_detect_multi: model_name=whisper, language=multi, language_candidates=["ko","en","ja"]