요청 파라미터

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

파라미터 목록

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

파라미터 이름	설명	필수	동기 HTTP	WebSocket	비동기 HTTP
authorization	인증 정보	●	●	●	●
grammarFileNames	연결 엔진 이름	●	●	●	●
profileId	프로파일 ID		●	●	●
profileWords	단어 등록 목록		●	●	●
keepFillerToken	필러 단어(불필요한 단어)의 자동 삭제 억제		●	●	●
segmenterProperties	발화 구간 검출・화자 다이어라이제이션 파라미터		●	●	● （*１）
extension	사용량 집계 태그
resultUpdatedInterval	인식 중 이벤트 간격			●
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

단어 등록 목록

세션에서 유효한 단어를 등록할 수 있습니다. 하나의 단어는 "표기 (반각 공백) 읽기" 형식으로 등록합니다. 클래스명을 지정할 경우 "표기 (반각 공백) 읽기 (반각 공백) 클래스명"으로 하십시오. 여러 개를 등록할 경우 단어와 단어를 "|"(반각 수직선)으로 구분합니다. 값의 포맷은 다음과 같습니다 (클래스명을 지정하지 않은 경우의 예입니다).

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

자세한 내용은 단어 등록을 참조하십시오.

keepFillerToken

필러 단어(불필요한 단어)의 자동 삭제 억제

1 또는 0을 지정합니다. 기본값은 0입니다. 음성 인식 결과에 포함된 필러 단어 ("아", "어" 등)를 자동으로 제거하고 싶지 않을 때 1을 지정합니다. 필러 단어의 자동 삭제도 참조하십시오.

필러 단어는 단어의 앞뒤를 반각 "%"로 둘러싸여 있습니다. 다음은 필러 단어의 예입니다.

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

팁

AmiVoice Tech Blog의 AmiVoice API로 불필요한 단어(필러)를 표시할지 제거할지 선택하는 방법 (일본어 블로그)도 참조하십시오.

segmenterProperties

발화 구간 검출 파라미터

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

주의

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

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

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

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

• useDiarizer
  • 1을 설정하면 동기 HTTP나 WebSocket 인터페이스에서 화자 다이어라이제이션을 활성화합니다. 기본값은 비활성화입니다. 자세한 내용은 화자 다이어라이제이션을 참조하십시오.
• diarizerAlpha
  • 동기 HTTP나 WebSocket 인터페이스에서의 화자 다이어라이제이션의 새로운 화자 출현 용이성을 제어하는 파라미터입니다. 큰 값을 지정할수록 새로운 화자가 출현하기 쉽고, 작은 값을 지정할수록 새로운 화자가 출현하기 어려워집니다. diarizerAlpha=0은 특별하여 1e0, 즉 1이 지정된 것으로 취급됩니다. 아무것도 설정하지 않으면 diarizerAlpha=0이 지정된 것으로 간주됩니다.
• diarizerTransitionBias
  • 동기 HTTP나 WebSocket 인터페이스에서의 화자 다이어라이제이션의 화자 전환 용이성을 제어하는 파라미터입니다. 큰 값을 지정할수록 화자가 전환되기 쉽고, 작은 값을 지정할수록 화자가 전환되기 어려워집니다. diarizerTransitionBias=0은 특별하여 1e-40이 지정된 것으로 취급됩니다. 단, 8kHz 음성에 대응하는 엔진, 예를 들어 범용 엔진(-a-general)을 사용하고 샘플링 레이트가 8k인 음성을 전송한 경우는 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 계정을 여러 시스템이나 환경, 최종 사용자 등이 공유하는 경우, 임의의 속성별 사용량을 확인할 수 있도록 사용량 집계 태그를 설정할 수 있습니다. 자세한 내용은 사용량 집계 태그를 참조하십시오.

WebSocket API 고유 파라미터

resultUpdatedInterval

인식 중 이벤트 간격

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

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

비동기 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입니다.

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