Qwen-Audio-3.0-ASR-Flash-Filetrans/Fun-ASR API HTTP para reconhecimento de fala em tempo não real

Transcrição de arquivo REST

Este tópico descreve os parâmetros e detalhes da interface da API HTTP para reconhecimento de fala em tempo não real com Qwen-Audio-3.0-ASR-Flash-Filetrans e Fun-ASR.

Guia do usuário: Reconhecimento de fala em tempo não real. Para requisitos de entrada, como formatos de áudio suportados, limites de tamanho de arquivo e limites de duração, consulte Especificações de áudio.

##Como funciona

Ao contrário das chamadas síncronas do DashScope, que retornam o resultado imediatamente em uma única solicitação, as chamadas assíncronas são projetadas para arquivos de áudio longos ou tarefas demoradas. Este modo usa um fluxo de envio e pesquisa em duas etapas que evita tempos limite de solicitação causados por longas esperas:

1. Etapa 1: Envie a tarefa.

   • O cliente envia uma solicitação de processamento assíncrono.
   • Após validar a solicitação, o servidor não executa a tarefa imediatamente. Em vez disso, ele retorna um único task_id para indicar que a tarefa foi criada com sucesso.

2. Etapa 2: Recupere o resultado.

   • O cliente usa o retornado task_id para pesquisar a interface de consulta repetidamente.
   • Quando a tarefa termina, a interface de consulta retorna o resultado final do reconhecimento.

Pré-requisitos

Faça login em QwenCloud e criar uma chave de API. Para evitar riscos de segurança, exporte a chave de API como uma variável de ambiente em vez de codificá-lo.

Para conceder acesso temporário ou restringir operações confidenciais, use um token temporário.

Os tokens temporários expiram em 60 segundos, reduzindo o risco de vazamento. Substitua a chave API no seu código pelo token temporário.

Terminais de serviço

Interface de envio de tarefa: POST https://maas.qwencloudapi.com/api/v1/services/audio/asr/transcription

Interface de tarefa de consulta: GET https://maas.qwencloudapi.com/api/v1/tasks/{task_id}

Solicitar cabeçalhos

Enviar interface de tarefa

Envia uma tarefa de reconhecimento de fala. Essa interface retorna de forma assíncrona, portanto, pesquise o status da tarefa com a Interface de tarefa de consulta.

Basic call

```bash
curl --location 'https://maas.qwencloudapi.com/api/v1/services/audio/asr/transcription' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
     --header "Content-Type: application/json" \
     --header "X-DashScope-Async: enable" \
     --data '{
    "model": "qwen-audio-3.0-asr-flash-filetrans",
    "input": {
        "file_urls": [
            "{YOUR_AUDIO_URL}"
        ]
    },
    "parameters": {
        "channel_id": [0]
    }
}'
```

Inline hotwords

Use hotwords in-line no seguinte formato:

```json
{
    "model": "qwen-audio-3.0-asr-flash-filetrans",
    "input": {
        "file_urls": [
            "{YOUR_AUDIO_URL}"
        ]
    },
    "parameters": {
        "vocabulary": {"John Smith": 5, "Jane Doe": 5}
    }
}
```

Context

Use o contexto no seguinte formato:

```json
{
    "model": "qwen-audio-3.0-asr-flash-filetrans",
    "input": {
        "file_urls": [
            "{YOUR_AUDIO_URL}"
        ],
        "context": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": "Hello there"
                    }
                ]
            },
            {
                "role": "assistant",
                "content": [
                    {
                        "type": "text",
                        "text": "Hello, I am Qwen. How can I help you?"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "vocabulary": {"John Smith": 5, "Jane Doe": 5}
    }
}
```

Parâmetros de solicitação

Somente qwen-audio-3.0-asr-flash-filetrans suporta hotwords in-line (vocabulary parâmetro).

Cada faixa de áudio em channel_id é cobrado separadamente. Exemplo: [0, 1] em um arquivo = duas cobranças.

Quando a diarização do alto-falante estiver ativada, mantenha a duração do áudio em 2 horas. Caso contrário, o reconhecimento poderá falhar ou expirar.

detalhes do parâmetro de contexto

O context parâmetro é uma lista de mensagens que fornecem contexto de conversação opcional para melhorar a precisão do reconhecimento.

O SDK ainda não oferece suporte a esse recurso.

O aprimoramento do contexto melhora a precisão do reconhecimento de termos específicos de domínio. Para uso, consulte Aprimoramento de contexto.

Restrições: mensagens de contexto do input_text e text cada tipo é limitado a 5 mensagens. Se você exceder esse limite, apenas os 5 mais recentes serão mantidos. O comprimento total do texto por turno de contexto (o comprimento combinado do text campos para user e assistant) não deve exceder 400 caracteres (contados por caractere, cada caractere conta como 1). Qualquer excesso é truncado no final.

