Skip to main content
Referência da API de reconhecimento de arquivos de gravação Paraformer

SDK Java de reconhecimento de fala gravada Paraformer

Este tópico descreve os parâmetros e os detalhes da interface do SDK Java de reconhecimento de fala gravada Paraformer.

O Alibaba Cloud Model Studio lançou um domínio específico para workspace na região China (Pequim). O novo domínio dedicado oferece desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos migrar de dashscope.aliyuncs.com para {WorkspaceId}.cn-beijing.maas.aliyuncs.com.Substitua {WorkspaceId} pelo seu ID do Workspace real. O domínio existente permanece totalmente funcional.
Este documento aplica-se apenas à região China (Pequim). Para usar modelos, utilize uma chave de API da região China (Pequim).
Guia do usuário:Reconhecimento de fala não em tempo real

Pré-requisitos

Ative o serviço e Obtenha uma chave de API. Configure a chave de API como variável de ambiente em vez de codificá-la diretamente no código para evitar riscos de segurança causados por vazamento de código.
Quando for necessário fornecer acesso temporário a aplicativos ou usuários terceiros, ou quando você desejar controlar rigorosamente operações de alto risco, como acessar ou excluir dados confidenciais, recomendamos o uso de tokens de autenticação temporários.Em comparação com chaves de API de longo prazo, os tokens de autenticação temporários possuem curto período de validade (60 segundos) e maior segurança. Eles são adequados para cenários de chamada temporária e reduzem efetivamente o risco de vazamento da chave de API.Uso: No seu código, substitua a chave de API originalmente usada para autenticação pelo token de autenticação temporário obtido.

Início rápido

A Classe principal (Transcription) fornece interfaces para enviar tarefas de forma assíncrona, aguardar sincronamente a conclusão das tarefas e consultar resultados de tarefas assincronamente. Utilize um dos dois métodos de chamada a seguir para reconhecimento de fala gravada:
  • Envio assíncrono + espera síncrona: Após enviar uma tarefa, a thread atual é bloqueada até que a tarefa termine e o resultado do reconhecimento seja obtido.
  • Envio assíncrono + consulta assíncrona: Após enviar uma tarefa, consulte o resultado da tarefa a qualquer momento chamando a interface de consulta.

Envio assíncrono + espera síncrona

image
  1. Configure os Parâmetros de solicitação.
  2. Instancie a Classe principal (Transcription).
  3. Chame o método asyncCall da Classe principal (Transcription) para enviar uma tarefa de forma assíncrona.
    • O serviço de transcrição de arquivos processa as tarefas enviadas por meio da API com base no melhor esforço. Após o envio, a tarefa entra no estado de fila (PENDING). O tempo de espera depende do tamanho da fila e da duração do arquivo, não podendo ser estimado com precisão, mas geralmente é concluído em alguns minutos. Assim que o processamento começa, o reconhecimento de fala é concluído a uma velocidade centenas de vezes superior ao tempo real.
    • Após a conclusão de cada tarefa, o resultado do reconhecimento e o link de download da URL são válidos por 24 horas. Após a expiração, não é possível consultar a tarefa ou baixar resultados pela URL fornecida anteriormente.
  4. Chame o método wait da Classe principal (Transcription) para aguardar sincronamente a conclusão da tarefa. Os status das tarefas incluem PENDING, RUNNING, SUCCEEDED e FAILED. Quando a tarefa está no estado PENDING ou RUNNING, a interface wait fica bloqueada. Quando a tarefa está no estado SUCCEEDED ou FAILED, a interface wait deixa de ser bloqueada e retorna o resultado da tarefa. O método wait retorna o Resultado da tarefa (TranscriptionResult).
import com.alibaba.dashscope.audio.asr.transcription.*;
import com.google.gson.*;

import java.util.Arrays;

