Criar uma transcrição em lote

Com transcrições em lote, você envia dados de áudio em lote. O serviço transcreve os dados de áudio e armazena os resultados em um recipiente de armazenamento. Em seguida, você pode recuperar os resultados do contêiner de armazenamento.

A conclusão da transcrição em lote pode levar de vários minutos a horas, dependendo do tamanho dos dados de áudio e do número de arquivos enviados. Mesmo o mesmo tamanho de dados de áudio pode levar diferentes quantidades de tempo para transcrever, dependendo da carga de serviço e outros fatores. O serviço não fornece uma maneira de estimar o tempo necessário para transcrever um lote de dados de áudio.

Gorjeta

Se você precisar de velocidade rápida consistente para arquivos de áudio com menos de 2 horas de comprimento e menos de 300 MB de tamanho, considere usar a API de transcrição rápida .

Pré-requisitos

Precisas de um recurso Microsoft Foundry para Speech.

Criar um trabalho de transcrição

Para criar uma tarefa de transcrição em lote, utilize a operação Transcrições - Enviar da API REST de fala para texto. Construa o corpo da solicitação de acordo com os seguintes passos:

  • Você deve definir a propriedade contentContainerUrl ou a propriedade contentUrls. Para mais informações sobre o armazenamento de blobs do Azure para transcrição em lote, veja Localizar ficheiros de áudio para transcrição em lote.
  • Defina a propriedade requerida locale. Esse valor deve corresponder à localidade esperada dos dados de áudio a serem transcritos. Não é possível alterar a localidade mais tarde.
  • Defina a propriedade requerida displayName. Escolha um nome de transcrição ao qual possa fazer referência mais tarde. O nome da transcrição não precisa ser exclusivo e pode ser alterado posteriormente.
  • Defina a propriedade requerida timeToLiveHours. Esta propriedade especifica por quanto tempo a transcrição deve ser mantida no sistema após sua conclusão. A duração suportada mais curta é de 6 horas, a duração suportada mais longa é de 31 dias. O valor recomendado é de 48 horas (dois dias) quando os dados são consumidos diretamente.
  • Opcionalmente, para usar um modelo diferente do modelo base, defina a model propriedade como a ID do modelo. Para obter mais informações, consulte Usar um modelo personalizado e Usar um modelo Whisper.
  • Opcionalmente, defina a wordLevelTimestampsEnabled propriedade como true para habilitar carimbos de data/hora no nível da palavra nos resultados da transcrição. O valor predefinido é false. Para modelos Whisper, defina a propriedade displayFormWordLevelTimestampsEnabled em vez disso. Whisper é um modelo somente de exibição, portanto, o campo lexical não é preenchido na transcrição.
  • Opcionalmente, defina a languageIdentification propriedade. A identificação de idioma é usada para identificar idiomas falados em áudio quando comparados com uma lista de idiomas suportados. Caso definas a propriedade languageIdentification, deves também definir languageIdentification.candidateLocales com locais candidatos.

Para obter mais informações, consulte Opções de configuração de solicitação.

Faça uma solicitação HTTP POST que use o URI, conforme mostrado no exemplo Transcrições - Enviar a seguir.

  • Substitui YourSpeechResoureKey pela tua chave de recursos do Microsoft Foundry.
  • Substitua YourServiceRegion pela região de recursos do Microsoft Foundry.
  • Configure as propriedades do corpo da solicitação conforme descrito anteriormente.
curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSpeechResoureKey" -H "Content-Type: application/json" -d '{
  "contentUrls": [
    "https://crbn.us/hello.wav",
    "https://crbn.us/whatstheweatherlike.wav"
  ],
  "locale": "en-US",
  "displayName": "My Transcription",
  "model": null,
  "properties": {
    "wordLevelTimestampsEnabled": true,
    "languageIdentification": {
      "candidateLocales": [
        "en-US", "de-DE", "es-ES"
      ],
      "mode": "Continuous"
    },
    "timeToLiveHours": 48
  }
}'  "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/transcriptions:submit?api-version=2024-11-15"

