RTZR 사용법

리턴제로(ReturnZero) 개요

리턴제로는 한국어 음성인식(STT) 분야에서 우수한 성능을 보이는 서비스로, 다양한 벤치마크에서 그 성능을 입증하고 있다. 특히 한국어 언어모델의 다분야 사고력을 측정하는 ‘로직Kor(LogicKor)’ 리더보드에서 경량화된 거대언어모델(sLLM) 중 1위를 달성했다.

한국어 STT 성능 비교

다음은 한국어 STT 성능을 비교한 벤치마크로, 리턴제로의 우수한 성능을 확인할 수 있다.

API \ 데이터셋	Avg. CER(%)	주요 영역별 회의	회의	상담	저음질 전화망	한국어 강의	KsponSpeech eval clean	KsponSpeech eval other
OpenAI Whisper	11.39	10.49	10.16	7.51	17.27	10.89	12.06	11.34
Google api v2	11.50	N/A1	11.62	8.37	14.11	11.48	11.82	11.59
ETRI	10.19	9.95	10.56	8.36	15.46	9.89	9.99	7.15
Naver ClovaSpeech	9.52	7.88	8.53	5.89	9.09	13.71	10.66	10.86
리턴제로	6.18	6.78	7.27	3.56	4.66	7.76	6.61	6.64
리턴제로 Whisper2	6.59	6.84	8.33	4.1	4.26	7.11	7.78	7.73
STT OpenAPI는 다음의 두 가지 형태를 제공한다:

• 일반 STT: 음성 파일을 텍스트로 변환
• 스트리밍 STT: 실시간으로 음성인식 처리

참고사항

• 무료 사용량: 기본 10시간을 무료 제공
• 보관 주기: 개인정보를 위해 변환된 데이터는 3일 동안만 기록하며, 3일이 지나면 삭제함
• Web, App 환경에서 사용하는 것보다, 서버를 통해서 연동하는 방식을 권장

인증 가이드

API를 사용하기 위해서는 애플리케이션 등록이 필요하다. 아래 절차를 따르면 된다.

1. RTZR 디벨로퍼스 사이트 회원가입
2. 콘솔에 입장
3. API 연동에 필요한 SECRET(client_id, client_secret) 정보 발급

애플리케이션 등록이 완료되면, 발급받은 Secret 정보와 인증 과정을 통해 Token을 발급받을 수 있다.

API 목록

Method	URL	Description
POST	/v1/authenticate	인증 토큰 요청

인증 토큰 요청 샘플 코드

import requests
 
resp = requests.post(
    'https://openapi.vito.ai/v1/authenticate',
    data={'client_id': '{YOUR_CLIENT_ID}',
          'client_secret': '{YOUR_CLIENT_SECRET}'}
)
resp.raise_for_status()
print(resp.json())

응답 바디 (Response Body)

성공 시, HTTP Status 200과 함께 아래와 같은 응답이 반환된다.

{
  "access_token": "{YOUR_JWT_TOKEN}",
  "expire_at": 1690377931
}

CAUTION

token의 만료 기간은 6시간이므로 /v1/authenticate를 통해 주기적으로 토큰을 갱신해야 한다.

오류 코드에 대한 자세한 내용은 RTZR STT 문서를 참고한다.

일반 STT

일반 STT API는 음성 파일을 텍스트로 변환할 수 있는 기능을 제공한다. HTTP 기반의 REST API³로 구현되어 있으며, 다양한 음성 파일 포맷을 지원한다.

지원 포맷

• mp4, m4a, mp3, amr, flac, wav

API 목록

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

1) [POST]/v1/transcribe

저장된 음성 파일에 대해 전사를 요청한다.

HTTP 요청

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

요청 헤더

Authorization: bearer {YOUR_JWT_TOKEN}

• scheme: bearer
• bearerFormat: JWT

요청 바디 (Request body)

content-type: multipart/form-data

Field	Type	Required
config	RequestConfig	required
file	Binary	required
RequestConfig

Name	Desc	Type	Required	Value	Default
model_name	음성인식 모델	string	optional	sommers, whisper	sommers
language	음성인식 언어, whisper 사용할 때만 적용	string	optional		ko
use_diarization	화자 분리 사용 여부	boolean	optional		false
diarization.spk_count	화자수, use_diarization이 true일 때만 적용	integer	optional	0 이상의 정수	0 (화자수 예측)
use_itn	영어/숫자/단위 변환 여부	boolean	optional		true
use_disfluency_filter	간투어 필터 사용 여부	boolean	optional		true
use_profanity_filter	비속어 필터 사용 여부	boolean	optional		false
use_paragraph_splitter	문단 나누기 사용 여부	boolean	optional		true
paragraph_splitter.max	문단의 최대 문자 길이, use_paragraph_splitter이 true일 때만 적용	integer	optional	1 이상의 정수	50
domain	음성파일의 종류 (도메인)	string	optional	GENERAL, CALL	GENERAL
use_word_timestamp	단어별 Timestamp 사용 여부	boolean	optional		false
keywords	키워드 부스팅용 단어 리스트	array	optional

