비동기 HTTP 인터페이스
비동기 HTTP 인터페이스는 장시간의 음성을 텍스트로 변환하기 위한 논블로킹 HTTP API입니다.
이 API를 사용하려면 다음 단계로 실행합니다.
- 음성 인식 작업 생성하기
- 폴링하여 음성 인식 작업 상태를 확인하고 결과 가져오기
사용 방법
1. 음성 인식 작업 생성하기
작업 생성 API 요청은 동기 HTTP 인터페이스와 동일하게 요청 파라미터를 설정하고, 비동기 HTTP 인터페이스의 엔드포인트로 요청을 전송합니다.
POST https://acp-api-async.amivoice.com/v1/recognitions
예를 들어, curl 명령으로 로그 저장 없이 test.wav 파일의 음성 인식 요청을 보내려면 다음과 같이 합니다.
curl https://acp-api-async.amivoice.com/v1/recognitions \
-F u={APP_KEY} \
-F d="grammarFileNames=-a-general loggingOptOut=True" \
-F a=@test.wav
동기 HTTP 인터페이스와는 엔드포인트가 다르지만, 요청 파라미터의 설정 방법은 동일합니다.
감정 분석 등 일부 파라미터는 비동기 HTTP 인터페이스에서만 지원됩니다.
동기 HTTP 인터페이스와 달리 로그 저장 여부는 엔드포인트가 아닌 요청 파라미터로 지정합니다.
기본적으로 로그 저장이 활성화되어 있습니다. 로그 저장을 비활성화하려면 d
파라미터에 loggingOptOut=True
를 지정하십시오.
성공한 경우
성공 시 응답에는 sessionid
가 포함됩니다. 이는 사용자의 음성 인식 요청에 대한 작업 ID로, 작업 상태를 확인하거나 결과를 얻는 데 사용됩니다.
text
는 항상 "..."를 반환합니다.
예
{"sessionid":"017ac8786c5b0a0504399999","text":"..."}
실패한 경우
실패 시 응답에는 sessionid
가 포함되지 않습니다. code
와 message
로 실패 원인을 판단할 수 있습니다.
응답 코드와 메시지를 참조하십시오.
예
{
"results": [{ "tokens": [], "tags": [], "rulename": "", "text": "" }],
"text": "",
"code": "-",
"message": "received illegal service authorization"
}
2. 음성 인식 작업 상태 확인 및 결과 가져오기
음성 인식 결과 요청이 성공하면 작업 상태를 확인하고 status
가 completed
또는 error
가 될 때까지 폴링하십시오.
작업 상태 가져오기
작업은 서버 측에서 순차적으로 실행됩니다. 작업 상태를 확인하거나 결과를 가져오려면 결과 조회용 엔드포인트 GET /v1/recognitions/{session_id}
에 요청합니다.
sessionid
에는 작업 생성 시 얻은 작업 ID를 설정합니다. 요청 파라미터의 인증 정보(authorization
)는 Authorization
헤더에 지정하십시오.
curl로 실행하는 경우 다음과 같습니다. 여기서는 sessionid
가 017c25ec12c00a304474a999라고 가정합니다.
curl -H "Authorization: Bearer {APPKEY}" \
https://acp-api-async.amivoice.com/v1/recognitions/017c25ec12c00a304474a999
queued 상태
요청을 보낸 직후에는 status
가 queued
상태가 됩니다.
{"service_id":"{YOUR_SERVICE_ID}","session_id":"017c25ec12c00a304474a999","status":"queued"}
started 상태
큐에서 작업이 꺼내지면 status
는 started
상태가 됩니다.
{"service_id":"{YOUR_SERVICE_ID}","session_id":"017c25ec12c00a304474a999","status":"started"}
processing 상태
실제로 음성 인식 처리가 시작되면 status
는 processing
상태가 됩니다. 아래 샘플을 참조하십시오. 여기서는 가독성을 위해 결과를 줄바꿈 처리합니다.
API가 수신한 음성 크기(audio_size
)나 MD5 체크섬(audio_md5
)을 사용하여 음성이 올바르게 전송되었는지 확인할 수 있습니다.
processing
에서 다음 completed
상태가 되기까지 걸리는 시간은 음성 길이에 따라 다르지만, 대략 음성 길이의 0.5~1.5배 정도를 기준으로 하십시오.
{
"audio_md5":"40f59fe5fc7745c33b33af44be43f6ad",
"audio_size":306980,
"service_id":"{YOUR_SERVICE_ID}",
"session_id":"017c25ec12c00a304474a999",
"status":"processing"
}
completed 상태
음성 인식이 완료되면 status
는 completed
상태가 됩니다. 이때 응답의 results
와 segments
에서 음성 인식 결과를 얻을 수 있습니다. 결과는 음성 인식 서버의 처리가 완료된 후 일정 기간 서버에 저장됩니다. 저장 기간은 비동기 HTTP 인터페이스의 제한의 "음성 인식 결과 보존 기간"을 참조하십시오.
인식 결과를 포함한 응답의 자세한 내용은 음성 인식 결과를 참조하십시오.
일정 기간이 지나 삭제된 결과에 접근하면 404 NOT FOUND
오류가 발생합니다. 오류에 대해서는 레퍼런스의 오류 응답 목록을 참조하십시오.
error 상태
어떤 이유로 음성 인식에 실패한 경우 status
가 error
상태가 됩니다. 이때 error_message
에는 오류의 원인이 설정됩니다.
예:
{
"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'"
}
error_message
에는 amineth_code='{응답 코드}'
와 amineth_message='{오류 메시지}'
가 포함될 수 있습니다. 자세한 내용은 응답 코드와 메시지 세부 사항의 표를 참조하십시오.
특히 오류 메시지에 amineth_code='o'
가 포함된 경우, 클라이언트의 요청 방법이나 음성 파일에 문제가 있으므로 재시도해도 같은 결과가 됩니다. 자세한 내용은 "리젝트 (응답 코드=o)"를 참조하십시오. o
이외의 오류인 경우 AmiVoice API 기반의 문제일 가능성이 높으므로 잠시 기다렸다가 재시도하십시오.
콘텐츠 ID
요청 시 d
파라미터의 contentId
에는 자유롭게 문자열을 설정할 수 있습니다. 예를 들어, 애플 리케이션이 발행한 ID나 파일 이름, 사용자 등의 정보를 설정해 두면 인식 결과의 일부로 나중에 해당 정보를 얻을 수 있습니다.
예를 들어, curl 명령으로 contentId
에 파일 이름을 설정하여 요청을 보내려면 다음과 같이 합니다.
curl https://acp-api-async.amivoice.com/v1/recognitions \
-F u={APP_KEY} \
-F d="grammarFileNames=-a-general loggingOptOut=True contentId=test.wav" \
-F a=@test.wav
작업 상태나 결과를 가져올 때 다음과 같이 content_id
가 포함됩니다.
{"content_id":"test.wav","service_id":"{YOUR_SERVICE_ID}","session_id":"017c25ec12c00a304474a999","status":"queued"}
샘플 코드
비동기 HTTP 인터페이스의 전형적인 처리 흐름을 Python 샘플 코드로 보여줍니다.
요청 파라미터
실행에는 AmiVoice API의 APPKEY가 필요합니다. 다음 줄에 자신의 AmiVoice API APPKEY를 설정합니다.
app_key = 'TODO: Please set APPKEY here'
d
파라미터에 설정할 옵션을 결정합니다. 여기서는 다음과 같이 합니다.
- 엔진: 범용 (
grammarFileNames=-a-general
) - 로그 저장: 없음 (
loggingOptOut=True
) - 콘텐츠 ID: 파일 이름 (
contentId=filename
) - 화자 다이어라이제이션: 활성화 (
speakerDiarization=True
) - 화자 수: 최대=최소=2 (
diarizationMinSpeaker=2
,diarizationMaxSpeaker=2
) - 감정 분석: 활성화 (
sentimentAnalysis=True
)
domain = {
'grammarFileNames': '-a-general',
'loggingOptOut': 'True',
'contentId': filename,
'speakerDiarization': 'True',
'diarizationMinSpeaker': '2',
'diarizationMaxSpeaker': '2',
'sentimentAnalysis': 'True',
...
또한 두 개의 단어를 등록하고 있습니다. profileId
는 주석 처리하여 등록된 단어가 해당 세션에서만 유효하도록 합니다. 자세한 내용은 단어 등록을 참조하십시오.
#'profileId': 'test',
'profileWords': 'wwww よんこだぶる|www2 とりぷるだぶる',
}
d
파라미터에 설정할 key-value의 value는 URL 인코딩합니다. Python에서는 urllib.parse.quote
를 사용합니다.
params = {
'u': app_key,
'd': ' '.join([f'{key}={urllib.parse.quote(value)}' for key, value in domain.items()]),
}
logger.info(params)