Deverá receber um corpo de resposta no seguinte formato:

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/transcriptions/788a1f24-f980-4809-8978-e5cf41f77b35?api-version=2024-11-15",
  "displayName": "My Transcription 2",
  "locale": "en-US",
  "createdDateTime": "2025-05-24T03:20:39Z",
  "lastActionDateTime": "2025-05-24T03:20:39Z",
  "links": {
    "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/transcriptions/788a1f24-f980-4809-8978-e5cf41f77b35/files?api-version=2024-11-15"
  },
  "properties": {
    "wordLevelTimestampsEnabled": true,
    "displayFormWordLevelTimestampsEnabled": false,
    "channels": [
      0,
      1
    ],
    "punctuationMode": "DictatedAndAutomatic",
    "profanityFilterMode": "Masked",
    "timeToLiveHours": 48,
    "languageIdentification": {
      "candidateLocales": [
        "en-US",
        "de-DE",
        "es-ES"
      ],
      "mode": "Continuous"
    }
  },
  "status": "NotStarted"
}

A propriedade de nível self superior no corpo da resposta é o URI da transcrição. Use esse URI para obter detalhes, como o URI das transcrições e dos arquivos de relatório de transcrição. Você também usa esse URI para atualizar ou excluir uma transcrição.

Você pode consultar o status de suas transcrições com a operação Transcrições - Obter .

Transcrições de chamadas - Exclua regularmente do serviço, depois de recuperar os resultados. Como alternativa, defina a timeToLive propriedade para garantir a eventual exclusão dos resultados.

Gorjeta

Também podes experimentar a API de Transcrição em Batch usando Python, C# ou Node.js em GitHub.

Para criar uma transcrição, use o spx batch transcription create comando. Construa os parâmetros de solicitação de acordo com as seguintes instruções:

  • Defina o parâmetro necessário content . Você pode especificar uma lista delimitada por vírgulas de arquivos individuais ou a URL para um contêiner inteiro. Para mais informações sobre o armazenamento de blobs do Azure para transcrição em lote, veja Localizar ficheiros de áudio para transcrição em lote.
  • Defina a propriedade requerida language. Esse valor deve corresponder à localidade esperada dos dados de áudio a serem transcritos. Não é possível alterar a localidade mais tarde. O parâmetro Speech CLI language corresponde à propriedade locale na solicitação e resposta JSON.
  • Defina a propriedade requerida name. Escolha um nome de transcrição ao qual possa fazer referência mais tarde. O nome da transcrição não precisa ser exclusivo e pode ser alterado posteriormente. O parâmetro Speech CLI name corresponde à propriedade displayName na solicitação e resposta JSON.
  • Defina o parâmetro necessário api-version como v3.2. A CLI de fala ainda não suporta a versão 2024-11-15 ou posterior, então você deve usar v3.2 por enquanto.

Aqui está um exemplo de comando da CLI de fala que cria um trabalho de transcrição:

spx batch transcription create --api-version v3.2 --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav,https://crbn.us/whatstheweatherlike.wav

Deverá receber um corpo de resposta no seguinte formato:

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/bbbbcccc-1111-dddd-2222-eeee3333ffff",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/ccccdddd-2222-eeee-3333-ffff4444aaaa"
  },
  "links": {
    "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/7f4232d5-9873-47a7-a6f7-4a3f00d00dc0/files"
  },
  "properties": {
    "diarizationEnabled": false,
    "wordLevelTimestampsEnabled": false,
    "channels": [
      0,
      1
    ],
    "punctuationMode": "DictatedAndAutomatic",
    "profanityFilterMode": "Masked"
  },
  "lastActionDateTime": "2025-05-24T03:20:39Z",
  "status": "NotStarted",
  "createdDateTime": "2025-05-24T03:20:39Z",
  "locale": "en-US",
  "displayName": "My Transcription",
  "description": ""
}

A propriedade de nível self superior no corpo da resposta é o URI da transcrição. Use esse URI para obter detalhes, como o URI das transcrições e dos arquivos de relatório de transcrição. Você também usa esse URI para atualizar ou excluir uma transcrição.

Para obter ajuda da CLI de fala com transcrições, execute o seguinte comando:

spx help batch transcription

Solicitar opções de configuração

Aqui estão algumas opções de propriedade para configurar uma transcrição quando você chama a operação Transcrições - Enviar . Você pode encontrar mais exemplos na mesma página, como a criação de uma transcrição com identificação de idioma.

