동기식 HTTP 인터페이스

동기식 HTTP 인터페이스는 요청 파라미터와 음성 데이터를 서버로 전송하면 응답으로 음성 인식 결과를 받을 수 있습니다.

사용 방법

음성 인식 요청 전송

엔드포인트는 로그 저장 여부에 따라 다릅니다.

POST https://acp-api.amivoice.com/v1/recognize　　　(로그 저장 있음)
POST https://acp-api.amivoice.com/v1/nolog/recognize (로그 저장 없음)

각각의 차이점은 로그 저장을 참조하십시오.

요청 파라미터의 필수 파라미터인 인증 정보, 연결 엔진 이름, 음성 데이터를 각각

u={인증 정보}
d={연결 엔진 이름}
a={음성 데이터 바이너리}

와 같이 파라미터 이름을 지정하여 멀티파트 POST로 서버에 전송합니다. 음성 바이너리 데이터는 반드시 HTTP 멀티파트의 마지막 파트에 위치시킵니다.

curl 명령어로 실제 음성 인식 요청을 해보겠습니다. 会話_汎用(대화 범용) 엔진(-a-general)을 사용하여 샘플에 포함된 음성 파일(test.wav)을 음성 인식하려면 다음과 같이 실행합니다. 여기서는 음성 로그를 서버에 남기지 않는 "로그 저장 없음" 엔드포인트로 연결합니다.

curl https://acp-api.amivoice.com/v1/nolog/recognize \
     -F u={APP_KEY} \
     -F d=-a-general \
     -F a=@test.wav

멀티파트 POST 요청의 HTTP 헤더와 HTTP 본문 구조

다음과 같은 구조입니다.

POST https://acp-api.amivoice.com/v1/recognize
Content-Type: multipart/form-data;boundary=some-boundary-string

--some-boundary-string
Content-Disposition: form-data; name="u"

(이 파트에는 <APPKEY>를 저장합니다)
--some-boundary-string
Content-Disposition: form-data; name="d"

-a-general
--some-boundary-string
Content-Disposition: form-data; name="a"
Content-Type: application/octet-stream

(마지막 파트에 음성 데이터를 저장합니다)
--some-boundary-string--

경고

a 파라미터 뒤에 설정된 파라미터는 무시됩니다.

예를 들어, 다음과 같이 u 파라미터를 마지막에 두면 인증 오류가 발생합니다.

curl https://acp-api.amivoice.com/v1/nolog/recognize \
     -F d=-a-general \
     -F a=@test.wav \
     -F u={APP_KEY}      # a 뒤에 u를 지정하고 있음

응답

{
  "results": [
    {
      "tokens": [],
      "tags": [],
      "rulename": "",
      "text": ""
    }
  ],
  "text": "",
  "code": ":"-",
  "message":"received illegal service authorization"
}

또한, 다음과 같이 d 파라미터를 마지막에 두면 지정한 음성 인식 엔진을 찾을 수 없다는 오류가 발생합니다.

curl https://acp-api.amivoice.com/v1/nolog/recognize \
     -F u={APP_KEY} \
     -F a=@test.wav \
     -F d=-a-general      # a 뒤에 d를 지정하고 있음

응답

{
  "results": [
    {
      "tokens": [],
      "tags": [],
      "rulename": "",
      "text": ""
    }
  ],
  "text": "",
  "code": "!",
  "message": "failed to connect to recognizer server (can't find available servers)"
}

응답에 대해서는 음성 인식 결과를 참조하십시오.

음성 포맷 지정

전송하는 음성이 헤더가 있는 음성 데이터(WAV나 Ogg 등)가 아닌 경우, 음성 포맷을 지정해야 합니다. 음성 포맷은 요청 파라미터의 c 뒤에 음성 포맷을 설정합니다.

c={음성 포맷}

지정할 수 있는 음성 포맷은 음성 포맷 대응표를 참조하십시오.

예를 들어, 샘플링 레이트 16kHz, 양자화 비트 수 16bit, 바이트 순서가 리틀 엔디안인 음성 파일 test.pcm을 전송하는 경우, 다음과 같이 파라미터 c에 LSB16K를 지정합니다.

curl https://acp-api.amivoice.com/v1/recognize \
     -F u={APP_KEY} \
     -F d=-a-general \
     -F c=LSB16K \
     -F a=@test.pcm

멀티파트 POST 요청의 HTTP 헤더와 HTTP 본문 구조

다음과 같은 구조입니다.

POST https://acp-api.amivoice.com/v1/recognize
Content-Type: multipart/form-data;boundary=some-boundary-string

