동기식 HTTP 인터페이스
동기식 HTTP 인터페이스는 짧은 음성 파일을 간단하게 텍스트로 변환할 수 있는 Web API입니다.
엔드포인트
음성 인식을 요청하는 엔드포인트입니다. 로그 저장 여부에 따라 엔드포인트가 다릅니다. 자세한 내용은 로그 저장을 참조하십시오.
POST https://acp-api.amivoice.com/v1/recognize (로그 저장 있음)
POST https://acp-api.amivoice.com/v1/nolog/recognize (로그 저장 없음)
요청
요청 파라미터 목록
파라미터명 | 필수 | 설명 |
|---|---|---|
| u | ● | 마이페이지에 표시된 APPKEY 또는 원타임 APPKEY를 지정합니다. |
| d | ● | 음성 인식 요청에 관한 다양한 파라미터를 설정합니다. d파라미터를 참조하십시오. |
| a | ● | 음성의 바이너리 데이터를 설정합니다. 이 데이터는 반드시 HTTP 멀티파트의 마지막 파트여야 합니다. 전송 가능한 음성 데이터에 대해서는 이용 가이드의 음성 포맷)을 참조하십시오. |
| c | RAW 데이터(PCM)를 전송하는 경우의 포맷명입니다. 설정할 수 있는 값은 음성 포맷을 참조하십시오. |
- 음성 데이터 이외에는 쿼리 파라미터나 멀티파트로 전송할 수 있습니다. 쿼리 파라미터에 d파라미터를 설정하면 요청 라인의 상한을 초과할 가능성이 있으므로 멀티파트로 전송하는 것을 권장합니다.
- 쿼리 파라미터와 멀티파트 양쪽에 같은 파라미터가 지정되어 있는 경우, 쿼리 파라미터에 설정한 값이 우선됩니다.
d파라미터
d파라미터 내에는 key-value 형식의 파라미터를 반각 스페이스로 구분하여 지정합니다. d파라미터의 형식은 다음과 같습니다.
예:
<키>=<값> <키>=<값> <키>=<값> ...
스페이스가 포함된 <값>은 URL 인코딩하십시오. 다음 예에서는 grammarFileNames와 profileWords의 2개 파라미터를 지정하고 있습니다. profileWords에는 표기가 "www", 읽기가 "とりぷるだぶる"인 단어를 설정하고 있습니다.
grammarFileNames=-a-general profileWords=www%20%E3%81%A8%E3%82%8A%E3%81%B7%E3%82%8B%E3%81%A0%E3%81%B6%E3%82%8B
d파라미터에 지정할 수 있는 것은 다음과 같습니다. 연결 엔진 이름(grammarFileNames)은 필수입니다.
| 파라미터명 | 값 | 설명 |
|---|---|---|
| grammarFileNames | {연결 엔진 이름} | 연결 엔진 이름 지정. 사용 가능한 연결 엔진 이름 목록은 마이페이지에 표시되어 있습니다. 음성 인식 엔진 목록도 참조하십시오. |
| profileId | 문자열 | 등록 단어를 지정하기 위한 ID. 자세한 내용은 단어 등록을 참조하십시오. |
| profileWords | 문자열 | 세션 중에만 유효하게 하고 싶은 단어 등록 목록. {표기} {읽기} 또는 {표기} {읽기} {클래스명}과 같이 지정합니다. 여러 단어를 지정하는 경우 |로 연결합니다. 자세한 내용은 단어 등록을 참조하십시오. |
| keepFillerToken | 0|1 | 필러 단어 출력 지정. 1로 설정하면 필러를 삭제하지 않습니다. 기본값은 0이며 필러 단어는 인식 결과에서 자동으로 제거됩니다. 필러 단어 출력 지정을 참조하십시오. |
- profileId에는 반각 영숫자 및 「-」(반각 마이너스), 「_」(반각 언더스코어)로 구성된 문자열을 사용할 수 있습니다. 단, 「__」(반각 언더스코어 2자)로 시작하는 문자열은 음성 인식 엔진 측에서 예약되어 있으므로 「__」(반각 언더스코어 2자)로 시작하는 문자열은 지정하지 마십시오.
profileId와profileWords를 모두 지정하는 경우에는 profileId를 먼저 지정해야 합니다.
응답
응답의 구조
<result>에는 다음과 같은 JSON이 포함되어 있습니다.
| 설명 | |||
|---|---|---|---|
| results | 「발화 구간의 인식 결과」 배열 ※배열 형식이지만 요소 수는 항상 1개입니다. | ||
| confidence | 신뢰도(0 ~ 1 값. 0: 신뢰도 낮음, 1: 신뢰도 높음) | ||
| starttime | 발화 시작 시간 (음성 데이터의 시작이 0) | ||
| endtime | 발화 종료 시간 (음성 데이터의 시작이 0) | ||
| tags | 미사용(빈 배열) | ||
| rulename | 미사용(빈 문자열) | ||
| text | 인식 결과 텍스트 | ||
| tokens | 인식 결과 텍스트의 형태소 배열 | ||
| written | 형태소(단어)의 표기 | ||
| confidence | 형태소의 신뢰도(인식 결과의 우도) | ||
| starttime | 형태소의 시작 시간 (음성 데이터의 시작이 0) | ||
| endtime | 형태소의 종료 시간 (음성 데이터의 시작이 0) | ||
| spoken | 형태소의 읽기 *3 | ||
| utteranceid | 인식 결과 정보 ID *1 | ||
| text | 「발화 구간의 인식 결과」의 모든 것을 결합한 전체 인식 결과 텍스트 | ||
| code | 결과를 나타내는 1문자 코드 *2 | ||
| message | 오류 내용을 나타내는 문자열 *2 |
*1 인식 결과 정보 ID는 WebSocket 음성 인식 프로토콜의 경우 발화 구간별 인식 결과 정보에 부여된 ID가 됩니다. HTTP 음성 인식 프로토콜의 경우 1 세션에서 업로드된 (여러 발화 구간을 포함할 수 있는) 음성 데이터 전체의 인식 결과 정보에 부여된 ID가 됩니다.
*2 인식 성공 시: body.code == "" 및 body.message == "" 및 body.text != "" 인식 실패 시: body.code != "" 및 body.message != "" 및 body.text == ""
*3 일본어 엔진의 인식 결과의 spoken은 히라가나입니다. 영어 엔진의 인식 결과의 spoken은 읽기가 아닙니다(무시해 주십시오). 중국어 엔진의 인식 결과의 spoken은 병음(pinyin)입니다.
code와 message 목록
<result>에 포함된 code와 message에 값이 설정되어 있으면 요청이 실패했음을 알 수 있습니다. 실패 원인은 다음과 같습니다.
| code | message | 설명 |
|---|---|---|
| + | received unsupported audio format | 지원되지 않는 음성 데이터 형식의 음성 데이터를 수신 |
| - | received illegal service authorization | 부적절한 APPKEY(서비스 인증 키 문자열)을 수신 |
| ! | failed to connect to recognizer server | 음성 인식 서버 내 통신 실패(DSRM 또는 DSRS 연결 실패) |
| > | failed to send audio data to recognizer server | 음성 인식 서버 내 통신 실패(DSRS로의 음성 데이터 전송 실패) |
| < | failed to receive recognition result from recognizer server | 음성 인식 서버 내 통신 실패(DSRS로부터의 인식 결과 수신 실패) |
| # | received invalid recognition result from recognizer server | 음성 인식 서버 내 통신 실패(DSRS로부터 수신한 인식 결과의 형식이 잘못됨) |
| $ | timeout occurred while receiving audio data from client | 클라이언트로부터의 음성 데이터 수신 중 무통신 타임아웃이 발생 |
| % | received too large audio data from client | 클라이언트로부터 수신한 음성 데이터 바이트 수가 너무 큼(WebSocket 인터페이스에서는 발생하지 않음) |
| o | recognition result is rejected because confidence is below the threshold | 인식 결과 전체의 신뢰도가 신뢰도 임계값을 하회하여 인식에 실패 ※ 받은 음성 데이터 전체에서 발화가 1개도 검출되지 않아 인식 결과를 반환할 수 없는 경우에도 이 오류가 반환됩니다. 발화 검출에 실패하는 원인으로는 음성 데이터의 손실이나 음성 데이터 포맷의 지정 오류가 고려됩니다. |
| b | recognition result is rejected because recognizer server is busy | 음성 인식 서버가 혼잡하여 인식에 실패 |
| x | recognition result is rejected because grammar files are not loaded | 사전이 로드되지 않아 인식에 실패 |
| c | recognition result is rejected because the recognition process is cancelled | 인식 처리 중단 요청이 있어 인식에 실패 |
| ? | recognition result is rejected because fatal error occurred in recognizer server | 음성 인식 서버에서 인식 중 치명적 오류가 발 생하여 인식에 실패 |
| ^ | invalid parameter (...) | 잘못된 파라미터가 지정되었습니다.비동기 HTTP 인터페이스의 경우에만 해당됩니다. |