O órgão do pedido tem dois níveis distintos. Colocar incorretamente uma propriedade faz com que o serviço a ignore silenciosamente ou retorne um erro de validação.

  • Nível raiz: Metadados que descrevem o próprio trabalho de transcrição (displayName, locale, model, contentUrls, contentContainerUrl).
  • Inside properties: Opções que controlam o comportamento de transcrição. Envolva estes num objeto "properties": { }.

Importante

destinationContainerUrl pertence dentro do properties objeto, não ao nível raiz do corpo do pedido. Colocá-lo na raiz faz com que o serviço o ignore, e os resultados da transcrição são silenciosamente escritos no contentor gerido pela Microsoft.

O exemplo seguinte mostra a estrutura correta:

{
  "contentUrls": ["https://..."],
  "locale": "en-US",
  "displayName": "My Transcription",
  "model": null,
  "properties": {
    "destinationContainerUrl": "https://<storage>.blob.core.windows.net/<container>?<SAS>",
    "wordLevelTimestampsEnabled": true,
    "timeToLiveHours": 48
  }
}
Propriedade Localização no corpo do pedido Descrição
contentContainerUrl Nível de raiz Você pode enviar arquivos de áudio individuais ou um contêiner de armazenamento inteiro.

Você deve especificar o local dos dados de áudio usando as propriedades contentContainerUrl ou contentUrls. Para mais informações sobre o armazenamento de blobs do Azure para transcrição em lote, veja Localizar ficheiros de áudio para transcrição em lote.

Esta propriedade não é retornada na resposta.
contentUrls Nível de raiz Você pode enviar arquivos de áudio individuais ou um contêiner de armazenamento inteiro.

Você deve especificar o local dos dados de áudio usando as propriedades contentContainerUrl ou contentUrls. Para obter mais informações, consulte Localizar arquivos de áudio para transcrição em lote.

Esta propriedade não é retornada na resposta.
displayName Nível de raiz O nome da transcrição do processamento em lote. Escolha um nome ao qual possa referir-se mais tarde. O nome para exibição não precisa ser exclusivo.

Esta propriedade é necessária.
locale Nível de raiz A configuração regional da transcrição em lote. Esse valor deve corresponder à localidade esperada dos dados de áudio a serem transcritos. A localidade não pode ser alterada posteriormente.

Esta propriedade é necessária.
model Nível de raiz Você pode definir a model propriedade para usar um modelo base específico ou um modelo de fala personalizado. Se você não especificar o model, o modelo base padrão para a localidade será usado. Para obter mais informações, consulte Usar um modelo personalizado e Usar um modelo Whisper.
channels Interior properties Uma matriz de números de canal para processar. Canais 0 e 1 são transcritos por padrão.
destinationContainerUrl Interior properties O resultado pode ser armazenado num contentor Azure. Se você não especificar um contêiner, o serviço de Fala armazenará os resultados em um contêiner gerenciado pela Microsoft. Quando o trabalho de transcrição é excluído, os dados do resultado da transcrição também são excluídos. Para obter mais informações, como os cenários de segurança suportados, consulte Especificar uma URL de contêiner de destino.
diarization Interior properties Indica que o serviço de Fala deve tentar a análise de diarização na entrada, que se espera que seja um canal mono que contenha várias vozes. O recurso não está disponível com gravações estéreo.

Diarização é o processo de separação de locutores em dados de áudio. O pipeline de lote pode reconhecer e separar vários alto-falantes em gravações de canal mono.

Especifique o número mínimo e máximo de pessoas que podem estar falando. Você também deve definir a diarizationEnabled propriedade como true. O ficheiro de transcrição contém uma speaker entrada para cada frase transcrita.

Você precisa usar essa propriedade quando espera três ou mais alto-falantes. Definir a propriedade diarizationEnabled para true é suficiente para dois alto-falantes. Para obter um exemplo do uso da propriedade, consulte Transcrições - Enviar.

O número máximo de falantes para diarização deve ser inferior a 36 e superior ou igual à minCount propriedade. Para obter um exemplo, consulte Transcrições - Enviar.

Quando essa propriedade é selecionada, o comprimento do áudio de origem não pode exceder 240 minutos por arquivo.