--some-boundary-string
Content-Disposition: form-data; name="u"

(이 파트에는 <APPKEY>를 저장합니다)
--some-boundary-string
Content-Disposition: form-data; name="d"

-a-general
--some-boundary-string
Content-Disposition: form-data; name="c"

LSB16K
--some-boundary-string
Content-Disposition: form-data; name="a"
Content-Type: application/octet-stream
(마지막 파트에 음성 데이터를 저장합니다)
--some-boundary-string--

복수 파라미터

프로파일 ID (profileId) 등 필수 파라미터 이외의 요청 파라미터를 설정하고 싶은 경우에는 다음과 같이 d 파라미터에 여러 파라미터를 설정할 수 있습니다.

d=<키>=<값> <키>=<값> <키>=<값> ...

각각의 <키>=<값>은 공백 또는 줄바꿈으로 구분하십시오.
연결 엔진 이름은 필수이므로 이 경우 grammarFileNames=-a-general과 같이 grammarFileNames를 key로 지정하십시오.

예:

curl https://acp-api.amivoice.com/v1/recognize \
     -F u={APP_KEY} \
     -F d="grammarFileNames=-a-general profileId=:user01" \
     -F a=@test.wav

위의 "<키>=<값>"의 <값>은 URL 인코딩이 필요합니다. 예를 들어, profileWords에 표기가 "www", 읽기가 "とりぷるだぶる"라는 단어를 설정하는 경우, 표기와 읽기 사이의 공백을 %20으로, とりぷるだぶる %ED%8A%B8%EB%A6%AC%ED%94%8C%EB%8D%94%EB%B8%94%EC%9C%A0와 같이 인코딩합니다.

curl https://acp-api.amivoice.com/v1/recognize \
     -F u={APP_KEY} \
     -F d="grammarFileNames=-a-general profileWords=hogehoge%20%E3%81%A8%E3%82%8A%E3%81%B7%E3%82%8D%E3%81%A0%E3%81%B6%E3%82%8B" \
     -F a=@test.wav

노트

문자 인코딩은 UTF-8로 지정합니다.
여기서의 URL 인코딩은 공백이 "+"가 아닌 "%20"으로 변환되는 방식입니다

파라미터를 URL 쿼리 문자열로 전송하는 경우

a 이외의 파라미터인 c, d, u는 URL 쿼리 문자열로도, HTTP 본문에 멀티파트 방식으로도 전송할 수 있습니다.

노트

HTTP 헤더의 크기 제한에 걸리지 않도록 모든 파라미터를 멀티파트 방식으로 전송하는 것을 권장합니다.
URL의 쿼리 문자열과 멀티파트 양쪽에 동일한 파라미터가 지정되어 있는 경우, 쿼리 파라미터의 값이 우선됩니다.
u는 쿼리 문자열로 전송할 수 있지만, 통신 경로의 로그 등에 남아 유출될 위험이 있으므로 반드시 HTTP 본문에 멀티파트 방식으로 전송해 주십시오.

d 파라미터를 쿼리 문자열로 전송하는 경우에는 d 파라미터의 값을 다시 URL 인코딩해야 합니다.

https://acp-api.amivoice.com/v1/recognize?d=grammarFileNames%3D-a-general%20profileWords%3Dhogehoge%2520%25E3%2581%25BB%25E3%2581%2592%25E3%2581%25BB%25E3%2581%2592%25E3%2581%25A6%25E3%2581%2599%25E3%2581%25A8

"%"는 "%25"로, "="는 "%3D"로, 공백은 "%20"으로 변환되어 있습니다.

기타 문서

API 레퍼런스는 동기식 HTTP 인터페이스를 참조하십시오.
HTTP 인터페이스를 사용할 때의 통신 처리와 절차를 클래스 라이브러리로 만들어, 음성 인식 애플리케이션에 필요한 인터페이스만 구현하면 쉽게 음성 인식 애플리케이션을 만들 수 있는 클라이언트 라이브러리(Hrp)를 제공하고 있습니다. 먼저 샘플 프로그램 HrpTester를 실행해 보십시오. Hrp 클라이언트 라이브러리의 인터페이스 사양에 대해서는 클라이언트 라이브러리의 Hrp(HTTP 인터페이스 클라이언트)를 참조하십시오.

사용 방법​

음성 인식 요청 전송​

음성 포맷 지정​

복수 파라미터​

파라미터를 URL 쿼리 문자열로 전송하는 경우​

기타 문서​