메인 콘텐츠로 건너뛰기

동기식 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={API_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"

(이 파트에는 <API_KEY>를 저장합니다)
--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={API_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={API_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={API_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"

(이 부분에는 <API_KEY>를 저장합니다)
--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={API_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={API_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"으로 변환됩니다.

결과​

실행에 성공하면 다음과 같이 JSON 형식의 결과를 얻을 수 있습니다.

{"results":[{"tokens":[{"written":"\u30a2\u30c9\u30d0\u30f3\u30b9\u30c8\u30fb\u30e1\u30c7\u30a3\u30a2","confidence":1.00,"starttime":522,"endtime":1578,"spoken":"\u3042\u3069\u3070\u3093\u3059\u3068\u3081\u3067\u3043\u3042"},{"written":"\u306f","confidence":1.00,"starttime":1578,"endtime":1866,"spoken":"\u306f"},{"written":"\u3001","confidence":0.72,"starttime":1866,"endtime":2026,"spoken":"_"},{"written":"\u4eba","confidence":1.00,"starttime":2026,"endtime":2314,"spoken":"\u3072\u3068"},{"written":"\u3068","confidence":1.00,"starttime":2314,"endtime":2426,"spoken":"\u3068"},{"written":"\u6a5f\u68b0","confidence":1.00,"starttime":2426,"endtime":2826,"spoken":"\u304d\u304b\u3044"},{"written":"\u3068","confidence":1.00,"starttime":2826,"endtime":2938,"spoken":"\u3068"},{"written":"\u306e","confidence":1.00,"starttime":2938,"endtime":3082,"spoken":"\u306e"},{"written":"\u81ea\u7136","confidence":1.00,"starttime":3082,"endtime":3434,"spoken":"\u3057\u305c\u3093"},{"written":"\u306a","confidence":1.00,"starttime":3434,"endtime":3530,"spoken":"\u306a"},{"written":"\u30b3\u30df\u30e5\u30cb\u30b1\u30fc\u30b7\u30e7\u30f3","confidence":1.00,"starttime":3530,"endtime":4378,"spoken":"\u3053\u307f\u3085\u306b\u3051\u30fc\u3057\u3087\u3093"},{"written":"\u3092","confidence":1.00,"starttime":4378,"endtime":4442,"spoken":"\u3092"},{"written":"\u5b9f\u73fe","confidence":1.00,"starttime":4442,"endtime":4922,"spoken":"\u3058\u3064\u3052\u3093"},{"written":"\u3057","confidence":1.00,"starttime":4922,"endtime":5434,"spoken":"\u3057"},{"written":"\u3001","confidence":0.45,"starttime":5434,"endtime":5562,"spoken":"_"},{"written":"\u8c4a\u304b","confidence":1.00,"starttime":5562,"endtime":5994,"spoken":"\u3086\u305f\u304b"},{"written":"\u306a","confidence":1.00,"starttime":5994,"endtime":6090,"spoken":"\u306a"},{"written":"\u672a\u6765","confidence":1.00,"starttime":6090,"endtime":6490,"spoken":"\u307f\u3089\u3044"},{"written":"\u3092","confidence":1.00,"starttime":6490,"endtime":6554,"spoken":"\u3092"},{"written":"\u5275\u9020","confidence":0.93,"starttime":6554,"endtime":7050,"spoken":"\u305d\u3046\u305e\u3046"},{"written":"\u3057\u3066","confidence":0.99,"starttime":7050,"endtime":7210,"spoken":"\u3057\u3066"},{"written":"\u3044\u304f","confidence":1.00,"starttime":7210,"endtime":7418,"spoken":"\u3044\u304f"},{"written":"\u3053\u3068","confidence":1.00,"starttime":7418,"endtime":7690,"spoken":"\u3053\u3068"},{"written":"\u3092","confidence":1.00,"starttime":7690,"endtime":7722,"spoken":"\u3092"},{"written":"\u76ee\u6307\u3057","confidence":0.76,"starttime":7722,"endtime":8090,"spoken":"\u3081\u3056\u3057"},{"written":"\u307e\u3059","confidence":0.76,"starttime":8090,"endtime":8506,"spoken":"\u307e\u3059"},{"written":"\u3002","confidence":0.82,"starttime":8506,"endtime":8794,"spoken":"_"}],"confidence":0.998,"starttime":250,"endtime":8794,"tags":[],"rulename":"","text":"\u30a2\u30c9\u30d0\u30f3\u30b9\u30c8\u30fb\u30e1\u30c7\u30a3\u30a2\u306f\u3001\u4eba\u3068\u6a5f\u68b0\u3068\u306e\u81ea\u7136\u306a\u30b3\u30df\u30e5\u30cb\u30b1\u30fc\u30b7\u30e7\u30f3\u3092\u5b9f\u73fe\u3057\u3001\u8c4a\u304b\u306a\u672a\u6765\u3092\u5275\u9020\u3057\u3066\u3044\u304f\u3053\u3068\u3092\u76ee\u6307\u3057\u307e\u3059\u3002"}],"utteranceid":"20220602/14/018122d637320a301bc194c9_20220602_141433","text":"\u30a2\u30c9\u30d0\u30f3\u30b9\u30c8\u30fb\u30e1\u30c7\u30a3\u30a2\u306f\u3001\u4eba\u3068\u6a5f\u68b0\u3068\u306e\u81ea\u7136\u306a\u30b3\u30df\u30e5\u30cb\u30b1\u30fc\u30b7\u30e7\u30f3\u3092\u5b9f\u73fe\u3057\u3001\u8c4a\u304b\u306a\u672a\u6765\u3092\u5275\u9020\u3057\u3066\u3044\u304f\u3053\u3068\u3092\u76ee\u6307\u3057\u307e\u3059\u3002","code":"","message":""}

인식 결과에 포함되는 일본어는, UTF-8 을 Unicode 이스케이프한 형식입니다. 사용 중인 개발 언어에 포함된 JSON 파서 등을 이용하면 간단히 원래 형태로 복원할 수 있습니다. 여기에서는 jq 명령을 사용하여 변환합니다.

curl -F a=@test.wav "https://acp-api.amivoice.com/v1/recognize?d=-a-general&u=<API_KEY>" | jq

이제는 인식 결과의 일본어를 읽을 수 있는 형식으로, 들여쓰기가 적용된 상태로 표시될 것입니다. 결과에 포함된 text 항목을 찾아보십시오. 여기에 음성을 텍스트로 변환한 결과가 포함되어 있습니다.

"text": "アドバンスト・メディアは、人と機械との自然なコミュニケーションを実現し、豊かな未来を創造していくことを目指します。"

아래는 응답의 완전한 예시입니다. 전사 결과 뿐만 아니라, 단어 단위의 결과 및 음성 시간, 신뢰도 등의 정보도 얻을 수 있습니다. 자세한 내용은, 음성 인식 결과 형식를 참조하십시오.

응답
{
  "results": [
    {
      "tokens": [
        {
          "written": "アドバンスト・メディア",
          "confidence": 1,
          "starttime": 522,
          "endtime": 1578,
          "spoken": "あどばんすとめでぃあ"
        },
        {
          "written": "は",
          "confidence": 1,
          "starttime": 1578,
          "endtime": 1866,
          "spoken": "は"
        },
        {
          "written": "、",
          "confidence": 0.72,
          "starttime": 1866,
          "endtime": 2026,
          "spoken": "_"
        },
        {
          "written": "人",
          "confidence": 1,
          "starttime": 2026,
          "endtime": 2314,
          "spoken": "ひと"
        },
        {
          "written": "と",
          "confidence": 1,
          "starttime": 2314,
          "endtime": 2426,
          "spoken": "と"
        },
        {
          "written": "機械",
          "confidence": 1,
          "starttime": 2426,
          "endtime": 2826,
          "spoken": "きかい"
        },
        {
          "written": "と",
          "confidence": 1,
          "starttime": 2826,
          "endtime": 2938,
          "spoken": "と"
        },
        {
          "written": "の",
          "confidence": 1,
          "starttime": 2938,
          "endtime": 3082,
          "spoken": "の"
        },
        {
          "written": "自然",
          "confidence": 1,
          "starttime": 3082,
          "endtime": 3434,
          "spoken": "しぜん"
        },
        {
          "written": "な",
          "confidence": 1,
          "starttime": 3434,
          "endtime": 3530,
          "spoken": "な"
        },
        {
          "written": "コミュニケーション",
          "confidence": 1,
          "starttime": 3530,
          "endtime": 4378,
          "spoken": "こみゅにけーしょん"
        },
        {
          "written": "を",
          "confidence": 1,
          "starttime": 4378,
          "endtime": 4442,
          "spoken": "を"
        },
        {
          "written": "実現",
          "confidence": 1,
          "starttime": 4442,
          "endtime": 4922,
          "spoken": "じつげん"
        },
        {
          "written": "し",
          "confidence": 1,
          "starttime": 4922,
          "endtime": 5434,
          "spoken": "し"
        },
        {
          "written": "、",
          "confidence": 0.45,
          "starttime": 5434,
          "endtime": 5562,
          "spoken": "_"
        },
        {
          "written": "豊か",
          "confidence": 1,
          "starttime": 5562,
          "endtime": 5994,
          "spoken": "ゆたか"
        },
        {
          "written": "な",
          "confidence": 1,
          "starttime": 5994,
          "endtime": 6090,
          "spoken": "な"
        },
        {
          "written": "未来",
          "confidence": 1,
          "starttime": 6090,
          "endtime": 6490,
          "spoken": "みらい"
        },
        {
          "written": "を",
          "confidence": 1,
          "starttime": 6490,
          "endtime": 6554,
          "spoken": "を"
        },
        {
          "written": "創造",
          "confidence": 0.93,
          "starttime": 6554,
          "endtime": 7050,
          "spoken": "そうぞう"
        },
        {
          "written": "して",
          "confidence": 0.99,
          "starttime": 7050,
          "endtime": 7210,
          "spoken": "して"
        },
        {
          "written": "いく",
          "confidence": 1,
          "starttime": 7210,
          "endtime": 7418,
          "spoken": "いく"
        },
        {
          "written": "こと",
          "confidence": 1,
          "starttime": 7418,
          "endtime": 7690,
          "spoken": "こと"
        },
        {
          "written": "を",
          "confidence": 1,
          "starttime": 7690,
          "endtime": 7722,
          "spoken": "を"
        },
        {
          "written": "目指し",
          "confidence": 0.76,
          "starttime": 7722,
          "endtime": 8090,
          "spoken": "めざし"
        },
        {
          "written": "ます",
          "confidence": 0.76,
          "starttime": 8090,
          "endtime": 8506,
          "spoken": "ます"
        },
        {
          "written": "。",
          "confidence": 0.82,
          "starttime": 8506,
          "endtime": 8794,
          "spoken": "_"
        }
      ],
      "confidence": 0.998,
      "starttime": 250,
      "endtime": 8794,
      "tags": [],
      "rulename": "",
      "text": "アドバンスト・メディアは、人と機械との自然なコミュニケーションを実現し、豊かな未来を創造していくことを目指します。"
    }
  ],
  "utteranceid": "20220602/14/018122d65d370a30116494c8_20220602_141442",
  "text": "アドバンスト・メディアは、人と機械との自然なコミュニケーションを実現し、豊かな未来を創造していくことを目指します。",
  "code": "",
  "message": ""
}

기타 문서​

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