Nota: Esta propriedade só está disponível com a API REST de fala para texto versão 3.1 e posterior. Se você definir essa propriedade com qualquer versão anterior, como a versão 3.0, ela será ignorada e apenas dois alto-falantes serão identificados.
diarizationEnabled Interior properties Especifica que o serviço de reconhecimento de fala deve realizar uma análise de diarização na entrada, a qual se espera que seja um canal monofónico contendo duas vozes. O valor predefinido é false.

Para três ou mais vozes, você também precisa usar a propriedade diarization. Use somente com a API REST de fala para texto versão 3.1 e posterior.

Quando essa propriedade é selecionada, o comprimento do áudio de origem não pode exceder 240 minutos por arquivo.
displayFormWordLevelTimestampsEnabled Interior properties Especifica se os carimbos de hora a nível de palavra devem ser incluídos na forma de apresentação dos resultados da transcrição. Os resultados são retornados na displayWords propriedade do arquivo de transcrição. O valor predefinido é false.

Nota: Esta propriedade só está disponível com a API REST de fala para texto versão 3.1 e posterior.
languageIdentification Interior properties A identificação de idioma é usada para identificar idiomas falados em áudio quando comparados com uma lista de idiomas suportados.

Se definir a languageIdentification propriedade, então também deve definir a sua propriedade anexa candidateLocales.
languageIdentification.candidateLocales Interior properties Os locais potenciais para a identificação de língua, como "properties": { "languageIdentification": { "candidateLocales": ["en-US", "de-DE", "es-ES"]}}. Um mínimo de duas e um máximo de dez localidades candidatas, incluindo a localidade principal para a transcrição, são suportadas.
profanityFilterMode Interior properties Especifica como tratar palavrões nos resultados de reconhecimento de voz. Os valores aceites são None para desativar o filtro de profanidade, Masked para substituir a profanidade por asteriscos, Removed para remover toda a profanidade do resultado, ou Tags para adicionar etiquetas de profanidade. O valor predefinido é Masked.
punctuationMode Interior properties Especifica como gerir a pontuação nos resultados de reconhecimento. Os valores aceites são None desativar a pontuação, Dictated implicar pontuação explícita (falada), Automatic deixar o descodificador lidar com a pontuação ou DictatedAndAutomatic utilizar pontuação ditada e automática. O valor predefinido é DictatedAndAutomatic.

Esta propriedade não é aplicável a modelos Whisper.
timeToLiveHours Interior properties Esta propriedade obrigatória especifica por quanto tempo a transcrição deve ser mantida no sistema após sua conclusão.

Uma vez que a transcrição atinge o tempo de vida útil após a conclusão (bem-sucedida ou falhada), ela é automaticamente apagada.

A duração suportada mais curta é de 6 horas, a duração suportada mais longa é de 31 dias. O valor recomendado é de 48 horas (dois dias) quando os dados são consumidos diretamente.

Como alternativa, você pode chamar Transcrições - Excluir regularmente depois de recuperar os resultados da transcrição.
wordLevelTimestampsEnabled Interior properties Especifica se carimbos de data/hora no nível da palavra devem ser incluídos na saída. O valor predefinido é false.

Esta propriedade não é aplicável a modelos Whisper. Whisper é um modelo somente de exibição, portanto, o campo lexical não é preenchido na transcrição.

Para obter ajuda da CLI de fala com as opções de configuração de transcrição, execute o seguinte comando:

spx help batch transcription create advanced

Usar um modelo personalizado

A transcrição em lote usa o modelo base padrão para a localidade especificada. Não é necessário definir nenhuma propriedade para usar o modelo base padrão.

Opcionalmente, você pode modificar o exemplo de transcrição de criação anterior definindo a model propriedade para usar um modelo base específico ou um modelo de fala personalizado.

curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSpeechResoureKey" -H "Content-Type: application/json" -d '{
  "contentUrls": [
    "https://crbn.us/hello.wav",
    "https://crbn.us/whatstheweatherlike.wav"
  ],
  "locale": "en-US",
  "displayName": "My Transcription",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/models/base/ccccdddd-2222-eeee-3333-ffff4444aaaa"
  },
  "properties": {
    "wordLevelTimestampsEnabled": true,
  }
}'  "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/transcriptions:submit?api-version=2024-11-15"

