요청 파라미터

AmiVoice API로 음성 인식을 요청할 때 설정하는 파라미터에 대해 설명합니다. HTTP, WebSocket 인터페이스에서 각각 전송 방법이 다르지만, 설정할 수 있는 파라미터는 동일합니다.

파라미터 목록

authorization(인증 정보)와 grammarFileNames(연결 엔진 이름)는 필수입니다. 그 외의 파라미터는 선택사항입니다. 인터페이스마다 지원되지 않는 것도 있으므로 아래 표를 참조하십시오.

파라미터 이름	설명	필수	동기식 HTTP	WebSocket	비동기 HTTP
authorization	인증 정보	●	●	●	●
grammarFileNames	연결 엔진 이름	●	●	●	●
profileId	프로파일 ID		●	●	●
profileWords	단어 등록 목록		●	●	●
keepFillerToken	채움말(Filler words) 자동 삭제의 억제		●	●	●
segmenterProperties	발화 구간 검출・화자 다이어라이제이션 파라미터		●	●	● （*１）
extension	사용량 집계 태그		●	●	●
maxDecodingTime	최대 인식 처리 시간		●	●	●
maxResponseTime	최대 응답 시간		●	●	●
maxDecodingRate	최대 RT		●	●	●
targetResponseTime	목표 응답 시간		●	●	●
targetDecodingRate	목표 RT		●	●	●
recognitionTimeout	인식 완료 타임아웃		●	●	●
resultUpdatedInterval	인식 중 이벤트 간격			●
noInputTimeout	발화 시작 대기 타임아웃			●
loggingOptOut	로그 저장 여부 변경				●
contentId	사용자 정의 ID				●
compatibleWithSync	결과 포맷의 호환성				●
speakerDiarization	화자 다이어라이제이션 활성화 옵션				●
diarizationMinSpeaker	화자 다이어라이제이션의 최소 추정 화자 수				●
diarizationMaxSpeaker	화자 다이어라이제이션의 최대 추정 화자 수				●
sentimentAnalysis	감정 분석 활성화 옵션				●

(*１) 비동기 HTTP 인터페이스에서는 화자 다이어라이제이션 관련 파라미터를 사용할 수 없습니다.

이러한 요청 파라미터의 전송 방법에 대해서는 다음 섹션을 참조하십시오.

• 동기식 HTTP 인터페이스
• 비동기 HTTP 인터페이스
• WebSocket 인터페이스

파라미터 상세

다음은 파라미터의 상세 설명입니다.

필수 파라미터

authorization

인증 정보

API를 사용하려면 반드시 인증 정보를 설정해야 합니다. 인증 정보는 마이페이지에 기재된 [APPKEY] 또는 원타임 APPKEY 발행 API로 취득한 원타임 APPKEY입니다.

주의

브라우저 애플리케이션에서 음성 인식 서버에 연결할 경우, HTML 파일에 APPKEY를 작성하는 것을 피하기 위해 원타임 APPKEY를 사용하도록 하십시오. 자세한 내용은 원타임 APPKEY를 참조하십시오.

grammarFileNames

연결 엔진 이름

해당 세션에서 사용하고자 하는 음성 인식 엔진을 지정합니다. 1회 세션에 1개를 지정합니다. 설정할 수 있는 값은 연결 엔진 이름 목록표나 마이페이지를 참조하십시오. 자세한 내용은 음성 인식 엔진을 참조하십시오.

선택 파라미터

profileId

프로파일 ID

프로파일은 음성 인식 서버 상에 존재하는 사용자별 데이터 파일로, 사용자가 이름을 지정하여 등록한 단어를 저장할 수 있습니다. 프로파일 ID는 해당 데이터 파일을 지정하기 위한 식별자입니다. 자세한 내용은 사용자 사전을 참조하십시오.

profileWords

사용자 사전 단어 목록

