Métodos

Nesta seção detalharemos os métodos existentes na API ASR REST.

RECOGNIZE

Realiza o reconhecimento de fala de um áudio enviado para o serviço. O conteúdo do áudio deve ser enviado no corpo da mensagem HTTP e pode ser RAW (PCM Linear, amostras de 16 bits e taxa de amostragem de 8kHz ou 16kHz, de acordo com o Modelo Acústico (AM) instalado) ou codificado. Os formatos codificados suportados são: MP3, OPUS, VORBIS, PCM aLaw/uLaw, GSM, FLAC e WAV. O reconhecimento é realizado de forma síncrona e o resultado vem na resposta HTTP.

Requisição

POST /asr/rest/v3/recognize

HTTP Headers

Accept

(Opcional) Tipo de conteúdo do resultado do reconhecimento. Valores válidos:

  • application/xml

  • application/json

Valor padrão: application/json.

User-Agent

Identificação do dispositivo e/ou aplicação que está gerando o áudio. Útil para fins de log de aplicação.

Content-Length

Indica o número de bytes do conteúdo

Content-Type

Indica o formato do áudio enviado. Formatos válidos:

  • application/octet-stream – arquivo codificado num formato suportado

  • audio/wav – arquivo codificado num formato suportado

  • audio/raw – áudio PCM Linear sem cabeçalho

Infer-age-enabled

Para a utilização deste parâmetro e dos demais abaixo, é necessário a instalação dos classificadores. Veja mais em Instalação dos classificadores.

(Opcional) Habilita a classificação da idade do usuário. Valores válidos:

  • true

  • false (padrão)

Infer-gender-enabled

(Opcional) Habilita a classificação do gênero do usuário. Valores válidos:

  • true

  • false (padrão)

Infer-emotion-enabled

(Opcional) Habilita a classificação do tom emocional do usuário. Valores válidos:

  • true

  • false (padrão)

O reconhecimento de fala pode ser configurado para se adaptar às características específicas da aplicação. A configuração é feita através de parâmetros definidos como headers da requisição HTTP. A lista completa dos parâmetros é mostrada na seção Configuração. O exemplo a seguir, é suportado em ambiente On premise e mostra a configuração dos parâmetros endpointer.levelThreshold e decoder.confidenceThreshold:

POST /asr/rest/v3/recognize?lm=builtin:slm/general HTTP/1.1
Host: 127.0.0.1:8025
User-Agent: curl/7.47.0
Accept: */*
Content-Type: audio/wav
endpointer.levelThreshold: 10
decoder.confidenceThreshold: 30
Content-Length: ...

[binary content]

Nota

O exemplo a seguir, é suportado em ambiente SaaS do CPQD e também em On premise e mostra a configuração dos parâmetros endpointer-levelThreshold e decoder-confidenceThreshold. Note que ao invés de . (ponto) foi usado - (hífen).

POST /asr/rest/v3/recognize?lm=builtin:slm/general HTTP/1.1
Host: 127.0.0.1:8025
User-Agent: curl/7.47.0
Accept: */*
Content-Type: audio/wav
endpointer-levelThreshold: 10
decoder-confidenceThreshold: 30
Content-Length: ...

[binary content]

Parâmetros da requisição

lm

