Fazendo uma solicitação de reconhecimento de voz
Para solicitar reconhecimento de voz com o serviço IBM Watson® Speech to Text, é necessário fornecer apenas o áudio que deve ser transcrito. O serviço oferece os mesmos recursos de transcrição básica com cada uma de suas interfaces: a interface do WebSocket, a interface de HTTP síncrona e a interface de HTTP assíncrona.
Os exemplos a seguir mostram as solicitações básicas de transcrição, sem parâmetros opcionais, para cada uma das interfaces do serviço:
- Os exemplos enviam um breve arquivo FLAC chamado audio-file.flac.
- Os exemplos usam o modelo de idioma padrão,
en-US_BroadbandModel
. Para obter mais informações, consulte Uso do modelo padrão.
Entendendo resultados de reconhecimento de voz descreve a resposta do serviço para esses exemplos.
Requisitos de uso
Considere os requisitos a seguir básicos de uso quando fizer um pedido de reconhecimento de voz:
- Os nomes dos métodos fazem distinção entre maiúsculas e minúsculas.
- Cabeçalhos da solicitação de HTTP não fazem distinção entre maiúsculas e minúsculas.
- Os parâmetros de consulta HTTP e WebSocket fazem distinção entre maiúsculas e minúsculas.
- Os nomes de campo JSON fazem distinção entre maiúsculas e minúsculas.
- Todo o conteúdo de resposta JSON está no conjunto de caracteres UTF-8.
- As chaves (
{ }
) são usadas na documentação para indicar valores de variáveis. Omita as chaves ao fornecer valores de variáveis.
Considere também os requisitos específicos do serviço a seguir:
- É necessário especificar apenas o áudio de entrada. Todos os outros parâmetros são opcionais.
- Se necessário, certifique-se de especificar o parâmetro
model
para indicar um modelo que seja apropriado para seu idioma e áudio. - Se você especificar um parâmetro de consulta ou um campo JSON inválido como parte da entrada, a resposta incluirá um campo
warnings
que descreva o argumento inválido. A solicitação é bem-sucedida, apesar de qualquer aviso.
Enviando áudio com uma solicitação
O áudio que você transmite para o serviço deve estar em um dos formatos suportados do serviço. Para a maioria dos áudios, o serviço pode detectar automaticamente o formato. Para alguns áudios, deve-se especificar o formato com o Content-Type
ou parâmetro equivalente. Para obter mais informações, consulte Formatos de áudio. (Para clareza, os exemplos a seguir especificam o formato de áudio
com todas as solicitações).
Com as interfaces do WebSocket e HTTP síncrona, é possível passar um máximo de 100 MB de dados de áudio com uma única solicitação. Com a interface de HTTP assíncrona, é possível passar um máximo de 1 GB de dados de áudio. Deve-se enviar pelo menos 100 bytes de áudio com qualquer solicitação.
Se você estiver reconhecendo grandes quantidades de áudio, será possível dividir manualmente o áudio em chunks menores. Mas, geralmente, é mais eficiente e conveniente converter o áudio em um formato compactado com perdas. A compactação pode maximizar a quantia de dados que você pode enviar com uma única solicitação. Especialmente se o áudio estiver no formato WAV ou FLAC, convertê-lo para um formato com perdas pode fazer uma diferença significativa.
- Para obter mais informações sobre formatos de áudio que usam compactação, consulte Formatos de áudio.
- Para obter mais informações sobre os efeitos da compactação e sobre como converter seu áudio em um formato que a use, consulte Limites de dados e compactação e Conversão de áudio.
- Para obter mais informações sobre como transcrever o áudio de um arquivo multimídia que contém áudio e vídeo, consulteTranscrevendo a fala de arquivos de vídeo.
Usando a interface do WebSocket
A interface do WebSocket oferece uma implementação eficiente que fornece baixa latência e rendimento alto por meio de uma conexão full duplex. Todas as solicitações e respostas são enviadas por meio da mesma conexão do WebSocket.
Para usar a interface do WebSocket, primeiro use o método /v1/recognize
para estabelecer uma conexão com o serviço. Especifique parâmetros como o modelo de idioma e qualquer modelo customizado que deve ser usado para solicitações
enviadas por meio da conexão. Em seguida, registre os listeners de eventos para manipular respostas do serviço. Para fazer uma solicitação, envie uma mensagem de texto JSON que inclui o formato de áudio e qualquer parâmetro adicional. Passe
o áudio como uma mensagem binária (BLOB) e, em seguida, envia uma mensagem de texto para sinalizar o fim do áudio.
O exemplo a seguir fornece o código JavaScript que estabelece uma conexão e envia as mensagens de texto e binárias para uma solicitação de reconhecimento. O exemplo básico não inclui o código para definir todos os manipuladores de eventos necessários para a conexão.
var access_token = {access_token};
var wsURI = '{ws_url}/v1/recognize'
+ '?access_token=' + access_token;
var websocket = new WebSocket(wsURI);
websocket.onopen = function(evt) { onOpen(evt) };
function onOpen(evt) {
var message = {
action: 'start',
content-type: 'audio/flac'
};
websocket.send(JSON.stringify(message));
websocket.send(blob);
websocket.send(JSON.stringify({action: 'stop'}));
}
Usando a interface de HTTP síncrona
A interface de HTTP síncrona fornece a maneira mais simples de fazer uma solicitação de reconhecimento. Use o método POST /v1/recognize
para fazer uma solicitação para
o serviço. Passe o áudio e todos os parâmetros com a solicitação única. O curl
de exemplo a seguir mostra uma solicitação de reconhecimento básico de HTTP:
IBM Cloud
curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: audio/flac" \
--data-binary @audio-file.flac \
"{url}/v1/recognize"
IBM Cloud Pak for Data IBM Software Hub
curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: audio/flac" \
--data-binary @audio-file.flac \
"{url}/v1/recognize"
Usando a interface de HTTP assíncrona
A interface de HTTP assíncrona fornece uma interface sem bloqueio para transcrição de áudio. É possível usar a interface registrando ou não primeiro uma URL de retorno de chamada
com o serviço. Com uma URL de retorno de chamada, o serviço envia notificações de retorno de chamada com status de tarefa e resultados de reconhecimento. A interface usa assinaturas HMAC-SHA1 com base em um segredo especificado pelo usuário
para fornecer autenticação e integridade de dados para suas notificações. Sem uma URL de retorno de chamada, deve-se pesquisar o serviço para obter o status e os resultados da tarefa. Com qualquer abordagem, use o método POST /v1/recognitions
para fazer uma solicitação de reconhecimento.
O curl
de exemplo a seguir mostra uma solicitação de reconhecimento de HTTP assíncrona simples. A solicitação não inclui uma URL de retorno de chamada, portanto, deve-se pesquisar o serviço para obter o status da tarefa e a transcrição
resultante.
IBM Cloud
curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: audio/flac" \
--data-binary @audio-file.flac \
"{url}/v1/recognitions"
IBM Cloud Pak for Data IBM Software Hub
curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: audio/flac" \
--data-binary @audio-file.flac \
"{url}/v1/recognitions"