세션에서 유효한 사용자 사전의 단어를 등록할 수 있습니다. 하이브리드 엔진의 단어 등록의 경우, 하나의 단어는 "표기<반각 공백>읽기" 형식으로 등록합니다. 클래스명을 지정하는 경우 "표기<반각 공백>읽기 <반각 공백>클래스명"으로 지정하십시오. End to End 엔진의 단어 강조의 경우、"표기<반각 공백>대체 표기<반각 골백>단어 강조도』의 형식으로 지정합니다. 대체 표기와 단어 강조도는 생략 가능합니다만, 대체 표기만을 생략하는 경우는, "표기<반각 공백><반각 공백>단어 강조도"로 지정합니다. 단어 등록 및 단어 강조에서 여러 개의 단어를 등록하는 경우, 단어와 단어 사이를 "|"(세로줄)로 구분합니다. 값의 포맷은 다음과 같습니다 (단어 등록 시, 클래스명을 지정하지 않은 경우의 예입니다).

표기1 읽기1|표기2 읽기2|표기3 읽기3|표기4 읽기4

자세한 내용은 사용자 사전을 참조하십시오.

keepFillerToken

채움말(Filler words) 자동 삭제의 억제

1 또는 0을 지정합니다. 기본값은 0입니다. 음성 인식 결과에 포함된 채움말(예를 들어, 「あー」 또는 「えー」 등)을 자동으로 제거하고 싶지 않을 때 1을 지정합니다. 채움말의 자동 삭제도 참조하십시오.

채움말(Filler words)은 단어의 앞뒤를 반각 "%"로 둘러싸여 있습니다. 다음은 채움말의 예입니다.

%あー%
%えー%
%おー%
%えっと%

팁

AmiVoice Tech Blog의 AmiVoice API로 채움말(Filler words)을 표시할지 제거할지 선택하는 방법 (일본어 블로그)도 참조하십시오.

segmenterProperties

발화 구간 검출 파라미터

발화를 얼마나 쉽게 검출할 수 있을지 등을 조정하는 파라미터입니다. 먼저 기본값으로 테스트한 후, 필요에 따라 조정하시기 바랍니다. 설정 가능한 파라미터는 다음과 같습니다.

기본값은 동기식 HTTP 인터페이스 및 WebSocket 인터페이스가 공통이며, 비동기 HTTP 인터페이스는 일부 다른 값이 설정되어 있습니다. 후자는 ()안에 기재되어 있습니다.

주의

기본값은 예고 없이 변경될 수 있습니다.

• threshold
  • 발화 여부를 판단하기 위한 점수의 임계값입니다. 점수가 설정값 이상인 경우, 발화로 간주됩니다. 설정값을 작게 할수록 발화가 더 잘 검출되어, 발화가 끊기거나 끝부분이 잘리는 현상이 줄어듭니다. 하지만 잘못 검출될 가능성도 높아집니다. 노이즈가 많은 환경에서 이러한 오검출이 두드러지는 경우에는 이 값을 크게 설정합니다.
  • 기본값은 5000(8000)입니다.
• preTime
  • 발화로 간주된 시간이 일정 시간 지속되면 발화 구간 검출 상태로 전환되는데, 이 "일정 시간"의 길이를 지정하는 값입니다. 짧은 발화가 검출되지 않거나 발화의 앞부분이 잘리는 경우에는 이 값을 작게 설정합니다. 짧은 노이즈가 잘못 검출되는 경우에는 이 값을 크게 설정합니다.
  • 단위는 밀리초이며, 기본값은 100(100)입니다. 50의 배수로 지정해야 합니다.
• postTime
  • 발화 구간의 끝부분에서 비발화로 간주된 시간이 일정 시간 지속되면 발화 구간 검출 상태가 종료됩니다. 이 "일정 시간"의 길이를 지정하는 값입니다. 발화 도중에 끊기는 경우에는 이 값을 크게 설정하고, 두 개의 발화가 연결되어 버리는 경우에는 이 값을 작게 설정합니다.
  • 단위는 밀리초이며, 기본값은 550(800)입니다.
• preForcedTime
  • 발화 구간 검출 상태로 전환될 때, 발화로 간주된 최초 시점에서 얼마나 이전으로 되돌려서 발화 구간 시작 지점으로 설정할지를 지정하는 값입니다. 발화의 앞부분이 잘리기 쉬운 경우에는, 이 값을 크게 설정합니다.
  • 단위는 밀리초이며, 기본값은 350(350)입니다.
