메인 콘텐츠로 건너뛰기

음성 인식 결과 형식

AmiVoice API에서는 전송한 음성을 텍스트로 변환한 것뿐만 아니라 다양한 정보를 얻을 수 있습니다. 정보는 구조화되어 JSON 형식으로 제공됩니다. 이 섹션에서는 AmiVoice API에서 얻을 수 있는 결과에 대해 설명합니다.

결과의 구조​

AmiVoice API에서 얻을 수 있는 음성 인식 결과는 크게 3가지 부분으로 나뉩니다. 다음은 클라이언트 라이브러리의 샘플 프로그램에 포함된 test.wav라는 음성 파일에 대한 결과입니다.

그림. AmiVoice API 결과 개요

각 요소를 순서대로 설명하겠습니다.

전체 결과​

API에 전송한 음성 전체의 결과입니다.

test.wav의 결과에서 전체 결과를 예로 발췌합니다.

{
  /* ... 생략 ... */
  "utteranceid": "20220602/14/018122d65d370a30116494c8_20220602_141442",
  "text": "アドバンスト・メディアは、人と機械との自然なコミュニケーションを実現し、豊かな未来を創造していくことを目指します。",
  "code": "",
  "message": ""
  /* ... 생략 ... */
}

전체 결과의 각 요소에는 다음 정보가 포함됩니다.

필드명설명비고
utteranceid인식 결과 정보 ID인식 결과 정보 ID는 WebSocket과 HTTP 인터페이스에서 다릅니다. WebSocket에서는 발화 구간별 인식 결과 정보에 대한 ID입니다. 반면 HTTP의 경우 1세션에서 업로드된 여러 발화 구간을 포함할 수 있는 음성 데이터 전체의 인식 결과 정보에 대한 ID입니다.
text전체 인식 결과 텍스트발화 구간의 인식 결과를 모두 결합한 전체 인식 결과 텍스트입니다.
code결과 코드결과를 나타내는 1문자 코드입니다. 응답 코드 및 메시지를 참조하십시오.
message오류 메시지오류 내용을 나타내는 문자열입니다. 응답 코드 및 메시지를 참조하십시오.

code와 message는 요청이 성공했을 때는 빈 문자열이 됩니다. 실패했을 때는 이유가 설정되므로 응답 코드 및 메시지를 참조하십시오.

인식 성공 시:

body.code == ""　및　 body.message == ""　및　 body.text != ""

인식 실패 시:

body.code != ""　및　 body.message != ""　및　 body.text == ""

가 됩니다.

발화 구간의 결과​

발화 구간이란 음성 데이터 중에서 사람이 말하는 부분을 가리킵니다. AmiVoice API에서는 발화 감지 프로세스를 통해 발화 구간을 추정합니다. 이 발화 구간별 음성 인식 결과에 대해 설명합니다.

노트

동기 HTTP 인터페이스에서는 발화 구간의 결과를 얻을 수 없습니다.

test.wav의 결과에서 단어 단위의 결과를 예로 발췌합니다.

{
  /* ... 생략 ... */
  "results": [
    {
      "tokens": [/*...단어 단위의 결과..*/],
      "confidence": 0.998,
      "starttime": 250,
      "endtime": 8794,
      "tags": [],
      "rulename": "",
      "text": "アドバンスト・メディアは、人と機械との自然なコミュニケーションを実現し、豊かな未来を創造していくことを目指します。"
    }
  ]
  /* ... 생략 ... */
}

results는 배열 형식이지만 항상 1개의 요소만 가집니다. results[0]의 요소는 발화 구간의 결과를 나타냅니다. 발화 구간 결과의 각 요소에는 다음 정보가 포함됩니다.