CAUTION

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

1. POST API의 동시처리 제한: 10개, POST API로 요청한 뒤 처리가 완료되기 전까지의 요청 개수를 의미하며, 완료 여부는 GET API를 통해 확인 가능하다.
2. 최대 인식파일 크기: 2GB, 최대 인식가능 시간: 4시간.

샘플 코드

import json
import requests
 
config = {}
resp = requests.post(
    'https://openapi.vito.ai/v1/transcribe',
    headers={'Authorization': 'bearer '+'{YOUR_JWT_TOKEN}'},
    data={'config': json.dumps(config)},
    files={'file': open('sample.wav', 'rb')}
)
resp.raise_for_status()
print(resp.json())

다양한 옵션을 설정한 예시:

import json
import requests
 
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
  }
}
resp = requests.post(
    'https://openapi.vito.ai/v1/transcribe',
    headers={'Authorization': 'bearer '+'{YOUR_JWT_TOKEN}'},
    data={'config': json.dumps(config)},
    files={'file': open('sample.wav', 'rb')}
)
resp.raise_for_status()
print(resp.json())

응답 바디 (Response Body)

성공 시, HTTP Status 200과 함께 아래와 같은 응답이 반환된다.

{
  "id": "{TRANSCRIBE_ID}"
}

응답이 실패한 경우 오류 코드는 RTZR STT 문서를 참고한다.

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

전사 요청 시 발급받은 TRANSCRIBE_ID를 사용하여 전사 결과를 조회한다.

HTTP 요청

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

요청 헤더

Authorization: bearer {YOUR_JWT_TOKEN}

• scheme: bearer
• bearerFormat: JWT

샘플 코드

import requests
 
resp = requests.get(
    'https://openapi.vito.ai/v1/transcribe/'+'{TRANSCRIBE_ID}',
    headers={'Authorization': 'bearer '+'{YOUR_JWT_TOKEN}'},
)
resp.raise_for_status()
print(resp.json())

응답 바디 (Response Body)

성공 시, HTTP Status 200과 함께 아래와 같은 응답이 반환된다.

Name	Desc	Type	Value
id	transcribe id	string
status	전사 결과 상태	string	transcribing, completed, failed
results.utterances	발화 정보	array
results.utterances.start_at	발화 시작 시각 (ms)	integer
results.utterances.duration	발화 duration (ms)	integer
results.utterances.msg	발화 텍스트	string
results.utterances.spk	화자/채널 ID	integer

TIP

일반 STT API는 긴 음성 파일도 지원하기 위해 Polling 방식을 사용한다. status 값이 transcribing인 경우, 최종 상태(completed 또는 failed)가 될 때까지 주기적으로 조회하여 결과를 확인해야 한다. 권장 Pooling 주기는 5초다.

status: transcribing

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

status: completed

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

응답이 실패한 경우 오류 코드는 RTZR STT 문서를 참고하자.

사용요금

요금

• 상품별 요금은 다음과 같다:
  • 일반 STT: 1시간당 1,000원
  • 스트리밍 STT: 1시간 1,000원
• 요금은 사용량에 따라 매월 청구되며, 부가세 별도
• 사용량은 1초 단위로 집계한 뒤 시간 단위로 환산한다(ex. 900초 = 15분 = 0.25시간으로 집계)
  • 일반 STT의 경우 음성 파일 길이를 기준으로 사용량이 집계됨.
    • 다중 채널 옵션을 사용할 경우 각 채널별 음성 파일 길이의 합이 집계됨
  • 스트리밍 STT의 경우, 실시간 스트림의 길이를 기준으로 사용량이 집계됨

다른 STT 서비스의 요금은 다음을 참고하자.

플랜

• 모든 유저는 가입 즉시 basic 플랜으로 시작함

무료 사용량

• 무료 사용량: 모든 유저에게 가입 즉시 기본 10시간을 무료 제공함
  • 일반 STT와 스트리밍 STT 구분 없이 API 사용 시간의 합산으로 10시간을 제공
• 무료 사용량에 대해서는 별도의 요금이 청구되지 않음

Footnotes

1. Google의 음성인식 파일 크기의 제한으로 생략 ↩

2. OpenAI에서 공개한 Whisper 오픈소스 모델에 리턴제로의 데이터를 파인튜닝(fine-tuning)한 모델 ↩

3. Representational State Transfer API, 자원을 이름으로 구분하여 해당 자원의 상태를 주고 받는 모든 것을 의미 ↩