• postForcedTime
  • 발화 구간 검출 상태가 종료될 때, 비발화로 간주된 최종 시점에서 얼마나 이후까지를 발화 구간으로 간주할지를 지정하는 값입니다. 발화의 끝부분이 잘리는 경우에는 이 값을 크게 설정하고, 응답의 실시간성이 떨어지는 경우에는 이 값을 작게 설정합니다.
  • 단위는 밀리초이며, 기본값은 350(350)입니다.
• powerThreshold
  • 발화 여부를 판단할 때 음량(signal power)을 고려하는 경우의 점수 임계값입니다. threshold와는 별도로 설정해야 하며, 0 이하의 값으로 설정하면 무효화됩니다. 점수가 임계값 이하인 경우에는 발화가 아닌 것으로 간주됩니다. 배경의 작은 소리가 검출되는 경우에는 이 값을 크게 설정합니다.
  • 기본값은 100(100)입니다.
• decayTime
  • 일정 시간이 경과하면 postTime 값을 점차 감소시켜 발화를 더 쉽게 끊어지도록 조정할 수 있는데, 이 "일정 시간"을 지정하는 값입니다. 검출된 발화 구간이 너무 긴 경우에는 이 값을 작게 설정합니다.
  • 단위는 밀리초이며, 기본값은 5000(15000)입니다.

화자 다이어라이제이션 관련 파라미터

화자 다이어라이제이션에 관련된 파라미터입니다. 동기식 HTTP 및 WebSocket 인터페이스에서만 설정 가능합니다. 설정 가능한 파라미터는 다음과 같습니다.

• useDiarizer
  • 1을 설정하면 동기식 HTTP나 WebSocket 인터페이스에서 화자 다이어라이제이션을 활성화합니다. 기본값은 비활성화입니다. 자세한 내용은 화자 다이어라이제이션을 참조하십시오.
• diarizerAlpha
  • 동기식 HTTP나 WebSocket 인터페이스에서의 화자 다이어라이제이션의 새로운 화자 출현 용이성을 제어하는 파라미터입니다. 큰 값을 지정할수록 새로운 화자가 출현하기 쉽고, 작은 값을 지정할수록 새로운 화자가 출현하기 어려워집니다. diarizerAlpha=0은 특별한 경우로, 1e-30 이 지정된 것으로 취급됩니다. 단, 8kHz 음성 대응 엔진, 예를 들어 汎用 범용 엔진(-a-general)을 사용하고 샘플링 레이트가 8kHz인 음성을 전송한 경우에는 1e-10 이 지정된 것으로 처리됩니다. 아무것도 설정하지 않으면 diarizerAlpha=0이 지정된 것으로 간주됩니다.
• diarizerTransitionBias
  • 동기식 HTTP나 WebSocket 인터페이스에서의 화자 다이어라이제이션의 화자 전환 용이성을 제어하는 파라미터입니다. 큰 값을 지정할수록 화자가 전환되기 쉽고, 작은 값을 지정할수록 화자가 전환되기 어려워집니다. diarizerTransitionBias=0은 특별한 경우로, 1e-20 이 지정된 것으로 취급됩니다. 아무것도 설정하지 않으면 diarizerTransitionBias=0이 지정된 것으로 간주됩니다.

파라미터 설정 방법

segmenterProperties= 뒤에 파라미터 설정을 기술합니다. 여러 개의 파라미터를 동시에 설정할 경우, 각 파라미터는 공백(space)문자로 구분합니다.

curl 명령어를 사용한 동기식 HTTP 인터페이스 설정 예시

여러 파라미터를 설정할 때 사용하는 공백문자는 URL 인코딩 시 %20으로 변환합니다.

curl https://acp-api.amivoice.com/v1/recognize \
     -F u={APP_KEY} \
     -F d="grammarFileNames=-a-general segmenterProperties=threshold=4000%20postTime=600" \
     -F a=@test.wav

WebSocket 인터페이스 설정 예시

segmenterProperties에 설정한 전체 파라미터는 "..."과 같이 큰따옴표(double quote) 로 감싸서 지정합니다.

s 16K -a-general authorization={APPKEY} segmenterProperties="preTime=200 useDiarizer=1 diarizerAlpha=1e-20"

extension

사용량 집계 태그

동일한 AmiVoice API 계정을 여러 시스템이나 환경, 최종 사용자 등이 공유하는 경우, 임의의 속성별 사용량을 확인할 수 있도록 사용량 집계 태그를 설정할 수 있습니다. 자세한 내용은 사용량 집계 태그를 참조하십시오.