필드명설명비고
results[0].tokens단어 단위의 결과단어 단위의 결과가 배열 형식으로 제공됩니다. 자세한 내용은 다음 장에서 설명합니다.
results[0].confidence신뢰도전체 신뢰도입니다. 값은 0 ~ 1을 가지며, 신뢰도가 낮으면 오류일 가능성이 높고 1에 가까울수록 결과가 더 확실함을 나타냅니다.
results[0].starttime발화 구간의 시작 시간음성 인식 처리 대상으로 감지된 발화 구간의 시작 시간을 나타냅니다. 결과에 포함된 시간 정보에 대하여를 참조하십시오.
results[0].endtime발화 구간의 종료 시간음성 인식 처리 대상으로 감지된 발화 구간의 종료 시간 또는 실제로 음성 인식 처리의 대상이 된 구간의 종료 시간을 나타냅니다. 결과에 포함된 시간 정보에 대하여를 참조하십시오.
results[0].tags태그항상 비어 있습니다. 현재 사용하지 않으므로 무시하십시오.
results[0].rulename규칙 이름항상 비어 있습니다. 현재 사용하지 않으므로 무시하십시오.
results[0].text음성 인식 결과 텍스트발화 구간에 포함된 음성에 대한 인식 결과 텍스트입니다.
노트
WebSocket 인터페이스의 경우 E 이벤트 패킷을 통해 클라이언트 측에 통지되는 값과의 차이점에 대하여​

WebSocket 인터페이스의 경우 E 이벤트 패킷을 통해 클라이언트 측에 통지되는 값은 발화 구간의 종료 시간입니다. 반면 결과에 포함된 results[0].endtime 값은 발화 구간 중 실제로 음성 인식 처리의 대상이 된 구간의 종료 시간을 나타냅니다. 따라서 E 이벤트의 시간 정보와 results[0].endtime 값은 약간 다를 수 있으며, results[0].endtime은 E의 시간과 같거나 약간 앞선 시간일 수 있습니다.

results[0].endtime≦E이벤트의시간정보results[0].endtime \leqq E이벤트의 시간 정보

사용자는 이 차이를 의식할 필요는 없지만, results[0].starttime과 results[0].endtime에서 계산한 시간은 청구 대상 시간과는 다르므로 주의하십시오.

단어 단위의 결과​

단어 단위의 결과는 results[0].tokens에 배열 형식으로 제공됩니다. 단어는 음성 인식 엔진이 다루는 단위를 의미하며, 언어의 문법적 단어와는 다릅니다.

test.wav의 결과에서 단어 단위의 결과를 예로 발췌합니다.