Quando você inclui contexto, a ordem das mensagens em messages questões: as mensagens de contexto devem ser organizadas por turno de conversa. Dentro de cada turno, o user mensagem (input_text tipo) deve vir antes do correspondente assistant mensagem (text tipo). Um user mensagem que contém input_audio deve ser colocado em último lugar messages matriz.

papel string (Obrigatório)

A função da mensagem. Valores válidos:

• user: resultados de reconhecimento de turnos anteriores ou uma lista de palavras específicas do domínio.
• assistant: as respostas do modelo de linguagem grande de turnos anteriores.

conteúdo array(object) (Obrigatório)

A lista de itens de conteúdo da mensagem.

**tipo** `string` **(Obrigatório)**

O tipo de conteúdo. Valores válidos:

- `input_text` (opcional, contexto): resultados de reconhecimento da fala do usuário em turnos anteriores ou uma lista de palavras específicas do domínio (a função é usuário). Você também deve passar pelo `text` campo.
- `text` (opcional, contexto): as respostas do modelo de linguagem grande de turnos anteriores (a função é de assistente). Você também deve passar pelo `text` campo.

**texto** `string` **(Condicionalmente obrigatório)**

Quando `type` é `input_text`, insira os resultados de reconhecimento da fala do usuário em turnos anteriores ou uma lista de palavras específicas do domínio. Quando `type` é `text`, insira as respostas do modelo de linguagem grande dos turnos anteriores. O texto é contado por caractere e cada caractere conta como 1. O comprimento combinado do `text` os campos em todas as mensagens em uma mudança de contexto não devem exceder 400 caracteres. Qualquer excesso é truncado no final.

Detalhes do filtro de palavras confidenciais

Se special_word_filter não estiver definido, o filtro integrado substituirá as palavras correspondentes por asteriscos (*) de igual comprimento.

Se definido, você poderá usar estas políticas:

• Substitua por *: Substitui palavras correspondentes por asteriscos do mesmo comprimento.
• Filtrar: Remove palavras correspondentes do resultado.

O valor deve ser uma string JSON:

{
  "filter_with_signed": {
  "word_list": ["test"]
  },
  "filter_with_empty": {
  "word_list": ["start", "happen"]
  },
  "system_reserved_filter": true
}

Descrições dos campos:

• filter_with_signed

  • Tipo: objeto. Obrigatório: Não.
  • As palavras correspondentes são substituídas por asteriscos do mesmo comprimento.
  • Exemplo: "Ajude-me a testar este trecho de código" torna-se "Ajude-me **** este trecho de código".
  • Campo interno: word_list -- Uma matriz de strings de palavras a serem substituídas.

• filter_with_empty

  • Tipo: objeto. Obrigatório: Não.
  • As palavras correspondentes são removidas do resultado.
  • Exemplo: “O jogo está prestes a começar?” torna-se "O jogo está prestes a acontecer?".
  • Campo interno: word_list -- Uma matriz de strings de palavras a serem removidas.

• system_reserved_filter

  • Tipo: Booleano. Obrigatório: Não. Padrão: true.
  • Ativa as regras de palavras sensíveis predefinidas do sistema. Quando true, palavras que correspondem a QwenCloud lista de palavras sensíveis são substituídos por asteriscos do mesmo comprimento.

Idiomas suportados

Códigos de idiomas suportados por modelo:

• qwen-audio-3.0-asr-flash-filetrans, fun-asr:
  • zh: Chinês
  • en: Inglês
  • ja: Japonês
  • ko: Coreano
  • vi: vietnamita
  • id: Indonésio
  • th: Tailandês
  • ms: malaio
  • tl: Filipino
  • ar: Árabe
  • bg: Búlgaro
  • hr: Croata
  • cs: Tcheco
  • da: dinamarquês
  • nl: Holandês
  • et: Estónio
  • fi: Finlandês
  • el: Grego
  • hi: Hindi
  • hu: Húngaro
  • ga: irlandês
  • lv: letão
  • lt: Lituano
  • mt: maltês
  • pl: Polonês
  • pt: Português
  • ro: romeno
  • sk: Eslovaco
  • sl: Esloveno
  • sv: Sueco

Parâmetros de resposta

Clique para ver uma amostra de resposta.

{
  "output": {
  "task_status": "PENDING",
  "task_id": "c2e5d63b-96e1-4607-bb91-************"
  },
  "request_id": "77ae55ae-be17-97b8-9942-************"
}

Interface de tarefa de consulta

Informações básicas

Cabeçalhos de solicitação:

Authorization: Bearer $DASHSCOPE_API_KEY

Parâmetros de solicitação

Clique para ver uma amostra de pedido.

curl --location 'https://maas.qwencloudapi.com/api/v1/tasks/{task_id}' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY"