public class Main {
    public static void main(String[] args) {
        // The following configuration is for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
        // Create transcription request parameters
        TranscriptionParam param =
                TranscriptionParam.builder()
                        // If the API Key is not configured in an environment variable, replace apiKey with your own API Key
                        //.apiKey("apikey")
                        .model("paraformer-v2")
                        // "language_hints" is only supported by the paraformer-v2 model
                        .parameter("language_hints", new String[]{"zh", "en"})
                        .fileUrls(
                                Arrays.asList(
                                        "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav"))
                        .build();
        try {
            Transcription transcription = new Transcription();
            // Submit transcription request
            TranscriptionResult result = transcription.asyncCall(param);
            System.out.println("RequestId: " + result.getRequestId());
            // Block and wait for the task to complete and get the result
            result = transcription.wait(
                    TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
            // Print result
            System.out.println(result.getOutput());
        } catch (Exception e) {
            System.out.println("error: " + e);
        }
        System.exit(0);
    }
}

Envio assíncrono + consulta assíncrona

image
  1. Configure os Parâmetros de solicitação.
  2. Instancie a Classe principal (Transcription).
  3. Chame o método asyncCall da Classe principal (Transcription) para enviar uma tarefa de forma assíncrona.
    • O serviço de transcrição de arquivos processa as tarefas enviadas por meio da API com base no melhor esforço. Após o envio, a tarefa entra no estado de fila (PENDING). O tempo de espera depende do tamanho da fila e da duração do arquivo, não podendo ser estimado com precisão, mas geralmente é concluído em alguns minutos. Assim que o processamento começa, o reconhecimento de fala é concluído a uma velocidade centenas de vezes superior ao tempo real.
    • Após a conclusão de cada tarefa, o resultado do reconhecimento e o link de download da URL são válidos por 24 horas. Após a expiração, não é possível consultar a tarefa ou baixar resultados pela URL fornecida anteriormente.
  4. Chame repetidamente o método fetch da Classe principal (Transcription) até obter o resultado final da tarefa. Quando o status da tarefa for SUCCEEDED ou FAILED, interrompa a consulta periódica e processe o resultado. O método fetch retorna o Resultado da tarefa (TranscriptionResult).
import com.alibaba.dashscope.audio.asr.transcription.*;
import com.alibaba.dashscope.common.TaskStatus;
import com.google.gson.*;

import java.util.Arrays;

public class Main {
    public static void main(String[] args) {
        // The following configuration is for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
        // Create transcription request parameters
        TranscriptionParam param =
                TranscriptionParam.builder()
                        // If the API Key is not configured in an environment variable, replace apiKey with your own API Key
                        //.apiKey("apikey")
                        .model("paraformer-v2")
                        // "language_hints" is only supported by the paraformer-v2 model
                        .parameter("language_hints", new String[]{"zh", "en"})
                        .fileUrls(
                                Arrays.asList(
                                        "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav"))
                        .build();
        try {
            Transcription transcription = new Transcription();
            // Submit transcription request
            TranscriptionResult result = transcription.asyncCall(param);
            System.out.println("RequestId: " + result.getRequestId());
            // Loop to get the task result until the task finishes
            while (true) {
                result = transcription.fetch(TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
                if (result.getTaskStatus() == TaskStatus.SUCCEEDED || result.getTaskStatus() == TaskStatus.FAILED) {
                    break;
                }
                Thread.sleep(1000);
            }
            // Print result
            System.out.println(result.getOutput());
        } catch (Exception e) {
            System.out.println("error: " + e);
        }
        System.exit(0);
    }
}

Parâmetros de solicitação

Configure os parâmetros de solicitação pelos métodos encadeados de TranscriptionParam.
TranscriptionParam param = TranscriptionParam.builder()
  .model("paraformer-v2")
  // "language_hints" is only supported by the paraformer-v2 model
  .parameter("language_hints", new String[]{"zh", "en"})
  .fileUrls(
          Arrays.asList(
                  "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav"))
  .build();
ParâmetroTipoPadrãoObrigatórioDescrição
modelString
SimEspecifica o nome do modelo Paraformer para transcrição de arquivos de áudio/vídeo. Consulte Modelos suportados.
fileUrlsList<String>
SimLista de URLs dos arquivos de áudio/vídeo para transcrição. Suporta protocolos HTTP/HTTPS. Apenas uma URL é suportada por solicitação.Se os arquivos de áudio estiverem armazenados no OSS da Alibaba Cloud, o SDK não suporta URLs temporárias com o prefixo oss://.
vocabularyIdString
NãoID mais recente de palavras-chave. Suporta os modelos mais recentes da série v2 com configuração de idioma. As palavras-chave associadas a este ID entram em vigor para este reconhecimento de fala. Desativado por padrão. Para instruções de uso, consulte Palavras-chave personalizadas.
channelIdList<Integer>[0]NãoEspecifica os índices das faixas de áudio a serem reconhecidas em um arquivo de áudio multifaixa. Os índices começam em 0. Por exemplo, [0] significa reconhecer a primeira faixa, e [0, 1] significa reconhecer simultaneamente a primeira e a segunda faixas. Se este parâmetro for omitido, apenas a primeira faixa será processada por padrão.
Cada faixa especificada é faturada independentemente. Por exemplo, solicitar [0, 1] para um único arquivo incorre em duas cobranças separadas.
disfluencyRemovalEnabledBooleanfalseNãoFiltra palavras de preenchimento. Desativado por padrão.
timestampAlignmentEnabledBooleanfalseNãoDefine se o recurso de alinhamento de carimbos de data/hora deve ser ativado. Desativado por padrão.
specialWordFilterString
NãoEspecifica palavras sensíveis a serem processadas durante o reconhecimento de fala e permite definir diferentes métodos de processamento para diferentes palavras sensíveis.Se este parâmetro não for fornecido, o sistema usa a lógica interna de filtragem de palavras sensíveis, e as palavras correspondentes à lista de palavras sensíveis do Alibaba Cloud Model Studio nos resultados de reconhecimento serão substituídas por * de igual comprimento.Se este parâmetro for fornecido, as seguintes estratégias de processamento de palavras sensíveis podem ser implementadas:
  • Substituir por : Substitui palavras sensíveis correspondentes por de igual comprimento.
  • Filtrar diretamente: Remove completamente as palavras sensíveis correspondentes dos resultados de reconhecimento.
O valor deste parâmetro deve ser uma string JSON com a seguinte estrutura:
{
      "filter_with_signed": {
        "word_list": ["test"]
      },
      "filter_with_empty": {
        "word_list": ["start", "happen"]
      },
      "system_reserved_filter": true
    }
Descrições dos campos JSON:
  • filter_with_signed
    • Tipo: Object.
    • Obrigatório: Não.
    • Descrição: Configura a lista de palavras sensíveis a serem substituídas por . As palavras correspondentes nos resultados de reconhecimento serão substituídas por de igual comprimento.
    • Exemplo: Usando o JSON acima, o resultado do reconhecimento de fala para "Help me test this code" seria "Help me **** this code".
    • Campos internos:
      • word_list: Um array de strings listando as palavras sensíveis a serem substituídas.
  • filter_with_empty
    • Tipo: Object.
    • Obrigatório: Não.
    • Descrição: Configura a lista de palavras sensíveis a serem removidas (filtradas) dos resultados de reconhecimento. As palavras correspondentes serão completamente excluídas.
    • Exemplo: Usando o JSON acima, o resultado do reconhecimento de fala para "The game is about to start, right?" seria "The game is about to, right?".
    • Campos internos:
      • word_list: Um array de strings listando as palavras sensíveis a serem completamente removidas (filtradas).
  • system_reserved_filter
    • Tipo: Boolean.
    • Obrigatório: Não.
    • Padrão: true.
    • Descrição: Define se as regras internas de palavras sensíveis do sistema devem ser ativadas. Quando definido como true, a lógica interna de filtragem de palavras sensíveis também é ativada, e as palavras correspondentes à lista de palavras sensíveis do Alibaba Cloud Model Studio nos resultados de reconhecimento serão substituídas por * de igual comprimento.
language_hintsString[]["zh", "en"]NãoEspecifica os códigos de idioma da fala a ser reconhecida.Este parâmetro aplica-se apenas ao modelo paraformer-v2.Códigos de idioma suportados:
  • zh: Chinês
  • en: Inglês
  • ja: Japonês
  • yue: Cantonês
  • ko: Coreano
  • de: Alemão
  • fr: Francês
  • ru: Russo
É necessário definir language_hints pelo método parameter ou pelo método parameters da instância TranscriptionParam:
TranscriptionParam param = TranscriptionParam.builder()
      // "language_hints" is only supported by the paraformer-v2 model
      .model("paraformer-v2")
      .parameter("language_hints", new String[]{"zh", "en"})
      .build();
diarizationEnabledBooleanfalseNãoDiarização automática de falantes. Desativada por padrão.Aplica-se apenas a áudio mono. Áudio multicanal não suporta diarização de falantes.Quando este recurso está ativado, os resultados de reconhecimento incluirão um campo speaker_id para distinguir diferentes falantes.
Se a diarização de falantes estiver ativada, recomenda-se que a duração do áudio não exceda 2 horas, caso contrário, o reconhecimento pode falhar ou atingir o tempo limite.
Para um exemplo de speaker_id, consulte Descrição do resultado de reconhecimento.
speakerCountInteger
NãoUm valor de referência para o número de falantes. Valores válidos: inteiros de 2 a 100 (inclusive).Entra em vigor quando a diarização de falantes está ativada (diarizationEnabled definido como true).Por padrão, o sistema determina automaticamente o número de falantes. Se este parâmetro for configurado, ele serve apenas como uma dica para o algoritmo tentar gerar o número especificado de falantes, mas o número exato não é garantido.
apiKeyString
NãoA chave de API. Se a chave de API já estiver configurada em uma variável de ambiente, não é necessário defini-la no código. Caso contrário, defina-a no código.

Resposta

Resultado da tarefa (TranscriptionResult)

A classe TranscriptionResult encapsula o resultado da tarefa atual.
Interface/MétodoParâmetroValor de retornoDescrição
public String getRequestId()
NenhumrequestIdObtém o requestId.
public String getTaskId()
NenhumtaskIdObtém o taskId.
public TaskStatus getTaskStatus()
NenhumTaskStatus, o status da tarefaObtém o status da tarefa.TaskStatus é uma classe enum. Você só precisa prestar atenção aos quatro status seguintes: PENDING, RUNNING, SUCCEEDED e FAILED.
Quando uma tarefa contém várias subtarefas, desde que qualquer subtarefa tenha sucesso, o status geral da tarefa é marcado como SUCCEEDED. É necessário verificar o campo subtask_status para determinar o resultado de cada subtarefa.
public List<TranscriptionTaskResult> getResults()
NenhumResultado da subtarefa (TranscriptionTaskResult)Obtém o Resultado da subtarefa (TranscriptionTaskResult).Cada tarefa reconhece um ou mais arquivos de áudio. Arquivos de áudio diferentes são processados em subtarefas diferentes, portanto, cada tarefa corresponde a uma ou mais subtarefas.
public JsonObject getOutput()
NenhumResultado da tarefa em formato JSONObtém o resultado da tarefa.O resultado está em formato JSON. Se você usar a interface getOutput para obter o resultado da tarefa, analise-o manualmente.
Exemplo normal
{
        "task_id":"0795ff8c-b666-4e91-bb8b-xxx",
        "task_status":"SUCCEEDED",
        "submit_time":"2025-02-13 16:12:09.109",
        "scheduled_time":"2025-02-13 16:12:09.128",
        "end_time":"2025-02-13 16:12:10.189",
        "results":[
            {
                "file_url":"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
                "transcription_url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20250213/16%3A12/3baafe5f-d09d-46c6-8b01-724927670edb-1.json?Expires=1739520730&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
                "subtask_status":"SUCCEEDED"
            }
        ],
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":1,
            "FAILED":0
        }
    }
Exemplo de erro"code" é o código de erro e "message" é a mensagem de erro. Esses dois campos aparecem apenas em cenários de erro. Use-os para solucionar problemas consultando Códigos de erro.
{
        "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2024-12-16 16:30:59.170",
        "scheduled_time": "2024-12-16 16:30:59.204",
        "end_time": "2024-12-16 16:31:02.375",
        "results": [
            {
                "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/rich_text_exaple_1.wav",
                "code": "InvalidFile.DownloadFailed",
                "message": "The audio file cannot be downloaded.",
                "subtask_status": "FAILED"
            }
        ],
        "task_metrics": {
            "TOTAL": 1,
            "SUCCEEDED": 0,
            "FAILED": 1
        }
    }

Resultado da subtarefa (TranscriptionTaskResult)

A classe TranscriptionTaskResult encapsula o resultado da subtarefa. Uma subtarefa reconhece um único arquivo de áudio.
Interface/MétodoParâmetroValor de retornoDescrição
public String getFileUrl()
NenhumURL do arquivo de áudio reconhecidoObtém a URL do arquivo de áudio reconhecido.
public String getTranscriptionUrl()
NenhumURL do resultado de reconhecimentoObtém a URL do resultado de reconhecimento. Esta URL é válida por 24 horas. Após a expiração, não é possível consultar a tarefa ou baixar resultados pela URL fornecida anteriormente.O resultado de reconhecimento é salvo como um arquivo JSON. Baixe o arquivo pela URL acima ou leia diretamente seu conteúdo por uma solicitação HTTP.Para o significado de cada campo nos dados JSON, consulte Descrição do resultado de reconhecimento.
public TaskStatus getSubTaskStatus()
NenhumTaskStatus, o status da subtarefaObtém o status da subtarefa.TaskStatus é uma classe enum. Você só precisa prestar atenção aos quatro status seguintes: PENDING, RUNNING, SUCCEEDED e FAILED.
public String getMessage()
NenhumInformações chave durante a execução da tarefa, que podem estar vaziasObtém informações chave durante a execução da tarefa.Quando uma tarefa falha, verifique este conteúdo para analisar a causa.

Descrição do resultado de reconhecimento

O resultado de reconhecimento é salvo como um arquivo JSON.
{
    "file_url":"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
    "properties":{
        "audio_format":"pcm_s16le",
        "channels":[
            0
        ],
        "original_sampling_rate":16000,
        "original_duration_in_milliseconds":3834
    },
    "transcripts":[
        {
            "channel_id":0,
            "content_duration_in_milliseconds":3720,
            "text":"Hello world, this is the Alibaba speech laboratory.",
            "sentences":[
                {
                    "begin_time":100,
                    "end_time":3820,
                    "text":"Hello world, this is the Alibaba speech laboratory.",
                    "sentence_id":1,
                    "speaker_id":0, //This field is only displayed when automatic speaker diarization is enabled
                    "words":[
                        {
                            "begin_time":100,
                            "end_time":596,
                            "text":"Hello ",
                            "punctuation":""
                        },
                        {
                            "begin_time":596,
                            "end_time":844,
                            "text":"world",
                            "punctuation":", "
                        }
                        // Other content omitted here
                    ]
                }
            ]
        }
    ]
}
Os principais parâmetros são os seguintes:

Parâmetro

Tipo

Descrição

audio_format

string

O formato de áudio do arquivo de origem.

channels

array[integer]

As informações de índice da faixa de áudio do arquivo de origem. Retorna [0] para áudio mono, [0, 1] para áudio de duas faixas, e assim por diante.

original_sampling_rate

integer

A taxa de amostragem (Hz) do áudio no arquivo de origem.

original_duration

integer

A duração original do áudio (ms) do arquivo de origem.

channel_id

integer

O índice da faixa de áudio do resultado de transcrição, começando em 0.

content_duration

integer

A duração (ms) do conteúdo identificado como fala na faixa de áudio.

O serviço de modelo de reconhecimento de fala Paraformer transcreve e mede apenas o conteúdo identificado como fala na faixa de áudio, faturando de acordo. Conteúdo sem fala não é medido nem faturado. Normalmente, a duração do conteúdo de fala é menor que a duração original do áudio. Como a determinação da existência de conteúdo de fala é feita por um modelo de IA, pode haver algum desvio em relação à situação real.

transcript

string

O resultado de transcrição de fala no nível de parágrafo.

sentences

array

O resultado de transcrição de fala no nível de sentença.

words

array

O resultado de transcrição de fala no nível de palavra.

begin_time

integer

O carimbo de data/hora inicial (ms).

end_time

integer

O carimbo de data/hora final (ms).

text

string

O resultado de transcrição de fala.

speaker_id

integer

O índice do falante atual, começando em 0, usado para distinguir diferentes falantes.

Este campo é exibido nos resultados de reconhecimento apenas quando a diarização de falantes está ativada.

punctuation

string

A pontuação prevista após a palavra (se houver).

Interfaces principais

Classe de parâmetros de consulta de tarefa (TranscriptionQueryParam)

Utilize TranscriptionQueryParam ao aguardar a conclusão de uma tarefa (chamando o método Transcription wait) ou ao consultar o resultado da tarefa (chamando o método Transcription fetch). Crie uma instância de TranscriptionQueryParam pelo método estático FromTranscriptionParam.
// Create transcription request parameters
TranscriptionParam param =
        TranscriptionParam.builder()
                // If the API Key is not configured in an environment variable, replace apiKey with your own API Key
                //.apiKey("apikey")
                .model("paraformer-v2")
                // "language_hints" is only supported by the paraformer-v2 model
                .parameter("language_hints", new String[]{"zh", "en"})
                .fileUrls(
                        Arrays.asList(
                                "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav"))
                .build();
try {
    Transcription transcription = new Transcription();
    // Submit transcription request
    TranscriptionResult result = transcription.asyncCall(param);
    System.out.println("RequestId: " + result.getRequestId());
    TranscriptionQueryParam queryParam = TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId());

} catch (Exception e) {
    System.out.println("error: " + e);
}
Interface/MétodoParâmetroValor de retornoDescrição
public static TranscriptionQueryParam FromTranscriptionParam(TranscriptionParam param, String taskId)
  • param: Uma instância de TranscriptionParam
  • taskId: O ID da tarefa
