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

Artigo
04/15/2024

A API REST Speech to text é usada para transcrição em lote e fala personalizada. As alterações da versão 3.0 para 3.1 são descritas nas seções abaixo.

Importante

A API REST de fala para texto v3.2 está disponível na visualização. A API REST de fala para texto v3.1 está geralmente disponível. A API REST de fala para texto v3.0 será desativada em 1º de abril de 2026. Para obter mais informações, consulte os guias de migração Speech to text REST API v3.0 to v3.1 e v3.1 to v3.2 .

Caminho base

Você deve atualizar o caminho base em seu código de /speechtotext/v3.0 para /speechtotext/v3.1. Por exemplo, para obter modelos base na eastus região, 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 /models/{id}/copyto operação (inclui '/') na versão 3.0 é substituída /models/{id}:copyto pela operação (inclui ':') na versão 3.1.
A /webhooks/{id}/ping operação (inclui '/') na versão 3.0 é substituída /webhooks/{id}:ping pela operação (inclui ':') na versão 3.1.
A /webhooks/{id}/test operação (inclui '/') na versão 3.0 é substituída /webhooks/{id}:test pela operação (inclui ':') na versão 3.1.

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

Transcrição em lotes

Nota

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

Na operação Transcriptions_Create são adicionadas as seguintes três propriedades:

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

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

Se você usar o webhook para receber notificações sobre o status da transcrição, observe que os webhooks criados por meio da API V3.0 não podem receber notificações para solicitações de transcrição V3.1. Você precisa criar um novo ponto de extremidade webhook via API V3.1 para receber notificações para solicitações de transcrição V3.1.

Fala personalizada

Conjuntos 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 - Carregue um bloco de dados para o conjunto de dados. O tamanho máximo do bloco é 8MiB.
Datasets_GetBlocks - Obtenha a lista de blocos carregados para este conjunto de dados.
Datasets_CommitBlocks - Confirme a lista de bloqueio para concluir o upload do conjunto de dados.

Para suportar a adaptação do modelo com texto estruturado em dados de markdown, a operação Datasets_Create agora suporta o tipo de dados LanguageMarkdown. Para obter mais informações, consulte carregar conjuntos de dados.

Modelos

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

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

A operação Models_Create tem uma nova customModelWeightPercent propriedade onde você pode especificar o peso usado quando o Modelo de Linguagem Personalizada (treinado a partir de dados de texto simples ou estruturado) é combinado com o Modelo de Idioma Base. Os valores válidos são inteiros entre 1 e 100. O valor padrão é atualmente 30.

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

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

Adicionada a operação Models_ListFiles para obter os arquivos do modelo identificado pelo ID fornecido.

Adicionada a operação Models_GetFile para obter um arquivo específico (identificado com fileId) 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

O nome de cada operationId um na versão 3.1 é prefixado com o nome do objeto. Por exemplo, o operationId para "Criar modelo" mudou de CreateModel na versão 3.0 para Models_Create na versão 3.1.

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

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

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