Parâmetros de resposta

Trabalhos com múltiplas subtarefas: o status geral é exibido SUCCEEDED se alguma subtarefa for bem-sucedida. Verifique subtask_status para determinar o resultado de uma subtarefa específica.

Clique para ver uma amostra de resposta (sucesso)

{
  "request_id": "f9e1afad-94d3-997e-a83b-************",
  "output": {
  "task_id": "f86ec806-4d73-485f-a24f-************",
  "task_status": "SUCCEEDED",
  "submit_time": "2024-09-12 15:11:40.041",
  "scheduled_time": "2024-09-12 15:11:40.071",
  "end_time": "2024-09-12 15:11:40.903",
  "results": [
      {
    "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav",
    "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/pre/filetrans-16k/20240912/15%3A11/3bdf7689-b598-409d-806a-121cff5e4a31-1.json?Expires=1726211500&OSSAccessKeyId=yourOSSAccessKeyId&Signature=Fj%2BaF%2FH0Kayj3w3My2ECBeP****%3D",
    "subtask_status": "SUCCEEDED"
      },
      {
    "file_url": "{YOUR_AUDIO_URL}",
    "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/pre/filetrans-16k/20240912/15%3A11/409a4b92-445b-4dd8-8c1d-f110954d82d8-1.json?Expires=1726211500&OSSAccessKeyId=yourOSSAccessKeyId&Signature=v5Owy5qoAfT7mzGmQgH0g8C****%3D",
    "subtask_status": "SUCCEEDED"
      }
  ],
  "task_metrics": {
      "TOTAL": 2,
      "SUCCEEDED": 2,
      "FAILED": 0
  }
  },
  "usage": {
  "duration": 9
  }
}

Clique para ver uma amostra de resposta (falha parcial)

O code campo contém o código do erro e o message campo contém a mensagem de erro. Esses campos aparecem apenas em erros.

{
  "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/long_audio_demo_cn.mp3",
      "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20241216/xxxx",
      "subtask_status": "SUCCEEDED"
    },
    {
      "file_url": "{YOUR_AUDIO_URL}",
      "code": "FILE_DOWNLOAD_FAILED",
      "message": "FILE_DOWNLOAD_FAILED",
      "subtask_status": "FAILED"
    }
  ],
  "task_metrics": {
    "TOTAL": 2,
    "SUCCEEDED": 1,
    "FAILED": 1
  }
}

Outras interfaces: status da tarefa de consulta em lote/cancelar uma tarefa

Para obter detalhes, consulte Gerenciar tarefas assíncronas: você pode consultar em lote tarefas de reconhecimento de fala que não sejam em tempo real enviadas nas últimas 24 horas e cancelar tarefas no PENDING estado (na fila).

Descrição do resultado do reconhecimento

O resultado do reconhecimento é salvo como um arquivo JSON.

Clique para ver o exemplo do resultado do reconhecimento.

{
  "file_url": "{YOUR_AUDIO_URL}",
  "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 Alibaba Speech Lab.",
      "sentences": [
        {
          "begin_time": 100,
          "end_time": 3820,
          "text": "Hello world, this is Alibaba Speech Lab.",
          "sentence_id": 1,
          "speaker_id": 0,
          "words": [
            {
              "begin_time": 100,
              "end_time": 596,
              "text": "Hello ",
              "punctuation": ""
            },
            {
              "begin_time": 596,
              "end_time": 844,
              "text": "world",
              "punctuation": ", "
            }
          ]
        }
      ]
    }
  ]
}

O `speaker_id` O campo aparece somente quando a diarização do alto-falante está habilitada. Outras entradas de palavras são omitidas por questões de brevidade.

Parâmetros principais:

O serviço do modelo de reconhecimento de fala transcreve apenas o conteúdo de uma faixa identificada como fala e mede e fatura com base nessa duração. O conteúdo não falado não é medido nem cobrado. Normalmente, a duração do conteúdo da fala é menor que a duração do áudio original. Como a existência do conteúdo da fala é determinada por um modelo de IA, o resultado pode diferir ligeiramente da situação real.

Fun-ASR-Flash (síncrono)

As chamadas SDK não são suportadas para este recurso. Use a API HTTP diretamente.

Informações básicas

Cabeçalhos de solicitação:

Authorization: Bearer $DASHSCOPE_API_KEY
Content-Type: application/json
X-DashScope-SSE: enable

Definir X-DashScope-SSE para enable para ativar o modo de streaming SSE. O servidor transmite apenas resultados de reconhecimento intermediários em vários eventos quando o áudio tem pelo menos 1 minuto de duração; caso contrário, apenas o resultado final será retornado. Definir X-DashScope-SSE para disable (ou omitir o cabeçalho) para receber apenas o resultado final.

Parâmetros de solicitação

Non-streaming