spx batch transcription create --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav,https://crbn.us/whatstheweatherlike.wav --model "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/ccccdddd-2222-eeee-3333-ffff4444aaaa"

Para usar um modelo de fala personalizado para transcrição em lote, você precisa do URI do modelo. A propriedade de nível self superior no corpo da resposta é o URI do modelo. Você pode recuperar o local do modelo ao criar ou obter um modelo. Para obter mais informações, consulte o exemplo de resposta JSON em Criar um modelo.

Gorjeta

Um endpoint de implementação hospedada não é necessário para usar voz personalizada com o serviço de transcrição em lote. Você pode conservar recursos se usar o modelo de fala personalizado apenas para transcrição em lote.

As solicitações de transcrição em lote para modelos expirados falham com um erro 4xx. Defina a model propriedade como um modelo base ou modelo personalizado que não expirou. Caso contrário, não inclua a model propriedade para usar sempre o modelo base mais recente. Para obter mais informações, consulte Escolher um modelo e Ciclo de vida do modelo de fala personalizado.

Identificação linguística

Para identificar línguas com a API REST de transcrição em lote, use a propriedade languageIdentification no corpo do pedido Transcrições - Submeter.

Advertência

A transcrição em lote suporta apenas a identificação de idioma para modelos base padrão. Se a identificação do idioma e um modelo personalizado forem especificados na solicitação de transcrição, o serviço voltará a usar os modelos base para os idiomas candidatos especificados. Isso pode resultar em resultados de reconhecimento inesperados.

Se o seu cenário de fala para texto exigir tanto identificação linguística como modelos personalizados, use fala em tempo real em vez de transcrição em lote.

O exemplo a seguir mostra o languageIdentification uso da propriedade com quatro idiomas candidatos. Para mais informações sobre propriedades de solicitação, consulte Criar uma transcrição em lote.

{
    <...>
    
    "properties": {
    <...>
    
        "languageIdentification": {
            "candidateLocales": [
            "en-US",
            "ja-JP",
            "zh-CN",
            "hi-IN"
            ]
        },	
        <...>
    }
}

Use um modelo Whisper

O Azure Speech no Foundry Tools suporta o modelo Whisper da OpenAI utilizando a API de transcrição em lote. Você pode usar o modelo Whisper para transcrição em lote.

Nota

O Azure OpenAI nos Microsoft Foundry Models também suporta o modelo Whisper da OpenAI para voz para texto com uma API REST síncrona. Para saber mais, consulte Speech to text com o modelo Azure OpenAI Whisper. Para mais informações sobre quando usar Azure Speech vs. Azure OpenAI nos Microsoft Foundry Models, veja O que é o modelo Whisper?

Para usares um modelo Whisper para transcrição em lote, precisas de definir a model propriedade. Whisper é um modelo somente de exibição, portanto, o campo lexical não é preenchido na resposta.

Importante

A transcrição em lote usando modelos Whisper está disponível em um subconjunto de regiões que suportam a transcrição em lote. Para obter a lista atual de regiões suportadas, consulte a tabela Regiões do serviço de fala. Observe que o suporte ao modelo Whisper pode ser limitado a regiões específicas dentro daquelas que suportam transcrição em lote.

Você pode fazer uma solicitação Modelos - Listar Modelos Base para obter modelos base disponíveis para todas as localidades.

Faça uma solicitação HTTP GET como mostrado no exemplo a seguir para a eastus região. Substitui YourSpeechResoureKey pela tua chave de recursos do Microsoft Foundry. Substitua eastus se estiver usando uma região diferente.

curl -v -X GET "https://eastus.api.cognitive.microsoft.com/speechtotext/models/base?api-version=2024-11-15" -H "Ocp-Apim-Subscription-Key: YourSpeechResoureKey"

Por padrão, apenas os 100 modelos básicos mais antigos são retornados. Use os parâmetros de consulta skip e top para percorrer os resultados. Por exemplo, a solicitação a seguir retorna os próximos 100 modelos básicos após os primeiros 100.

curl -v -X GET "https://eastus.api.cognitive.microsoft.com/speechtotext/models/base?api-version=2024-11-15&skip=100&top=100" -H "Ocp-Apim-Subscription-Key: YourSpeechResoureKey"