Uma instância de TranscriptionQueryParamCria uma instância de TranscriptionQueryParam.

Classe principal (Transcription)

Importe Transcription com "import com.alibaba.dashscope.audio.asr.transcription.*;". Suas interfaces principais são as seguintes:
Interface/MétodoParâmetroValor de retornoDescrição
public TranscriptionResult asyncCall(TranscriptionParam param)
param: Parâmetros de reconhecimento de fala, uma instância de TranscriptionParamResultado da tarefa (TranscriptionResult)Envia uma tarefa de reconhecimento de fala de forma assíncrona.
public TranscriptionResult wait(TranscriptionQueryParam queryParam)
queryParam: Uma instância de TranscriptionQueryParamResultado da tarefa (TranscriptionResult)Bloqueia a thread atual até que a tarefa assíncrona termine (o status da tarefa seja SUCCEEDED ou FAILED).
public TranscriptionResult fetch(TranscriptionQueryParam queryParam)
queryParam: Uma instância de TranscriptionQueryParamResultado da tarefa (TranscriptionResult)Consulta o resultado da tarefa atual de forma assíncrona.

Códigos de erro

Se encontrar erros, consulte Códigos de erro para solução de problemas. Se o problema persistir, junte-se à comunidade de desenvolvedores para relatar o problema e forneça o Request ID para investigação adicional. Quando uma tarefa contém várias subtarefas, desde que qualquer subtarefa tenha sucesso, o status geral da tarefa é marcado como SUCCEEDED. Verifique o campo subtask_status para determinar o resultado de cada subtarefa. Exemplo de resposta de erro:
{
    "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-12-16 16:30:59.170",
    "scheduled_time": "2024-12-16 16:30:59.204",
    "end_time": "2024-12-16 16:31:02.375",
    "results": [
        {
            "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/rich_text_exaple_1.wav",
            "code": "InvalidFile.DownloadFailed",
            "message": "The audio file cannot be downloaded.",
            "subtask_status": "FAILED"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 0,
        "FAILED": 1
    }
}

Mais exemplos

Para mais exemplos, consulte o GitHub.

FAQ

Perguntas sobre recursos

P: Suporta áudio codificado em Base64?

Não. Áudio codificado em Base64 não é suportado. Apenas áudio acessível via URLs publicamente acessíveis é suportado. Fluxos binários e reconhecimento direto de arquivos locais não são suportados.

P: Como fornecer arquivos de áudio como URLs publicamente acessíveis?

Geralmente, siga estas etapas (esta é uma abordagem geral; os detalhes variam conforme o produto de armazenamento. Recomendamos fazer upload do áudio para o Alibaba Cloud OSS):
Por exemplo:
  • Object Storage Service (recomendado):
    • Use o serviço de armazenamento de objetos de um provedor de nuvem (como o Alibaba Cloud OSS) para fazer upload de arquivos de áudio para um bucket e configurá-los para acesso público.
    • Vantagens: Alta disponibilidade, suporte a aceleração CDN, gerenciamento fácil.
  • Servidor web:
    • Coloque arquivos de áudio em um servidor web que suporte acesso HTTP/HTTPS (como Nginx ou Apache).
    • Vantagens: Adequado para pequenos projetos ou testes locais.
  • Content Delivery Network (CDN):
    • Hospede arquivos de áudio em uma CDN e acesse-os pela URL fornecida pela CDN.
    • Vantagens: Entrega acelerada de arquivos, adequada para cenários de alta concorrência.
Faça upload dos arquivos de áudio com base no método de armazenamento/hospedagem escolhido, por exemplo:
  • Object Storage Service:
    • Faça login no console do provedor de nuvem e crie um bucket.
    • Faça upload dos arquivos de áudio e defina as permissões do arquivo como "leitura pública" ou gere links de acesso temporário.
  • Servidor web:
    • Coloque os arquivos de áudio no diretório designado do servidor (como /var/www/html/audio/).
    • Garanta que os arquivos sejam acessíveis via HTTP/HTTPS.
Por exemplo:
  • Object Storage Service:
    • Após o upload, o sistema gera automaticamente uma URL de acesso público (geralmente no formato https://<bucket-name>.<region>.aliyuncs.com/<file-name>).
    • Se precisar de um domínio mais amigável, vincule um domínio personalizado e ative HTTPS.
  • Servidor web:
    • A URL de acesso ao arquivo é tipicamente o endereço do servidor mais o caminho do arquivo (como https://your-domain.com/audio/file.mp3).
  • CDN:
    • Após configurar a aceleração CDN, use a URL fornecida pela CDN (como https://cdn.your-domain.com/audio/file.mp3).
Em um ambiente de rede pública, garanta que a URL gerada seja acessível, por exemplo:
  • Abra a URL em um navegador e verifique se o arquivo de áudio pode ser reproduzido.
  • Use ferramentas (como curl ou Postman) para verificar se a URL retorna uma resposta HTTP correta (código de status 200).
Ao usar o SDK, se os arquivos de áudio estiverem armazenados no Alibaba Cloud OSS, URLs temporárias com o prefixo oss:// não são suportadas. Ao usar a API RESTful, se os arquivos de áudio estiverem armazenados no Alibaba Cloud OSS, URLs temporárias com o prefixo oss:// são suportadas:
  • A URL temporária é válida por 48 horas e não pode ser usada após expirar. Não a utilize em ambiente de produção.
  • A API para obtenção de credencial de upload é limitada a 100 QPS e não suporta scale-out. Não a utilize em ambientes de produção, cenários de alta concorrência ou cenários de teste de estresse.
  • Para ambientes de produção, use um serviço de armazenamento estável, como o OSS, para garantir disponibilidade de arquivos a longo prazo e evitar problemas de limitação de taxa.

P: Quanto tempo leva para obter os resultados de reconhecimento?

Após o envio, a tarefa entra em um estado de fila (PENDING). O tempo de espera depende do tamanho da fila e da duração do arquivo, não podendo ser estimado com precisão, mas geralmente é concluído em alguns minutos. Aguarde pacientemente. Arquivos de áudio mais longos exigem mais tempo de processamento.

Solução de problemas

Se encontrar erros de código, solucione o problema com base nas informações em Códigos de erro.

P: O que fazer se o resultado de reconhecimento e a reprodução de áudio estiverem dessincronizados?

Defina o Parâmetro de solicitação timestampAlignmentEnabled como true para ativar o recurso de alinhamento de carimbos de data/hora, que sincroniza o resultado de reconhecimento com a reprodução de áudio.

P: Não consigo obter resultados após consulta contínua?

Isso pode ocorrer devido à limitação de taxa. Aguarde pacientemente. Se precisar de expansão de capacidade, junte-se à comunidade de desenvolvedores para solicitar.

P: Por que não há resultado de reconhecimento (não consegue reconhecer a fala)?

  • Verifique se o áudio atende aos requisitos (formato, taxa de amostragem).
  • Se estiver usando o modelo paraformer-v2, verifique se a configuração language_hints está correta.
  • Se nenhuma das opções acima resolver o problema, personalize palavras-chave para melhorar o reconhecimento de palavras específicas.

Mais perguntas

Consulte o QA no GitHub.
Referência da API de Geração de Texto
Geração de Imagens
  • FAQ
Geração de Vídeo
Áudio
API em tempo real
Incorporação de Texto
Produção de Modelos