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:
|
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:
|
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:
|
Infer-gender-enabled |
(Opcional) Habilita a classificação do gênero do usuário. Valores válidos:
|
Infer-emotion-enabled |
(Opcional) Habilita a classificação do tom emocional do usuário. Valores válidos:
|
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 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]
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:
|
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:
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:
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:
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:
|
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:
|
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>