```bash
curl --location --request POST 'https://maas.qwencloudapi.com/api/v1/services/aigc/multimodal-generation/generation' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
     --header "Content-Type: application/json" \
     --header "X-DashScope-SSE: disable" \
     --data '{
    "model": "fun-asr-flash-2026-06-15",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav"
                        }
                    }
                ]
            }
        ]
    },
    "parameters": {
        "format": "wav",
        "sample_rate": "16000"
    }
}'
```

Streaming

```bash
curl --location --request POST 'https://maas.qwencloudapi.com/api/v1/services/aigc/multimodal-generation/generation' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
     --header "Content-Type: application/json" \
     --header "X-DashScope-SSE: enable" \
     --data '{
    "model": "fun-asr-flash-2026-06-15",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav"
                        }
                    }
                ]
            }
        ]
    },
    "parameters": {
        "format": "wav",
        "sample_rate": "16000"
    }
}'
```

With context

```bash
curl --location --request POST 'https://maas.qwencloudapi.com/api/v1/services/aigc/multimodal-generation/generation' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
     --header "Content-Type: application/json" \
     --header "X-DashScope-SSE: disable" \
     --data '{
    "model": "fun-asr-flash-2026-06-15",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [{"type": "input_text", "text": "Hello!"}]
            },
            {
                "role": "assistant",
                "content": [{"type": "text", "text": "Hello! I am Tongyi Qianwen. How can I help you?"}]
            },
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav"
                        }
                    }
                ]
            }
        ]
    },
    "parameters": {
        "format": "wav",
        "sample_rate": "16000"
    }
}'
```

Mensagens de contexto (input_text e text tipos) são limitados a 5 cada. Quando excedido, apenas os 5 mais recentes são retidos. A ordem das mensagens é importante: cada user mensagem de contexto deve preceder seu correspondente assistant mensagem, e o user mensagem com input_audio deve ser sempre o último em input.messages.

###Base64

Você pode fornecer áudio codificado em Base64 como um URI de dados no formato data:{MIME_TYPE};base64,{DATA}:

• {MIME_TYPE}: tipo MIME, que varia de acordo com o formato de áudio. Por exemplo: WAV usa audio/wav, MP3 usa audio/mpeg.
• {DATA}: a string codificada em Base64 do arquivo de áudio.

A codificação Base64 aumenta o tamanho do arquivo. Mantenha o arquivo original pequeno o suficiente para que os dados codificados ainda atinjam o limite de tamanho de entrada de áudio (10 MB).

Exemplo: data:audio/wav;base64,SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4LjI5LjEwMAAAAAAAAAAAAAAA//PAxABQ/BXRbMPe4IQAhl9

Python

```python
import base64, pathlib

# input.mp3 is the local audio file to recognize. Replace it with the path to your own audio file and make sure it meets the audio requirements.
file_path = pathlib.Path("input.mp3")
base64_str = base64.b64encode(file_path.read_bytes()).decode()
data_uri = f"data:audio/mpeg;base64,{base64_str}"
```

Java

```java
import java.nio.file.*;
import java.util.Base64;

public class Main {
  /**
   * filePath is the local audio file to recognize. Replace it with the path to your own audio file and make sure it meets the audio requirements.
   */
  public static String toDataUri(String filePath) throws Exception {
    byte[] bytes = Files.readAllBytes(Paths.get(filePath));
    String encoded = Base64.getEncoder().encodeToString(bytes);
    return "data:audio/mpeg;base64," + encoded;
  }

  public static void main(String[] args) throws Exception {
    System.out.println(toDataUri("input.mp3"));
  }
}
```

Parâmetros de resposta

Non-streaming

```json
{
    "output": {
        "sentence": {
            "begin_time": 760,
            "channel_id": 0,
            "end_time": 3800,
            "sentence_end": true,
            "sentence_id": 1,
            "text": "Hello world, this is Alibaba Speech Lab.",
            "words": [
                {"begin_time": 760, "end_time": 1040, "fixed": true, "punctuation": "", "text": "Hello"},
                {"begin_time": 1040, "end_time": 1360, "fixed": true, "punctuation": ", ", "text": " world"}
            ]
        },
        "text": "Hello world, this is Alibaba Speech Lab."
    },
    "usage": {
        "duration": 4
    },
    "request_id": "40e0734d-096f-9ae3-86c1-a8c013287561"
}
```

Streaming

Quando `X-DashScope-SSE: enable` estiver definido, o servidor transmitirá os resultados usando o protocolo Server-Sent Events (SSE). Cada evento tem o formato:

```plaintext
id:{sequence_number}
event:result
:HTTP_STATUS/200
data:{JSON data}
```

Para cada evento SSE, analise o JSON no arquivo data campo e verifique output.sentence.sentence_end para determinar se a sentença é final. usage está incluído apenas em eventos de final de frase.