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"