maxDecodingTime

최대 인식 처리 시간

$$\text{지금까지 소요된 음성 인식 처리 시간} > \text{maxDecodingTime}$$

인 경우, 음성 인식 처리를 강제로 중단시키는 기능입니다. 단위는 밀리초입니다.

기본값은 0이며, 0인 경우 이 기능은 비활성화됩니다.

maxResponseTime

최대 응답 시간

$$\text{지금까지 소요된 음성 인식 처리 시간} > \text{입력된 음성의 시간} + \text{maxResponseTime}$$

인 경우, 음성 인식 처리를 강제로 중단시키는 기능입니다. 단위는 밀리초입니다. 이 기능은 모든 음성 데이터를 수신한 후에만 작동한다는 점에 주의하십시오.

기본값은 0이며, 0인 경우 이 기능은 비활성화됩니다.

maxDecodingRate

최대 RT

$$\text{지금까지 소요된 음성 인식 처리 시간} > \text{입력된 음성의 시간} \times \text{maxDecodingRate}$$

인 경우, 음성 인식 처리를 강제로 중단시키는 기능입니다. 이 기능은 모든 음성 데이터를 수신한 후에만 작동한다는 점에 주의하십시오.

기본값은 -1이며, 음수인 경우 이 기능은 비활성화됩니다.

참고로, RT는 음성 인식의 처리 속도를 나타내는 수치로, RT = 음성 인식 처리에 소요된 시간 / 입력된 음성의 시간으로 계산됩니다.

targetResponseTime

목표 응답 시간

$\text{잠정 RT} = \frac{\text{지금까지 소요된 음성 인식 처리 시간}}{\text{지금까지 입력된 음성의 시간}}$ 로 "잠정 RT"를 계산하고,

$$\text{잠정 RT} \approx \frac{\text{지금까지 입력된 음성의 시간} + \text{targetResponseTime}}{\text{지금까지 입력된 음성의 시간}}$$

이 되도록 음성 인식 처리 중에 음성 인식의 처리 속도와 인식률의 균형을 동적으로 조절하는 기능입니다. 단위는 밀리초입니다. "지금까지 입력된 음성의 시간"이 1초 미만이거나, "지금까지 소요된 음성 인식 처리 시간"이 "지금까지 입력된 음성의 시간"보다 짧은 경우(즉, "잠정 RT"가 1 이상이 되지 않은 경우)에는 이 기능이 작동하지 않습니다.

기본값은 0이며, 0인 경우 이 기능은 비활성화됩니다.

targetDecodingRate

목표 RT

$\text{잠정 RT} = \frac{\text{지금까지 소요된 음성 인식 처리 시간}}{\text{지금까지 입력된 음성의 시간}}$ 으로 "잠정 RT"를 계산하고,

$$\text{잠정RT} \approx \text{targetDecodingRate}$$

가 되도록, 음성 인식 처리 중에 음성 인식의 처리 속도와 인식률의 균형을 동적으로 조절하는 기능. "지금까지 입력된 음성의 시간"이 1초 미만이거나, "지금까지 소요된 음성 인식 처리 시간"이 "지금까지 입력된 음성의 시간"보다 짧은 경우(즉, "잠정 RT"가 1 이상이 되지 않은 경우)에는 이 기능이 작동하지 않습니다.

기본값은 -1이며, 음수인 경우 이 기능은 비활성화됩니다.

recognitionTimeout

인식 완료 타임아웃

음성 인식 처리가 일정 시간 내(=recognitionTimeout)에 끝나지 않을 경우, 처리를 강제로 중단시키는 기능. 단위는 밀리초. 이 기능이 활성화된 경우, 한 개의 발화 구간에서 음성 인식이 성공하면 recognitionTimeout으로 설정한 시간 내라도, 이후의 발화 구간에서의 인식 처리는 수행되지 않습니다.

동기식 HTTP 인터페이스 및 비동기 HTTP 인터페이스에서는 서버가 클라이언트로부터 음성 수신을 시작한 시점부터, WebSocket 인터페이스에서는 첫 번째 발화 구간의 시작이 검출된 시점부터 recognitionTimeout의 카운트가 시작됩니다. 또한, recognitionTimeout의 시간 길이는 음성 인식 처리에 소요되는 시간이며, 음성 데이터의 시간과는 다릅니다.