Certifica-te de que defines as variáveis de configuração para um recurso Foundry para Fala numa das regiões suportadas. Você pode executar o spx csr list --base comando para obter modelos base disponíveis para todas as localidades.

Defina o parâmetro necessário api-version como v3.2. A CLI de fala ainda não suporta a versão 2024-11-15 ou posterior, então você deve usar v3.2 por enquanto.

spx csr list --base --api-version v3.2

A displayName propriedade de um modelo Whisper contém "Whisper", conforme mostrado neste exemplo. Whisper é um modelo somente de exibição, portanto, o campo lexical não é preenchido na transcrição.

{
  "links": {
    "manifest": "https://eastus.api.cognitive.microsoft.com/speechtotext/models/base/69adf293-9664-4040-932b-02ed16332e00/manifest?api-version=2024-11-15"
  },
  "properties": {
    "deprecationDates": {
      "adaptationDateTime": "2025-04-15T00:00:00Z",
      "transcriptionDateTime": "2026-04-15T00:00:00Z"
    },
    "features": {
      "supportsAdaptationsWith": [
        "Acoustic"
      ],
      "supportsTranscriptionsSubmit": true,
      "supportsTranscriptionsTranscribe": false,
      "supportsEndpoints": false,
      "supportsTranscriptionsOnSpeechContainers": false,
      "supportedOutputFormats": [
        "Display"
      ]
    },
    "chargeForAdaptation": true
  },
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/models/base/69adf293-9664-4040-932b-02ed16332e00?api-version=2024-11-15",
  "displayName": "20240228 Whisper Large V2",
  "description": "OpenAI Whisper Model in Azure Speech (Whisper v2-large)",
  "locale": "en-US",
  "createdDateTime": "2024-02-29T15:46:31Z",
  "lastActionDateTime": "2024-02-29T15:51:53Z",
  "status": "Succeeded"
},

Você define o URI do modelo completo como mostrado neste exemplo para a eastus região. Substitui YourSpeechResoureKey pela tua chave de recursos do Microsoft Foundry. Substitua eastus se estiver usando uma região diferente.

curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSpeechResoureKey" -H "Content-Type: application/json" -d '{
  "contentUrls": [
    "https://crbn.us/hello.wav",
    "https://crbn.us/whatstheweatherlike.wav"
  ],
  "locale": "en-US",
  "displayName": "My Transcription",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/models/base/69adf293-9664-4040-932b-02ed16332e00?api-version=2024-11-15"
  },
  "properties": {
    "wordLevelTimestampsEnabled": true,
  },
}'  "https://eastus.api.cognitive.microsoft.com/speechtotext/transcriptions:submit?api-version=2024-11-15"

Você define o URI do modelo completo como mostrado neste exemplo para a eastus região. Substitua eastus se estiver usando uma região diferente.

Defina o parâmetro necessário api-version como v3.2. A CLI de fala ainda não suporta a versão 2024-11-15 ou posterior, então você deve usar v3.2 por enquanto.

spx batch transcription create --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav,https://crbn.us/whatstheweatherlike.wav --model "https://eastus.api.cognitive.microsoft.com/speechtotext/models/base/ddddeeee-3333-ffff-4444-aaaa5555bbbb" --api-version v3.2

Configurar notificações de webhook

Em vez de consultar o estado da transcrição, pode registar um webhook para receber uma notificação quando um trabalho de transcrição for concluído (ou atingir qualquer outro estado terminal).

Utilize a operação Web hooks - Criar para registar um webhook endpoint. O serviço de voz envia callbacks HTTP POST para eventos de transcription.created, transcription.processing, transcription.succeeded, transcription.failed e transcription.deleted para o seu endpoint.

Requisitos de firewall

O serviço de voz inicia chamadas HTTPS de saída a partir da sua infraestrutura gerida para o seu endpoint webhook. Para aceitar essas chamadas, o firewall ou o grupo de segurança de rede do seu endpoint deve permitir o tráfego de entrada da etiqueta CognitiveServicesManagementde serviço Azure.

Importante