{
  /* ... 생략 ... */
  "results": [
    "tokens": [
      {
        "written": "アドバンスト・メディア",
        "confidence": 1,
        "starttime": 522,
        "endtime": 1578,
        "spoken": "あどばんすとめでぃあ",
        "label": "speaker0"
      },
      {
        "written": "は",
        "confidence": 1,
        "starttime": 1578,
        "endtime": 1866,
        "spoken": "は"
      },
      /* ... 생략 ... */
  ]
  /* ... 생략 ... */
}

단어 단위 결과의 각 요소에는 다음 정보가 포함됩니다.

필드명설명비고
results[0].tokens[].written단어 단위의 표기인식된 단어의 표기입니다.
results[0].tokens[].spoken단어 단위의 읽기인식된 단어의 단어 읽기입니다.

- 일본어 엔진의 인식 결과의 spoken은 히라가나입니다.
- 영어 엔진의 인식 결과의 spoken은 읽기가 아닙니다(무시하십시오).
- 중국어 엔진의 인식 결과의 spoken은 병음(pinyin)입니다.
results[0].tokens[].starttime단어 단위 발화의 시작 시간인식된 단어의 발화 시작을 추정한 시간입니다. 결과에 포함된 시간 정보에 대하여를 참조하십시오.
results[0].tokens[].endtime단어 단위 발화의 종료 시간인식된 단어의 발화 종료를 추정한 시간입니다. 결과에 포함된 시간 정보에 대하여를 참조하십시오.
results[0].tokens[].label단어 단위의 추정 화자 라벨화자 다이어라이제이션 기능을 활성화했을 때만 얻을 수 있는 정보입니다. 화자를 구별하는 라벨, speaker0, speaker1, ... 입니다. 자세한 내용은 화자 다이어라이제이션을 참조하십시오.
results[0].tokens[].confidence단어 단위의 신뢰도인식된 단어의 신뢰도입니다. 값은 0 ~ 1을 가지며, 신뢰도가 낮으면 오류일 가능성이 높고 1에 가까울수록 결과가 더 확실함을 나타냅니다.
노트

단어 단위 결과에 반드시 존재하는 것은 written뿐입니다. 그 외의 정보는 요청 내용이나 지정한 엔진에 따라 다릅니다. 예를 들어 label은 화자 다이어라이제이션을 활성화하지 않으면 존재하지 않습니다. 또한 일본어 이외의 음성 인식 엔진에서 구두점 결과에 대해서는 starttime, endtime, confidence가 포함되지 않으므로 주의하십시오.

중국어 구두점 결과의 예:

{
  "written": "。",
  "spoken": "_"
}

인터페이스별 결과의 세부 사항​

결과의 구조에서 설명한 음성 인식 결과가 인터페이스별로 어떻게 제공되는지, 인터페이스 고유의 결과나 차이점에 대해 설명합니다.

동기 HTTP 인터페이스​

발화 구간을 하나로 통합한 결과가 제공됩니다. 여러 개의 발화 구간이 감지된 경우에도 통합하여 하나의 결과가 됩니다.

{
    "results": [
      {
        "starttime": 첫 번째 발화 구간의 시작 시각,
        "endtime": 마지막 발화 구간의 종료 시각,
        "tokens": [{단어 단위 결과1},...,{단어 단위 결과N}]
        "confidence": 신뢰도,
        "tags": [],
        "rulename": "",
        "text": "...",
      }
    ],
    "text": "...",
    "code": 결과 코드,
    "message": 오류 이유,
    "utteranceid": "..."
}
  • 첫 번째 발화 구간의 시작 시각이 starttime에, 마지막 발화 구간의 종료 시각이 endtime에, 전송한 음성에 대한 모든 단어 단위의 결과가 tokens에 배열 형식으로 얻어집니다.
  • 동기 HTTP 인터페이스에서는 utteranceid가 하나만 얻어집니다.

예:

{
  "results": [
    {
      "tokens": [
        {
          "written": "アドバンスト・メディア",
          "confidence": 1,
          "starttime": 522,
          "endtime": 1578,
          "spoken": "あどばんすとめでぃあ"
        },
        {
          "written": "は",
          "confidence": 1,
          "starttime": 1578,
          "endtime": 1866,
          "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": ""
}

비동기 HTTP 인터페이스​

발화 구간별로 결과가 얻어집니다. 여러 개의 발화 구간이 검출된 경우에는 발화 구간의 수만큼 results가 얻어집니다.

{
  "segments": [
    {
      "results": [
        {
          "starttime": 발화 구간의 시작 시각,
          "endtime": 발화 구간의 종료 시각,
          "tokens": [{단어 단위 결과1},...]
          "confidence": 신뢰도,
          "tags": [],
          "rulename": "",
          "text": "...",
        }
      ],
      "text": "..."
    },
    /* ... */
    {
      "results": [
        {
          "starttime": 발화 구간의 시작 시각,
          "endtime": 발화 구간의 종료 시각,
          "tokens": [...,{단어 단위 결과N}]
          "confidence": 신뢰도,
          "tags": [],
          "rulename": "",
          "text": "...",
        }
      ],
      "text": "..."
    }
  ]},
  "text": "...",
  "code": "...",
  "message": "...",
  "utteranceid": "...",
  /* ... 이하는 비동기 HTTP 인터페이스에 고유한 항목) ... */
  "audio_md5": "...",
  "audio_size": 0,
  "service_id": "...",
  "session_id": "...",
  "status": "..."
}
  • 동기식 HTTP 음성 인식과 달리, 발화 구간별 결과(results)가 segments에 배열 형식으로 얻어집니다.
노트

동기식 HTTP 인터페이스와 마찬가지로 최상위 레벨에 results를 얻으려면, d 파라미터에 compatibleWithSync=True를 지정합니다.

작업 상태 등 비동기식 HTTP 인터페이스에만 있는 항목은 다음 표와 같습니다.

필드명설명비고
session_id세션 ID비동기식 HTTP 인터페이스에 전송한 작업의 ID.
status비동기 처리 상태비동기식 HTTP 인터페이스에 전송한 작업의 상태.
audio_size요청한 음성의 크기비동기식 HTTP 인터페이스가 수락한 음성의 크기.
audio_md요청한 음성의 MD5 체크섬비동기식 HTTP 인터페이스가 수락한 음성의 MD5 체크섬.
content_id컨텐츠 ID이용자가 나중에 데이터를 연결하기 위해 사용할 수 있는 ID.
service_id서비스 ID이용자별로 발행된 서비스 ID.

WebSocket 인터페이스​

발화 구간의 결과​

발화 구간별로 결과가 얻어집니다. 여러 개의 발화 구간이 있는 경우 발화 구간의 수만큼 결과 이벤트(A)가 얻어집니다.

{
    "results": [
      {
        "starttime": 발화 구간의 시작 시각,
        "endtime": 발화 구간의 종료 시각,
        "tokens": [{단어 단위의 결과1},...,{단어 단위의 결과N}]
        "confidence": 신뢰도,
        "tags": [],
        "rulename": "",
        "text": "받아쓰기 결과"
      }
    ],
    "text": "...",
    "code": 결과 코드,
    "message": 오류 이유
    "utteranceid": "..."
}
  • utteranceid는 발화 구간마다 다른 ID가 부여됩니다.

중간 결과​

음성 인식이 진행 중일 때 얻어지는 중간 결과입니다. 중간 결과는 가설이며, 발화 구간의 결과에서는 내용이 변경되어 있을 수 있습니다.

{
    "results": [
      {
        "tokens": [{단어 단위의 결과1},...,{단어 단위의 결과N}]
        "text": "받아쓰기 결과"
      }
    ],
    "text": "..."
}

결과 텍스트에 대하여​

문자 코드​

결과는 UTF-8로 인코딩되어 있습니다.

Unicode 이스케이프​

동기식 HTTP 인터페이스, WebSocket 인터페이스의 결과에 포함된 일본어 등의 멀티바이트 코드는 Unicode 이스케이프되어 있습니다.

Unicode 이스케이프되지 않은 결과:

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

Unicode 이스케이프된 결과:

"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"

불필요한 단어의 자동 삭제​

「あのー」나 「えーっと」 등의 불필요한 단어는 text에서 자동으로 제거됩니다. 자세한 내용은 불필요한 단어의 자동 삭제를 참조하십시오.

결과에 포함된 시각 정보에 대하여​

results[0].starttime, results[0].endtime, results[0].tokens[].starttime, results[0].tokens[].endtime 등 시각을 나타내는 값은 음성 데이터의 시작을 0으로 한 밀리초 단위입니다. WebSocket 인터페이스의 경우 s부터 e까지가 하나의 세션이 되며, 세션 내에서의 상대적인 시간을 나타냅니다. 새로운 세션이 시작될 때마다 기준 시간이 리셋됩니다.

청구 대상 음성 시간에 대하여​

음성 인식 API의 청구는 발화 구간을 기준으로 합니다. WebSocket 인터페이스의 S와 E 이벤트를 통해 정확한 발화 구간 정보를 얻을 수 있습니다. WebSocket 인터페이스의 경우 E 이벤트 패킷을 통해 클라이언트 측에 통지되는 값과의 차이에 대하여도 참조하십시오.