기본값은 0이며, 0인 경우 이 기능은 비활성화됩니다.

예를 들어 일문일답 형식의 보이스봇(voice bot)과 같이, 유효한 인식 결과가 포함된 발화 구간을 조금이라도 빨리 취득하는 것이 중요하고, 그 이후의 발화 구간에 대해서는 인식 처리를 하지 않아도 되는 경우에 유효한 기능입니다. 이 기능의 활성화 시, 발화 도중에 발화 구간이 중간중간 끊어져서 필요한 인식 결과를 얻지 못하는 경우에는 segmenterProperties의 postTime을 조절하십시오.

WebSocket API 고유 파라미터

resultUpdatedInterval

인식 중 이벤트 간격

인식 중 이벤트를 발행하는 간격을 밀리초 단위로 지정합니다.

• 0으로 설정하면 인식 중 이벤트를 발생하지 않습니다.
• 지정된 시간이 경과할 때마다 인식 중 이벤트를 발생시킵니다. 지정된 시간이 경과하는 동안 음성 인식의 처리 중 결과가 업데이트되지 않은 경우, 직전의 인식 중 결과의 끝에 "."을 하나 추가한 것이 전송됩니다. 100 미만의 소수점을 포함한 값이 지정된 경우에는 100의 배수로 올림한 값이 지정된 것으로 취급합니다.

noInputTimeout

발화 시작 대기 타임아웃

발화 구간이 일정 시간(=noInputTimeout) 동안 검출되지 않은 경우, 음성 인식 세션을 강제로 종료하고, 이후의 인식 처리를 모두 취소하는 기능. 단위는 밀리초. 이 시간의 길이는 음성 인식 처리에 소요되는 시간이며, 음성 데이터의 시간과는 다릅니다.

세션이 종료된 경우, 클라이언트에 "e timeout occurred" 오류가 전송됩니다.

기본값은 0이며, 0인 경우 이 기능은 비활성화됩니다.

비동기 HTTP 인터페이스 고유 파라미터

loggingOptOut

로그 저장 여부 변경

loggingOptOut=<True|False> 로그 저장 여부를 지정합니다. True로 설정하면 세션 중 시스템은 로그를 저장하지 않습니다. 기본값은 False입니다.

contentId

사용자 정의 ID

contentId=<임의의 문자열> 사용자 측에서 정의한 임의의 문자열을 지정할 수 있습니다. 해당 세션 중의 상태, 결과 응답에 포함됩니다. 기본값은 None입니다.

compatibleWithSync

결과 포맷의 호환성

compatibleWithSync=<True|False> 동기식 HTTP 인터페이스와 호환되는 형태로 결과를 포맷합니다. 기본값은 False입니다.

speakerDiarization

화자 다이어라이제이션 활성화 옵션

speakerDiarization=<True|False> 화자 다이어라이제이션을 활성화합니다. 기본값은 False입니다. 자세한 내용은 화자 다이어라이제이션을 참조하십시오.

diarizationMinSpeaker

화자 다이어라이제이션의 최소 추정 화자 수

diarizationMinSpeaker=<int> 화자 다이어라이제이션이 활성화되었을 때만 유효하며, 음성에 포함된 최소 화자 수를 지정할 수 있습니다. 1 이상으로 설정해야 합니다. 기본값은 1입니다. 자세한 내용은 화자 다이어라이제이션을 참조하십시오.

diarizationMaxSpeaker

화자 다이어라이제이션의 최대 추정 화자 수

diarizationMaxSpeaker=<int> 화자 다이어라이제이션이 활성화되어 있을 때만 유효하며, 음성에 포함된 최대 화자 수를 지정할 수 있습니다. diarizationMinSpeaker 이상으로 설정해야 합니다. 기본값은 10입니다. 자세한 내용은 화자 다이어라이제이션을 참조하십시오.

sentimentAnalysis

감정 분석 활성화 옵션

sentimentAnalysis=<True|False> 감정 분석을 활성화합니다. 기본값은 False입니다.

자세한 내용은 감정 분석을 참조하십시오.