URI do modelo de língua. Caso não seja informada, será retornado um erro. A URI deve possuir um dos prefixos abaixo:

  • builtin - modelo interno (ex. builtin:slm/general).

  • file - modelo localizado no servidor (ex. file:///opt/grammar/menu, file:///opt/grammar/menu.gram).

  • http - modelo localizado na rede (ex. http://acme.com/grammar/menu.gram).

Resultado (HTTP status = 200)

Se a requisição HTTP retorna status code “200”, o corpo da resposta possui a estrutura abaixo. O formato da resposta pode ser definido através do header HTTP “Accept”, selecionando JSON (Accept: application/json) ou XML (Accept: application/xml). O formato padrão é JSON.

recognition_result

  • alternatives

  • result_status

alternatives: lista com os resultados prováveis do reconhecimento

  • index: índice da alternativa de resultado

  • text: texto reconhecimento

  • score: pontuação ou índice de confiança

  • interpretations: lista com os resultados da interpretação, conforme definido na gramática. Em caso de modelo de língua de fala livre, essa lista é vazia.

result_status: estado do reconhecimento. Pode ser um dos valores abaixo:

result_status

Descrição

RECOGNIZED

reconhecimento realizado com sucesso

NO_MATCH

reconhecimento realizado com sucesso mas sem correspondência na gramática

NO_INPUT_TIMEOUT

o reconhecimento não detectou o início de fala antes do vencimento do temporizador

EARLY_SPEECH

o áudio recebido não possui trecho de silêncio inicial (a fala começou antes do início do reconhecimento)

MAX_SPEECH

o servidor recebeu uma quantidade de áudio maior do que a capacidade de processamento

RECOGNITION_TIMEOUT

não foi possível gerar um resultado final antes do vencimento do temporizador

NO_SPEECH

não foi possível detectar fala no áudio enviado

CANCELED

o reconhecimento foi cancelado

FAILURE

falha não específica no servidor

Resultado (HTTP status <> 200)

Se a requisição HTTP retorna erro, com status code diferente de “200”, a resposta possui a estrutura abaixo.

ErrorResponse

  • code: Código de erro (Códigos de erro).

  • message: Mensagem complementar que indica o motivo da falha.

Exemplos

Chamada REST com resultado JSON, compatível com ambiente On premise:

curl -X POST \
  --header "Content-Type: audio/wav" \
  --header "decoder.maxSentences: 1" \
  --data-binary '@/opt/cpqd/asr/samples/audio/ptbr/87431_8k.wav' \
  http://127.0.0.1:8025/asr/rest/v3/recognize?lm=builtin:grammar/digits

Chamada REST com resultado JSON, compatível com ambiente SaaS e On premise:

curl -X POST \
  --header "Content-Type: audio/wav" \
  --header "decoder-maxSentences: 1" \
  --data-binary '@/opt/cpqd/asr/samples/audio/ptbr/87431_8k.wav' \
  http://127.0.0.1:8025/asr/rest/v3/recognize?lm=builtin:grammar/digits

Resultado:

[{
  "alternatives": [{
    "text": "oito sete quatro três um",
    "interpretations": ["87431"],
    "words": [{
      "text": "oito",
      "score": 100,
      "start_time": 0.3901262,
      "end_time": 0.95921874
    }, {
      "text": "sete",
      "score": 100,
      "start_time": 0.99,
      "end_time": 1.7068747
    }, {
      "text": "quatro",
      "score": 100,
      "start_time": 1.74,
      "end_time": 2.28
    }, {
      "text": "três",
      "score": 100,
      "start_time": 2.2800765,
      "end_time": 2.8498626
    }, {
      "text": "um",
      "score": 100,
      "start_time": 2.9167604,
      "end_time": 3.2101758
    }],
    "score": 100,
    "lm": "builtin:grammar/digits",
    "interpretation_scores": [100]
  }],
  "segment_index": 0,
  "last_segment": true,
  "final_result": true,
  "start_time": 0.24,
  "end_time": 3.52,
  "result_status": "RECOGNIZED"
}]

Chamada REST com resultado XML, compatível com ambiente On premise:

curl -X POST \
  --header "Content-Type: audio/wav" \
  --header "Accept: application/xml" \
  --header "decoder.maxSentences: 1" \
  --data-binary '@/opt/cpqd/asr/samples/audio/ptbr/87431_8k.wav' \
  http://127.0.0.1:8025/asr/rest/v3/recognize?lm=builtin:grammar/digits

Chamada REST com resultado XML, compatível com ambiente SaaS e On premise:

curl -X POST \
  --header "Content-Type: audio/wav" \
  --header "Accept: application/xml" \
  --header "decoder-maxSentences: 1" \
  --data-binary '@/opt/cpqd/asr/samples/audio/ptbr/87431_8k.wav' \
  http://127.0.0.1:8025/asr/rest/v3/recognize?lm=builtin:grammar/digits

Resultado:

<ArrayList>
  <item>
    <segment_index>0</segment_index>
    <last_segment>true</last_segment>
    <final_result>true</final_result>
    <start_time>0.24</start_time>
    <end_time>3.52</end_time>
    <result_status>RECOGNIZED</result_status>
    <alternatives>
      <alternative>
        <text>oito sete quatro três um</text>
        <score>100</score>
        <lm>builtin:grammar/digits</lm>
        <interpretations>
          <interpretation>87431</interpretation>
        </interpretations>
        <interpretation_scores>
          <interpretation_score>100</interpretation_score>
        </interpretation_scores>
        <words>
          <word>
            <text>oito</text>
            <score>100</score>
            <start_time>0.3901258</start_time>
            <end_time>0.95921737</end_time>
          </word>
          <word>
            <text>sete</text>
            <score>100</score>
            <start_time>0.99</start_time>
            <end_time>1.7068772</end_time>
          </word>
          <word>
            <text>quatro</text>
            <score>100</score>
            <start_time>1.74</start_time>
            <end_time>2.28</end_time>
          </word>
          <word>
            <text>três</text>
            <score>100</score>
            <start_time>2.2800772</start_time>
            <end_time>2.8498623</end_time>
          </word>
          <word>
            <text>um</text>
            <score>100</score>
            <start_time>2.9167345</start_time>
            <end_time>3.210177</end_time>
          </word>
        </words>
      </alternative>
    </alternatives>
  </item>
</ArrayList>

Resultado com erro (JSON):

{
  "code":"ERR_LM_NOT_FOUND",
  "message":"Language Model not found: builtin:grammar/booh"
}

Resultado com erro (XML):

<ErrorResponse>
  <code>ERR_LM_NOT_FOUND</code>
  <message>Language Model not found: builtin:grammar/booh</message>
</ErrorResponse>

INTERPRET

Realiza a interpretação semântica de um texto fornecido pelo cliente, usando a gramática indicada, de forma similar a RECOGNIZE. O texto deve ser enviado no corpo da mensagem HTTP. O reconhecimento é realizado de forma síncrona e o resultado vem na resposta HTTP.

Requisição

POST /asr/rest/v3/interpret

HTTP Headers

Accept

(Opcional) Tipo de conteúdo do resultado do reconhecimento. Valores válidos:

  • application/xml

  • application/json

Valor padrão: application/json.

User-Agent

Identificação do dispositivo e/ou aplicação que está gerando o áudio. Útil para fins de log de aplicação.

Content-Length

Indica o número de bytes do conteúdo

Content-Type

Indica o formato do áudio enviado. Formatos válidos:

  • text/plain – conteúdo de texto

Parâmetros da requisição

lm

URI do modelo de língua. Caso não seja informada, será retornado um erro. A URI deve possuir um dos prefixos abaixo:

  • builtin - modelo interno (ex. builtin:slm/general).

  • file - modelo localizado no servidor (ex. file:///opt/grammar/menu, file:///opt/grammar/menu.gram).

  • http - modelo localizado na rede (ex. http://acme.com/grammar/menu.gram).

Resultado

O resultado do reconhecimento é um objeto que possui a mesma estrutura do “recognize” mas apenas alguns campos fazem sentido e devem ser usados:

recognition_result

  • alternatives

  • result_status

alternatives: lista com os resultados prováveis do reconhecimento

  • text: texto reconhecimento

  • score: pontuação ou índice de confiança

  • interpretations: lista com os resultados da interpretação, conforme definido na gramática. Em caso de modelo de língua de fala livre, essa lista é vazia.

result_status: estado do reconhecimento. Pode ser um dos valores abaixo:

result_status

Descrição

RECOGNIZED

reconhecimento realizado com sucesso

NO_MATCH

reconhecimento realizado com sucesso mas sem correspondência na gramática

CANCELED

o reconhecimento foi cancelado

FAILURE

falha não específica no servidor

Exemplos

Chamada REST com resultado JSON:

curl -X POST \
  --header "Content-Type: text/plain" \
  --data 'oito sete quatro três um' \
  http://127.0.0.1:8025/asr/rest/v3/interpret?lm=builtin:grammar/digits

Resultado:

{
  "alternatives": [{
    "text": "oito sete quatro três um",
    "interpretations": ["87431"],
    "score": 100,
    "lm": "builtin:grammar/digits",
    "interpretation_scores": [100]
  }],
  "result_status": "RECOGNIZED"
}

Chamada REST com resultado XML:

curl -X POST \
  --header "Content-Type: application/xml"
  --data 'oito sete quatro três um' \
  http://127.0.0.1:8025/asr/rest/v3/interpret?lm=builtin:grammar/digits

Resultado:

<recognition_result>
  <result_status>RECOGNIZED</result_status>
  <alternatives>
    <alternative>
      <text>oito sete quatro três um</text>
      <score>100</score>
      <lm>builtin:grammar/digits</lm>
      <interpretations>
        <interpretation>87431</interpretation>
      </interpretations>
      <interpretation_scores>
        <interpretation_score>100</interpretation_score>
      </interpretation_scores>
    </alternative>
  </alternatives>
</recognition_result>