Migrar o código da v3.0 para a v3.1 da API REST

  • Artigo

A API REST de Conversão de fala em texto é usada para a Transcrição em lote e a fala personalizada. As alterações da versão 3.0 para a 3.1 estão descritas nas seções abaixo.

Importante

A API REST de conversão de fala em texto v3.2 está disponível em versão prévia. A API REST de Conversão de fala em texto v3.1 está em disponibilidade geral. A API REST de conversão de fala em texto v3.0 será desativada em 1º de abril de 2026. Para obter mais informações, consulte os guias de migração Conversão de fala em texto da API REST v3.0 para v3.1 e v3.1 para v3.2.

Caminho Base

Você deve atualizar o caminho base no código de /speechtotext/v3.0 para /speechtotext/v3.1. Por exemplo, para obter modelos base na região eastus, use https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base em vez de https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/models/base.

Observe estas outras alterações:

  • A operação /models/{id}/copyto (inclui '/') na versão 3.0 é substituída pela operação /models/{id}:copyto (inclui ':') na versão 3.1.
  • A operação /webhooks/{id}/ping (inclui '/') na versão 3.0 é substituída pela operação /webhooks/{id}:ping (inclui ':') na versão 3.1.
  • A operação /webhooks/{id}/test (inclui '/') na versão 3.0 é substituída pela operação /webhooks/{id}:test (inclui ':') na versão 3.1.

Para obter mais informações, consulte IDs de operação mais adiante neste guia.

Transcrição de lote

Observação

Não use a API REST de Conversão de fala em texto v3.0 para recuperar uma transcrição criada por meio da API REST de Conversão de fala em texto v3.1. Você verá uma mensagem de erro como a seguinte: "A versão da API não pode ser usada para acessar essa transcrição. Use a API versão v3.1 ou superior."

Na operação Transcriptions_Create, as três propriedades a seguir são adicionadas:

  • A propriedade displayFormWordLevelTimestampsEnabled pode ser usada para habilitar o relatório de carimbos de data/hora no nível da palavra no formulário de exibição dos resultados da transcrição. Os resultados são retornados na propriedade displayWords do arquivo de transcrição.
  • A propriedade diarization pode ser usada para especificar dicas para o número mínimo e máximo de rótulos do locutor a serem gerados ao realizar a diarização opcional (separação do locutor). Com esse recurso, o serviço agora é capaz de gerar rótulos de locução para mais de dois locutores. Para usar essa propriedade, você também deve definir a propriedade diarizationEnabled como true. Com a API v3.1, aumentamos o número de alto-falantes que podem ser identificados por meio da diarização dos dois alto-falantes compatíveis com a API v3.0. É recomendável manter o número de alto-falantes abaixo de 30 para obter um melhor desempenho.
  • A propriedade languageIdentification pode ser usada para especificar configurações para identificação de idioma opcional na entrada antes da transcrição. Há suporte para até 10 localidades candidatas para identificação de linguagem. A transcrição retornada inclui uma nova propriedade locale para o idioma reconhecido ou a localidade que você forneceu.

A propriedade filter é adicionada às operações Transcriptions_List, Transcriptions_ListFiles e Projects_ListTranscriptions. A expressão filter pode ser usada para selecionar um subconjunto dos recursos disponíveis. É possível filtrar por displayName, description, createdDateTime, lastActionDateTime, status e locale. Por exemplo: filter=createdDateTime gt 2022-02-01T11:00:00Z

Se você usar webhook para receber as notificações sobre o status da transcrição, observe que os webhooks criados por meio da API V3.0 não poderão receber as notificações para solicitações de transcrição da V3.1. Será necessário criar um novo ponto de extremidade de webhook por meio da API V3.1 para receber as notificações das solicitações de transcrição V3.1.

Fala Personalizada

Conjunto de dados

As seguintes operações são adicionadas para carregar e gerenciar vários blocos de dados para um conjunto de dados:

  • Datasets_UploadBlock – Carregar um bloco de dados para o conjunto de dados. O tamanho máximo do bloco é 8MiB.
  • Datasets_GetBlocks – Obter a lista de blocos carregados para esse conjunto de dados.
  • Datasets_CommitBlocks – Lista de blocos de confirmação para concluir o upload do conjunto de dados.

Para dar suporte à adaptação de modelo com dados de texto estruturado em markdown, a operação Datasets_Create agora dá suporte ao tipo de dados LanguageMarkdown. Para saber mais, confira Carregar conjunto de dados.

Modelos

As operações Models_ListBaseModels e Models_GetBaseModel retornam informações sobre o tipo de adaptação com suporte por cada modelo base.

"features": {
    "supportsAdaptationsWith": [
        "Acoustic",
        "Language",
        "LanguageMarkdown",
        "Pronunciation"
    ]
}

A operação Models_Create tem uma nova propriedade customModelWeightPercent em que é possível especificar o peso usado quando o Modelo de Linguagem Personalizada (treinado com dados de texto estruturados ou sem formatação) é combinado com o Modelo de Linguagem Base. Os valores válidos são inteiros entre 1 e 100. O valor padrão atualmente é 30.

A propriedade filter é adicionada às seguintes operações:

A expressão filter pode ser usada para selecionar um subconjunto dos recursos disponíveis. É possível filtrar por displayName, description, createdDateTime, lastActionDateTime, status, locale e kind. Por exemplo: filter=locale eq 'en-US'

Foi adicionada a operação Models_ListFiles para obter os arquivos do modelo identificados pela ID especificada.

Foi adicionada a operação Models_GetFile para obter um arquivo específico (identificado com fileId) a partir de um modelo (identificado com ID). Isso permite recuperar um arquivo ModelReport que fornece informações sobre os dados processados durante o treinamento.

IDs de operação

Você deve atualizar o caminho base no código de /speechtotext/v3.0 para /speechtotext/v3.1. Por exemplo, para obter modelos base na região eastus, use https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base em vez de https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/models/base.

O nome de cada operationId na versão 3.1 é prefixado com o nome do objeto. Por exemplo, a operationId para "Criar Modelo" foi alterada de CreateModel na versão 3.0 para Models_Create na versão 3.1.

A operação /models/{id}/copyto (inclui '/') na versão 3.0 é substituída pela operação /models/{id}:copyto (inclui ':') na versão 3.1.

A operação /webhooks/{id}/ping (inclui '/') na versão 3.0 é substituída pela operação /webhooks/{id}:ping (inclui ':') na versão 3.1.

A operação /webhooks/{id}/test (inclui '/') na versão 3.0 é substituída pela operação /webhooks/{id}:test (inclui ':') na versão 3.1.

Próximas etapas