비동기 HTTP 인터페이스
비동기 HTTP 인터페이스는 장시간의 음성을 텍스트화, 문자 기록하기 위한 논블로킹 HTTP API입니다.
이 API를 사용하려면 다음 단계를 실행합니다.
- 음성 인식 작업 생성
- 폴링하여 음성 인식 작업의 상태를 확인하고 결과 가져오기
1의 작업을 생성하는 방법은 로그의 유무 지정 방법 등이 다르지만, 동기 HTTP 인터페이스와 거의 동일합니다.
엔드포인트
동기 HTTP 인터페이스와 달리, 로그 저장 유무에 관계없이 엔드포인트의 기본은 동일합니다.
https://acp-api-async.amivoice.com/v1/recognitions
1. 작업 생성
엔드포인트:
POST https://acp-api-async.amivoice.com/v1/recognitions
요청
요청 방법은 동기 HTTP 인터페이스와 동일합니다. 자세한 내용은 동기 HTTP 인터페이스 레퍼런스의 요청을 참조하십시오.
d 파라미터에 대하여
동기 HTTP 인터페이스의 d 파라미터를 설정할 수 있습니다. 비동기 HTTP 인터페이스에서만 유효한 파라미터는 다음 표와 같습니다.
| 파라미터명 | 값 | 설명 |
|---|---|---|
| loggingOptOut | True|False | 로그 저장의 유무 변경을 지정합니다. True로 설정하면 세션 중 시스템이 로그를 저장하지 않습니다. 기본값은 False입니다. |
| contentId | 임의의 문자열 | 사용자 측에서 정의한 임의의 문자열을 지정할 수 있습니다. 해당 세션 중 상태, 결과 응답에 포함됩니다. 기본적으로 설정되지 않습니다. |
| compatibleWithSync | True|False | 결과 형식의 호환성. 동기 HTTP 인터페이스와 호환되는 형태로 결과를 포맷합니다. 기본값은 False입니다. |
| speakerDiarization | True|False | 화자 다이어라이제이션 활성화 옵션. 화자 다이어라이제이션을 활성화합니다. 기본값은 False입니다. |
| diarizationMinSpeaker | int | 화자 다이어라이제이션의 최소 추정 화자 수. 화자 다이어라이제이션이 활성화되었을 때만 유효하며, 음성에 포함된 최소 화자 수를 지정할 수 있습니다. 1 이상으로 설정해야 합니다. 기본값은 1입니다. |
| diarizationMaxSpeaker | int | 화자 다이어라이제이션의 최대 추정 화자 수. 화자 다이어라이제이션이 활성화되었을 때만 유효하며, 음성에 포함된 최대 화자 수를 지정할 수 있습니다. diarizationMinSpeaker 이상으로 설정해야 합니다. 기본값은 10입니다. |
| sentimentAnalysis | True|False | 감정 분석을 활성화합니다. 기본값은 False입니다. |
응답
성공 시 응답은 JSON 형식으로 다음 값을 가집니다.
| Key | 설명 |
|---|---|
| sessionid | 사용자의 음성 인식 요청에 대한 작업 ID. |
| text | 항상 ...를 반환합니다. |
예
{"sessionid":"017ac8786c5b0a0504399999","text":"..."}
실패 시 응답은 JSON 형식으로 다음 값을 가집니다.
| Key | 설명 | |
|---|---|---|
| results | 배열(요소 1개) | |
| tokens | 배열(빈 배열) | |
| tags | 배열(빈 배열) | |
| rulename | 문자열(빈 문자열) | |
| text | 문자열(빈 문자열) | |
| text | 문자열(빈 문자열) | |
| code | 결과를 나타내는 1문자 코드. 응답 코드 및 메시지를 참조하십시오. | |
| message | 오류 내용을 나타내는 문자열. 응답 코드 및 메시지를 참조하십시오. |
예
{
"results": [{ "tokens": [], "tags": [], "rulename": "", "text": "" }],
"text": "",
"code": "-",
"message": "received illegal service authorization"
}
2. 작업 상태 확인, 결과 가져오기
엔드포인트:
GET https://acp-api-async.amivoice.com/v1/recognitions/{session_id}
요청
요청 파라미터
| 파라미터명 | 필수 | 전송 방법 | 설명 |
|---|---|---|---|
| session_id | ● | 경로 파라미터 | 작업 생성 응답에서 얻은 ID를 지정합니다. |
인증
APPKEY는 Authorization 헤더에 지정하십시오.
Authorization: Bearer {APPKEY}
응답
요청이 성공한 경우 음성 인식 요청의 상태 status와 부수적인 정보를 반환합니다. 실패한 경우 HTTP 응답 코드 200 이외를 반환합니다. 성공한 경우의 status는 다음 5가지 값을 가집니다.
| status | 설명 |
|---|---|
| queued | 작업이 큐에 등록된 상태. |
| started | 작업이 큐에서 꺼내져 실행 환경을 준비하고 있는 상태. |
| processing | 작업이 실행되고 있는 상태. |
| completed | 음성 인식 프로세스에서 결과를 얻은 상태. code가 빈 문자열, 즉 음성 인식에 성공한 경우 segments에 결과가 포함됩니다. |
| error | 작업을 실행하려고 할 때 또는 작업 실행 중에 어떤 오류가 발생한 상태. error_message에 오류의 상세 내용을 저장합니다. |
응답에 포함되는 정보
queued, started, processing, completed, error의 각 상태에서 포함되는 정보에 대해 다음 표에 정리합니다. 각 상태의 각 머리글자 열(q, s, p, c, e)에서 A로 표시된 것은 항상 포함됩니다. O로 표시된 것은 해당 정보가 있으면 응답에 포함됩니다.
| Key | q | s | p | c | e | 설명 |
|---|---|---|---|---|---|---|
| status | A | A | A | A | A | 작업의 상태. queued, started, processing, completed, error 상태를 가집니다. |
| audio_md5 | A | A | O | 수신한 음성 파일의 MD5 체크섬 값. | ||
| audio_size | A | A | O | 수신한 음성 파일의 크기. | ||
| content_id | O | O | O | O | O | 사용자가 요청 시 설정한 contentId 값. |
| service_id | A | A | A | A | 사용자 ID. | |
| segments | A | 음성 인식 프로세스의 결과. 발화 단위의 음성 인식 결과. | ||||
| utteranceid | A | 음성 인식 프로세스의 결과. 인식 결과 정보 ID. | ||||
| text | A | 음성 인식 프로세스의 결과. '발화 구간의 인식 결과' 모두를 연결한 전체 인식 결과 텍스트. | ||||
| code | A | 음성 인식 프로세스의 결과. 결과를 나타내는 1문자 코드. | ||||
| message | A | 음성 인식 프로세스의 결과. 오류 내용을 나타내는 문자열. | ||||
| error_message | A | 오류 내용을 나타내는 문자열 |
completed(음성 인식 결과) 응답의 상세
status가 completed일 때는 음성 인식의 결과를 JSON 형식으로 반환합니다. 동기 HTTP 인터페이스와 달리 인식 결과가 발화 단위로 segments 아래에 배치됩니다.
| 설명 | ||||
|---|---|---|---|---|
| segments | ||||
| results | '발화 구간의 인식 결과' 배열 | |||
| confidence | 신뢰도(0 ～ 1의 값. 0: 신뢰도 낮음, 1: 신뢰도 높음) | |||
| starttime | 발화 시작 시간 (음성 데이터의 선두가 0) | |||
| endtime | 발화 종료 시간 (음성 데이터의 선두가 0) | |||
| tags | 미사용(빈 배열) | |||
| rulename | 미사용(빈 문자열) | |||
| text | 인식 결과 텍스트 | |||
| tokens | 인식 결과 텍스트의 형태소 배열 | |||
| written | 형태소(단어)의 표기 | |||
| confidence | 형태소의 신뢰도(인식 결과의 우도) | |||
| starttime | 형태소의 시작 시간 (음성 데이터의 선두가 0) | |||
| endtime | 형태소의 종료 시간(음성 데이터의 선두가 0) | |||
| spoken | 형태소의 읽기 | |||
| label | 화자 레이블(speaker0, speaker1, ...) 요청 시 speakerDiarization=True가 지정된 경우에만 결과에 포함됩니다. | |||
| utteranceid | 인식 결과 정보 ID | |||
| text | '발화 구간의 인식 결과' 모두를 연결한 전체 인식 결과 텍스트 | |||
| code | 결과를 나타내는 1문자 코드. 응답 코드 및 메시지를 참조하십시오. | |||
| message | 오류 내용을 나타내는 문자열. 응답 코드 및 메시지를 참조하십시오. |
error(오류) 응답의 상세
음성 인식 처리에 실패했을 때의 응답 예입니다. 각 값은 응답에 포함되는 정보를 참조하십시오.
예
{
"status": "error",
"audio_md5":"40f59fe5fc7745c33b33af44be43f6ad",
"audio_size":306980,
"service_id":"{YOUR_SERVICE_ID}",
"session_id":"017c25ec12c00a304474a999",
"error_message": "ERROR: Failed to transcribe in recognition process - amineth_result=0, amineth_code='o', amineth_message='recognition result is rejected because confidence is below the threshold'"
}
오류 응답
작업 상태 확인, 결과 가져오기 엔드포인트 호출에 실패한 경우 HTTP 상태 코드가 200이 아닌 값을 반환합니다. 응답 본문에는 다음 정보를 포함하는 JSON 데이터를 반환합니다.
| 파라미터 이름 | 설명 |
|---|---|
| errorCode | 응답 코드. |
| errorMessage | 오류 메시지. |
예시:
{
"errorCode":401,
"errorMessage":"Invalid authorization header format"
}
상태 코드 및 오류 메시지
호출이 실패한 경우의 상태 코드와 오류 메시지는 다음과 같습니다.
| HTTP 상태 코드 | 오류 메시지 | 설명 |
|---|---|---|
| 401 | No app_key | APPKEY가 설정되지 않음 |
| 401 | No authorization header | Authorization 헤더가 설정되지 않음 |
| 401 | Invalid authorization header format | Authorization 헤더의 형식이 잘못됨 |
| 401 | Failed to authorize for the app_key | 지정된 APPKEY로 인증 실패 |
| 404 | Specified session_id is not found | 지정된 session_id의 작업을 찾을 수 없습니다. 올바른 session_id를 지정했음에도 이 오류가 발생하는 경우, 다음과 같은 경우가 고려될 수 있습니다.- 데이터 보존 기간이 지났을 때 - 요청 시 사용자와 다른 사용자가 작업 상태나 결과를 가져오려고 할 때 |
| 500 | - | 내부 오류. 여기로 문의해 주십시오. |