Se o tráfego recebido de CognitiveServicesManagement estiver bloqueado, o serviço de voz não consegue chegar ao seu endpoint. O registo do webhook é bem-sucedido — porque o registo envolve apenas uma chamada de saída do seu cliente para a API de Fala — mas todas as chamadas subsequentes falham silenciosamente.

Para endpoints alojados no Azure, adicione uma regra de entrada no seu grupo de segurança de rede:

  • Fonte: Etiqueta de serviço CognitiveServicesManagement
  • Porto de destino: 443 (HTTPS)
  • Ação: Permitir

Aperto de mão de validação de Webhook

Ao registar um novo webhook, o serviço de Voz envia imediatamente um pedido de validação para verificar que o seu endpoint está acessível e sob o seu controlo. O seu endpoint tem de responder corretamente ou o registo falhará.

O pedido de validação é o seguinte:

POST https://your-endpoint.example.com/?validationToken=<token>

Detalhes principais:

  • O token é entregue como um parâmetro de cadeia de consulta (validationToken), não no corpo do pedido.
  • O seu endpoint deve responder com HTTP 200 OK e devolver a cadeia de tokens bruta como texto simples (Content-Type: text/plain).
  • Devolver JSON (por exemplo, {"validationToken": "..."}) faz com que a validação falhe.

Importante

Erro comum: Ecoar o token como objeto JSON em vez de texto simples faz com que o registo do webhook falhe, sem erro claro do serviço. Devolva sempre o token como uma cadeia de texto simples.

Exemplo em Python: manipulador de validação

O exemplo seguinte mostra um endpoint mínimo de webhook em Python usando Flask. Lê validationToken da cadeia de consulta e devolve-a como texto simples.

import flask
import json

app = flask.Flask(__name__)

@app.route("/webhook", methods=["POST"])
def webhook():
    # Validation handshake: Speech sends the token as a query parameter.
    # Return it as plain text—do NOT return JSON.
    validation_token = flask.request.args.get("validationToken")
    if validation_token:
        return flask.Response(validation_token, status=200, mimetype="text/plain")

    # Normal event callback: parse the JSON body.
    event = flask.request.get_json(silent=True) or {}
    event_type = event.get("events", [{}])[0].get("kind", "")

    if event_type == "TranscriptionSucceeded":
        transcription_url = event.get("self", "")
        print(f"Transcription completed: {transcription_url}")
        # TODO: fetch results from transcription_url

    return flask.Response(status=200)

if __name__ == "__main__":
    app.run(port=5000)

Registe o webhook

Depois de o seu endpoint passar a validação, registe-o na operação Web hooks - Criar :

curl -X POST \
  -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "My Transcription Webhook",
    "events": {
      "transcriptionSucceeded": true,
      "transcriptionFailed": true
    },
    "webUrl": "https://your-endpoint.example.com/webhook"
  }' \
  "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/webhooks?api-version=2024-11-15"
  • Substitui YourSpeechResourceKey pela tua chave de recursos do Microsoft Foundry.
  • Substitui YourServiceRegion pela tua região de recursos.
  • Substitua o webUrl pelo URL do endpoint HTTPS publicamente acessível.

Para a lista completa de tipos de eventos suportados, consulte a referência aos ganchos Web.

Especificar uma URL de contêiner de destino

O resultado da transcrição pode ser armazenado num contentor Azure. Se você não especificar um contêiner, o serviço de Fala armazenará os resultados em um contêiner gerenciado pela Microsoft. Nesse caso, quando o trabalho de transcrição é excluído, os dados do resultado da transcrição também são excluídos.

Pode armazenar os resultados de uma transcrição em lote num contentor gravável de armazenamento Azure Blob usando a opção no pedido de criação de transcrição em lote . Esta opção utiliza apenas um URI SAS ad hoc e não suporta o mecanismo de segurança dos serviços de confiança do Azure. Esta opção também não suporta SAS baseada em política de acesso. O recurso de conta de armazenamento do contêiner de destino deve permitir todo o tráfego externo.

Se quiser armazenar os resultados de transcrição num contentor de armazenamento Azure Blob usando o mecanismo de segurança Trusted Azure services, considere usar Bring-your-own-storage (BYOS). Para mais informações, consulte o recurso Microsoft Foundry Traga o seu próprio armazenamento (BYOS) para conversão de voz em texto.

Conteúdos relacionados

  • Last updated on