Tradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗

Qwen-Audio-3.0-Realtime conversa por voz em tempo real Android SDK

Use o Android SDK para Qwen-Audio-3.0-Realtime para construir conversas de voz em tempo real com entrada de áudio e saída de áudio ou texto.

Guia do usuário: Para apresentações de modelos e conselhos de seleção, consulte Conversa por voz em tempo real.

Início rápido

Obtenha e configure uma chave API.
Baixe o SDK e execute o código de exemplo:
- Baixe o pacote SDK mais recente.
- Extraia o pacote ZIP. Obtenha o SDK do AAR em app/libs e adicione-o às dependências do seu projeto. Para integração com Android C++, use android_libs e android_include no pacote ZIP para obter as bibliotecas dinâmicas e arquivos de cabeçalho.
- Abra o projeto no Android Studio. O código de exemplo está em DashQwenAudioChatActivity.java. Substitua a chave API para testar o recurso.

Procedimento de chamada

Inicialize o SDK.
Defina parâmetros para seu caso de uso. Use o parameters argumento de inicializar para definir os parâmetros de conexão e controle e use setParams para definir os parâmetros de conversação por voz.
Chame startDialog para iniciar a conversa.
Em onNuiAudioStateChanged, inicie o dispositivo de gravação com base no estado do áudio.
Forneça continuamente dados de gravação em onNuiNeedAudioData ou ligue para updateAudio para enviar ativamente dados de gravação.
Receba continuamente o áudio retornado pelo modelo em onNuiAssistEventCallback.
Ouça eventos e obtenha informações sobre eventos em onNuiEventCallback.
Chame stopDialog para interromper a conversa e ouvir EVENT_TRANSCRIBER_COMPLETE para confirmar que terminou.
Quando o recurso de conversa não for mais necessário, ligue para release para liberar os recursos do SDK.

Parâmetros de solicitação

Parâmetros de conexão e controle

Passe uma string JSON no parameters argumento de inicializar.

Exemplo: A sequência JSON a seguir não lista todos os parâmetros. Adicione parâmetros conforme necessário para seu caso de uso.

{
  "url": "wss://maas.qwencloudapi.com/api-ws/v1/realtime?model=<model_name>",
  "apikey": "st-****",
  "device_id": "my_device_id",
  "service_mode": "1"
}

Parâmetros

<col style={{ width: "20%" }} />

<col style={{ width: "20%" }} />

<col style={{ width: "40%" }} />

</colgroup>

<thead> <tr> <th> Parâmetro </th>

  <th>
    **Tipo**
  </th>

  <th>
    **Obrigatório**
  </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

  <td>
    `String`
  </td>

  <td>
    Sim
  </td>

  <td>
    Ponto final do serviço: `wss://maas.qwencloudapi.com/api-ws/v1/realtime?model=<model_name>`.
  </td>
</tr>

<tr>
  <td>
    `apikey`
  </td>

  <td>
    `String`
  </td>

  <td>
    Sim
  </td>

  <td>
    Chave de API.
  </td>
</tr>

<tr>
  <td>
    `service_mode`
  </td>

  <td>
    `String`
  </td>

  <td>
    Sim
  </td>

  <td>
    Modo de tempo de execução. Defina este parâmetro como `"1"` para conversação por voz em tempo real.
  </td>
</tr>

<tr>
  <td>
    `device_id`
  </td>

  <td>
    `String`
  </td>

  <td>
    Sim
  </td>

  <td>
    Uma string exclusiva que identifica o usuário final. Você pode usar um ID de usuário no aplicativo ou um identificador de dispositivo gerado pelo cliente. Esse ID é usado principalmente para rastreamento de log e solução de problemas.
  </td>
</tr>

<tr>
  <td>
    `audio_update_manually`
  </td>

  <td>
    `String`
  </td>

  <td>
    Não
  </td>

  <td>
    Se deve enviar ativamente dados de áudio. Padrão: `"false"`. Se definido para `"true"` e o SDK oferece suporte a recursos de áudio no dispositivo, como AEC e VAD, esses recursos são habilitados por padrão.
  </td>
</tr>

<tr>
  <td>
    `workspace`
  </td>

  <td>
    `String`
  </td>

  <td>
    Não
  </td>

  <td>
    O caminho de armazenamento para arquivos de recursos no dispositivo. Este parâmetro é necessário quando `audio_update_manually` é `"true"` e um recurso de áudio no dispositivo, como AEC ou VAD, está ativado.
  </td>
</tr>

<tr>
  <td>
    `debug_path`
  </td>

  <td>
    `String`
  </td>

  <td>
    Não
  </td>

  <td>
    O caminho de armazenamento do arquivo de log. Este parâmetro entra em vigor somente quando `save_log` é `true` em `initialize`. Neste caso, o caminho é obrigatório. O SDK retém no máximo dois arquivos de log localmente.
  </td>
</tr>

<tr>
  <td>
    `save_wav`
  </td>

  <td>
    `String`
  </td>

  <td>
    Não
  </td>

  <td>
    Se deseja salvar o áudio de depuração em `debug_path`. Padrão: `"false"`. Os valores válidos são `"true"` e `"false"`. Este parâmetro entra em vigor somente quando `save_log` é `true`e `debug_path` também deve ser definido.
  </td>
</tr>

<tr>
  <td>
    `max_log_file_size`
  </td>

  <td>
    `int`
  </td>

  <td>
    Não
  </td>

  <td>
    O tamanho máximo do arquivo de log em bytes. Este parâmetro entra em vigor somente quando `save_log` é `true`. Padrão: `104857600` (100 × 1024 × 1024 bytes ou 100 MiB).
  </td>
</tr>

<tr>
  <td>
    `log_track_level`
  </td>

  <td>
    `int`
  </td>

  <td>
    Não
  </td>

  <td>
    O nível de filtro para logs enviados por meio `onNuiLogTrackCallback`. Padrão: `2`. Valores válidos: `0` (VERBOSO), `1` (DEBUGAR), `2` (INFORMAÇÕES), `3` (AVISO), `4` (ERRO) e `5` (NENHUMA). Um log é retornado somente quando seu nível é maior ou igual a ambos `log_track_level` e o `level` passou para `initialize`. Por exemplo, se `log_track_level` é `2` (INFORMAÇÕES) e `level` é `3` (WARNING), apenas WARNING e logs de nível superior (valores maiores ou iguais a `3`) são retornados.
  </td>
</tr>

<tr>
  <td>
    `aec_params`
  </td>

  <td>
    `object`
  </td>

  <td>
    Não
  </td>

  <td>
    Configuração AEC avançada no dispositivo. Este objeto entra em vigor somente quando `audio_update_manually` é `"true"`.
  </td>
</tr>

<tr>
  <td>
    `aec_params.enable_aec`
  </td>

  <td>
    `boolean`
  </td>

  <td>
    Não
  </td>

  <td>
    Se deve ativar o AEC no dispositivo. Se `audio_update_manually` é `"true"` e o SDK oferece suporte a AEC no dispositivo, o AEC é habilitado por padrão.
  </td>
</tr>

<tr>
  <td>
    `aec_params.save_audio`
  </td>

  <td>
    `boolean`
  </td>

  <td>
    Não
  </td>

  <td>
    Se deseja salvar o áudio processado pelo módulo AEC no dispositivo. Se `save_wav` é `"true"` e `debug_path` estiver definido, esse recurso será ativado por padrão e o áudio será salvo em `debug_path`.
  </td>
</tr>

<tr>
  <td>
    `aec_params.enable_aec_data_callback`
  </td>

  <td>
    `boolean`
  </td>

  <td>
    Não
  </td>

  <td>
    Se deve retornar áudio processado por AEC através `EVENT_AEC_DATA` em `onNuiAssistEventCallback`. Padrão: `false`.
  </td>
</tr>

<tr>
  <td>
    `vad_params`
  </td>

  <td>
    `object`
  </td>

  <td>
    Não
  </td>

  <td>
    Configuração avançada de VAD no dispositivo. Este objeto entra em vigor somente quando `audio_update_manually` é `"true"`.
  </td>
</tr>

<tr>
  <td>
    `vad_params.enable_vad`
  </td>

  <td>
    `boolean`
  </td>

  <td>
    Não
  </td>

  <td>
    Se deve ativar o VAD no dispositivo. Se `audio_update_manually` é `"true"` e o SDK oferece suporte ao VAD no dispositivo, o VAD é habilitado por padrão.
  </td>
</tr>

<tr>
  <td>
    `vad_params.save_audio`
  </td>

  <td>
    `boolean`
  </td>

  <td>
    Não
  </td>

  <td>
    Se deseja salvar o áudio processado pelo módulo VAD no dispositivo. Se `save_wav` é `"true"` e `debug_path` estiver definido, esse recurso será ativado por padrão e o áudio será salvo em `debug_path`.
  </td>
</tr>

</tbody> </table>

Parâmetros de conversação por voz

Passe uma string JSON no params argumento de setParams.

Exemplo: A sequência JSON a seguir não lista todos os parâmetros. Adicione parâmetros conforme necessário para seu caso de uso.

{
  "service_type": 4,
  "nls_config": {
    "model": "qwen-audio-3.1-realtime-plus",
    "sr_format": "pcm"
  }
}

Parâmetros

<col style={{ width: "20%" }} />

<col style={{ width: "20%" }} />

<col style={{ width: "40%" }} />

</colgroup>

<thead> <tr> <th style={{ verticalAlign: "top" }}> Parâmetro de nível superior </th>

  <th style={{ verticalAlign: "top" }}>
    **Tipo**
  </th>

  <th style={{ verticalAlign: "top" }}>
    **Obrigatório**
  </th>

  <th style={{ verticalAlign: "top" }}>
    **Descrição**
  </th>
</tr>

</thead>

<tbody> <tr> <td style={{ verticalAlign: "top" }}> service_type </td>

  <td style={{ verticalAlign: "top" }}>
    `int`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Sim
  </td>

  <td style={{ verticalAlign: "top" }}>
    Tipo de serviço de voz. Defina este parâmetro como `4` para conversação por voz em tempo real.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `object`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Sim
  </td>

  <td style={{ verticalAlign: "top" }}>
    Configuração central de conversação por voz, incluindo seleção de modelo e comportamento de conversação.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.model`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `string`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Sim
  </td>

  <td style={{ verticalAlign: "top" }}>
    Nome do modelo. Suporta o `qwen-audio-3.1-realtime-plus`, `qwen-audio-3.0-realtime-plus`e `qwen-audio-3.0-realtime-flash` série de modelos.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.sr_format`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `string`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Sim
  </td>

  <td style={{ verticalAlign: "top" }}>
    Formato de áudio de entrada. Somente `pcm` é suportado. O formato padrão é PCM mono de 16 kHz, 16 bits.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.modalities`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `string`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Uma string contendo uma matriz de modalidades de saída. Valores válidos:<ul><li><code>\["texto"]</code>: retorna apenas texto.</li><li><code>\["áudio", "texto"]</code> (padrão): retorna áudio e texto.</li></ul>
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.voice`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `string`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Voz TTS. O padrão é `longanqian_v3.1` para 3.1 Plus e `longanqian` para 3.0 Plus/Flash. Este parâmetro pode ser definido apenas no primeiro `session.update`; valores posteriores são ignorados. Vozes do sistema: `longanqian`, `longanlingxin`, `longanlingxi`, `longanxiaoxin`e `longanlufeng`. Você também pode especificar um clone `voice_id` criado por meio da API de clonagem de voz. Consulte [Configuração de voz](/developer-guides/speech/qwen-audio-realtime#voice-configuration).

    3.1 Plus também suporta `longanqian_v3.1`, `longanhuan_v3.1`, `longanlingxin_v3.1`, `longanfengyue_v3.1`, `xunanchuan_v3.1`, `beth_v3.1`, `betty_v3.1`, `cally_v3.1`.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.enable_speech_emotion`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `boolean`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Seja para permitir uma expressão emocional aprimorada. Quando ativada, a voz de resposta apresenta variação emocional mais perceptível. Padrão: `true`. Valores válidos: `true` e `false`.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.instructions`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `string`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Instruções do sistema que definem a função do modelo, o estilo de resposta e as preferências comportamentais para toda a sessão.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.max_history_turns`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `int`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Número máximo de turnos históricos de perguntas e respostas permitidos em uma solicitação. Valores válidos: 1 a 50. Padrão: `20`.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.tools`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `string`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Uma string contendo uma matriz de definições de ferramentas de chamada de função. Depois de configurar esse parâmetro, o modelo decide se chamará uma ferramenta com base na entrada do usuário. Cada definição usa `type` (necessário e fixado para `function`) e um `function` objeto contendo `name` (obrigatório), `description` (opcional) e `parameters` (opcional). Se uma função não tiver argumentos, omita `parameters`.

Exemplo:

    ```json
    [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Queries weather information for a specified city.",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string",
                "description": "City"
              }
            },
            "required": [
              "city"
            ]
          }
        }
      }
    ]
    ```
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.turn_detection`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `string`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Uma string contendo um objeto JSON para detecção de curva. Se omitido, a sessão usa o modo push-to-talk, no qual o áudio é confirmado e a inferência é acionada manualmente. Se definido, o modo de conversação duplex será ativado.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.turn_detection.type`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `string`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Tipo VAD. `server_vad` (padrão) detecta limites de fala de recursos acústicos e aciona automaticamente a inferência. `smart_turn` combina sinais acústicos e semânticos; sons sem conteúdo semântico, como sons de preenchimento, não iniciam uma curva nem interrompem a reprodução do modelo.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.turn_detection.threshold`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `float`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Sensibilidade do DAV. Este parâmetro se aplica apenas a `server_vad` e não tem efeito `smart_turn`. Valores mais baixos tornam o VAD mais sensível a sons baixos e ruídos de fundo; valores mais altos requerem uma fala mais clara e mais alta. Intervalo válido: `[-1.0, 1.0]`. Padrão: `0.5`.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.turn_detection.silence_duration_ms`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `int`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Duração mínima do silêncio após a fala, em milissegundos, antes que a resposta do modelo seja acionada. Este parâmetro se aplica apenas a `server_vad` e não tem efeito `smart_turn`. Valores mais baixos reduzem a latência, mas podem ser acionados em breves pausas. Intervalo válido: `[200, 6000]`. Padrão: `800`. Recomendado para conversa: `400` para `800`.
  </td>
</tr>

<tr>
  <td style={{ verticalAlign: "top" }}>
    `nls_config.turn_detection.voiceprint_audio_urls`
  </td>

  <td style={{ verticalAlign: "top" }}>
    `string`
  </td>

  <td style={{ verticalAlign: "top" }}>
    Não
  </td>

  <td style={{ verticalAlign: "top" }}>
    Uma string contendo uma matriz de URLs de áudio pré-gravados publicamente acessíveis para o locutor alvo. Este parâmetro se aplica apenas a `smart_turn`. Em conversas duplex, ajuda o modelo a focar no alto-falante alvo e ignorar outros alto-falantes e ruídos de fundo. Até cinco URLs são suportados. O áudio deve ser PCM ou WAV de 16 kHz.
  </td>
</tr>

</tbody> </table>

Principais APIs

NativoNui

inicializar

Inicializa uma instância do SDK de conversação por voz. O SDK é um singleton. Não inicialize mais de uma vez antes de chamar release.

Este método é bloqueado, então chame-o em um thread que não seja da UI.

Assinatura do método

public synchronized int initialize(final INativeNuiCallback callback,
                                   String parameters,
                                   final Constants.LogLevel level,
                                   final boolean save_log)

Parâmetros

<table><colgroup><col style={{ width: "20%" }} /><col style={{ width: "20%" }} /><col style={{ width: "60%" }} /></colgroup><thead><tr><th> Parâmetro </th><th> Tipo </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>retorno de chamada</code> </td><td> <a href="#native-nui-callback">INativeNuiCallback</a> </td><td> A implementação da interface de retorno de chamada de eventos e dados. </td></tr><tr><td> <code>parâmetros</code> </td><td> <code>Corda</code> </td><td> Uma string JSON que contém os parâmetros de autenticação, conexão e depuração. Veja <a href="#connection-and-control-parameters">Parâmetros de conexão e controle</a>. </td></tr><tr><td> <code>nível</code> </td><td> <code>Constantes.LogLevel</code> </td><td> Controla o nível de impressão dos próprios logs do SDK. </td></tr><tr><td> <code>salvar_log</code> </td><td> <code>booleano</code> </td><td> Se deseja salvar logs locais. Se definido para <code>verdade</code>, especifique o caminho através <code>depuração_caminho</code> no <a href="#connection-and-control-parameters">Parâmetros de conexão e controle</a>e, opcionalmente, defina o tamanho do arquivo por meio <code>max_log_arquivo_tamanho</code>. </td></tr></tbody></table>

Valor de retorno

Um código de erro. Consulte Referência do código de erro.

####setParams

Define os Parâmetros de conversação por voz no formato JSON. Chame esse método antes de startDialog.

Assinatura do método

public synchronized int setParams(String params)

Parâmetros

Valor de retorno

Um código de erro. Consulte Referência do código de erro.

startDialog

Inicia a conversa.

Assinatura do método

public synchronized int startDialog(VadMode vad_mode, String dialog_params)

Parâmetros

<col style={{ width: "20%" }} />

<col style={{ width: "60%" }} />

</colgroup>

<thead> <tr> <th> Parâmetro </th>

  <th>
    **Tipo**
  </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

  <td>
    `VadMode`
  </td>

  <td>
    Modo VAD. Corrigido para `VadMode.TYPE_P2T`.
  </td>
</tr>

<tr>
  <td>
    `dialog_params`
  </td>

  <td>
    `String`
  </td>

  <td>
    Se `apikey` nos [parâmetros de conexão e controle](#connection-and-control-parameters) é uma [chave de API temporária](/api-reference/more/generate-a-temporary-api-key), atualize-o aqui depois que ele expirar.

Formato JSON:

    ```json
    {
      "apikey": "st-****"
    }
    ```
  </td>
</tr>

</tbody> </table>

Valor de retorno

Um código de erro. Consulte Referência do código de erro.

stopDialog

Termina a conversa. Depois de chamar esse método, o servidor retorna o resultado final da conversa e encerra a tarefa.

Assinatura do método

public synchronized int stopDialog();

Valor de retorno

Um código de erro. Consulte Referência do código de erro.

cancelarDialog

Termina a conversa imediatamente. Depois de chamar esse método, a tarefa termina imediatamente, sem esperar que o servidor retorne o resultado final da conversa.

Assinatura do método

public synchronized int cancelDialog();

Valor de retorno

Um código de erro. Consulte Referência do código de erro.

atualizaçãoAção

Envia um comando de ação de conversa durante uma interação para atualizar o comportamento do tempo de execução, como o contexto da conversa.

Assinatura do método

public synchronized int updateAction(String params);

Parâmetros

<col style={{ width: "20%" }} />

<col style={{ width: "60%" }} />

</colgroup>

<thead> <tr> <th> Parâmetro </th>

  <th>
    **Tipo**
  </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

<tbody> <tr> <td> params </td>

  <td>
    `String`
  </td>

  <td>
    Uma string JSON usada para atualizar o comportamento do tempo de execução, como o contexto da conversa.
  </td>
</tr>

<tr>
  <td>
    `params.type`
  </td>

  <td>
    `String`
  </td>

  <td>
    Definir como `"action"`.
  </td>
</tr>

<tr>
  <td>
    `params.command`
  </td>

  <td>
    `String`
  </td>

  <td>
    Comando de tempo de execução. Valores válidos:<ul><li><code>função\_chamada</code>: atualiza uma solicitação de chamada de função.</li><li><code>jogar\_iniciar</code>: quando o AEC no dispositivo é usado, notifica o SDK de que a reprodução de áudio foi iniciada.</li><li><code>jogar\_over</code>: quando o AEC no dispositivo é usado, notifica o SDK de que a reprodução de áudio foi encerrada.</li></ul>
  </td>
</tr>

<tr>
  <td>
    `params.context`
  </td>

  <td>
    `String`
  </td>

  <td>
    Atualização de solicitação de chamada de função. Usado quando `command` é `"function_call"`.
  </td>
</tr>

<tr>
  <td>
    `params.context.type`
  </td>

  <td>
    `String`
  </td>

  <td>
    Tipo de evento. Este parâmetro é necessário quando `command` é `"function_call"`. `conversation.item.create` insere um item de conversa para contexto histórico, texto suplementar ou resultado de ferramenta. Depois de enviar `conversation.item.create`, usar `response.create` para desencadear outra inferência.
  </td>
</tr>

<tr>
  <td>
    `params.context.item`
  </td>

  <td>
    `object`
  </td>

  <td>
    Obrigatório quando `params.context.type` é `conversation.item.create`. O item de conversa a ser criado.
  </td>
</tr>

<tr>
  <td>
    `params.context.response`
  </td>

  <td>
    `object`
  </td>

  <td>
    Opcional quando `params.context.type` é `response.create`. Substitui os padrões de sessão para esta inferência. Se omitido, a configuração da sessão atual será usada.
  </td>
</tr>

</tbody> </table>

context.item parâmetros:

<col style={{ width: "20%" }} />

<col style={{ width: "60%" }} />

</colgroup>

<thead> <tr> <th> Parâmetro </th>

  <th>
    **Tipo**
  </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

  <td>
    `String`
  </td>

  <td>
    ID de item de conversa exclusivo opcional. Se omitido, o servidor gera um. Um erro será retornado se o ID especificado já existir.
  </td>
</tr>

<tr>
  <td>
    `type`
  </td>

  <td>
    `String`
  </td>

  <td>
    Tipo de item obrigatório. Valores válidos:<ul><li><code>mensagem</code>: uma mensagem normal.</li><li><code>função\_chamada</code>: uma solicitação de chamada de função. Esse tipo normalmente é gerado pelo servidor. O cliente também pode usá-lo para adicionar contexto histórico.</li><li><code>função\_chamada\_saída</code>: um resultado de execução da ferramenta. Depois de receber um <code>função\_chamada</code>, o cliente executa a ferramenta e usa esse tipo para gravar o resultado.</li></ul>
  </td>
</tr>

<tr>
  <td>
    `role`
  </td>

  <td>
    `String`
  </td>

  <td>
    Obrigatório para `message`. Valores válidos: `system`, `user`e `assistant`.
  </td>
</tr>

<tr>
  <td>
    `content`
  </td>

  <td>
    `array`
  </td>

  <td>
    Obrigatório para `message`. Cada item contém um `type` e o campo de dados associado. `system` suporta `input_text` com `text`; `user` suporta `input_text` com `text` e `input_audio` com codificação Base64 `audio`; `assistant` suporta `output_text` com `text`.
  </td>
</tr>

<tr>
  <td>
    `call_id`
  </td>

  <td>
    `String`
  </td>

  <td>
    Obrigatório para `function_call` e `function_call_output`. O ID exclusivo que associa uma solicitação de chamada de função ao seu resultado.
  </td>
</tr>

<tr>
  <td>
    `name`
  </td>

  <td>
    `String`
  </td>

  <td>
    Obrigatório para `function_call`. O nome da função a ser chamada.
  </td>
</tr>

<tr>
  <td>
    `arguments`
  </td>

  <td>
    `String`
  </td>

  <td>
    Obrigatório para `function_call`. Argumentos de função como uma string JSON.
  </td>
</tr>

<tr>
  <td>
    `output`
  </td>

  <td>
    `String`
  </td>

  <td>
    Obrigatório para `function_call_output`. Resultado da execução da ferramenta como uma string JSON.
  </td>
</tr>

</tbody> </table>

context.response parâmetros:

<col style={{ width: "20%" }} />

<col style={{ width: "60%" }} />

</colgroup>

<thead> <tr> <th> Parâmetro </th>

  <th>
    **Tipo**
  </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

<tbody> <tr> <td> modalities </td>

  <td>
    `array`
  </td>

  <td>
    Modalidades de saída. `["text"]` retorna apenas texto. `["audio", "text"]` (padrão) retorna áudio e texto.
  </td>
</tr>

<tr>
  <td>
    `voice`
  </td>

  <td>
    `string`
  </td>

  <td>
    Substitui a voz TTS para esta inferência.
  </td>
</tr>

</tbody> </table>

Exemplo:

{
  "type": "action",
  "command": "function_call",
  "context": {
    "item": {
      "call_id": "call_xxxx",
      "output": "{\"city\":\"Hangzhou\",\"condition\":\"sunny\",\"temperature\":18}",
      "type": "function_call_output"
    },
    "type": "conversation.item.create"
  }
}

{
  "type": "action",
  "command": "function_call",
  "context": {
    "response": {
      "modalities": ["text", "audio"]
    },
    "type": "response.create"
  }
}

Valor de retorno

Um código de erro. Consulte Referência do código de erro.

atualizaçãoÁudio

Quando <code>áudio_atualizar_manualmente</code> está definido para <code>"verdadeiro"</code>, chame esse método para enviar ativamente os dados de gravação em vez de fornecer os dados por meio <code>onNuiNeedAudioData</code>.

Assinatura do método

public synchronized int updateAudio(byte[] data, int len,
                                    boolean first_pack);

Parâmetros

Valor de retorno

Um código de erro. Consulte Referência do código de erro.

atualizaçãoRefAudio

Quando <code>áudio_atualizar_manualmente</code> está definido para <code>"verdadeiro"</code> e o AEC no dispositivo estiver ativado, chame esse método para enviar o áudio reproduzido pelo player como sinal de referência.

Assinatura do método

public synchronized int updateRefAudio(byte[] data, int len,
                                       boolean first_pack);

Parâmetros

Valor de retorno

Um código de erro. Consulte Referência do código de erro.

lançamento

Libera todos os recursos internos do SDK. Depois de chamar esse método, a instância do SDK fica indisponível. Para usá-lo novamente, você deve reinicializá-lo chamando initialize.

Assinatura do método

public synchronized int release();

Valor de retorno

Um código de erro. Consulte Referência do código de erro.

Obter versão

Obtém as informações da versão atual do SDK.

Assinatura do método

public synchronized String GetVersion();

Valor de retorno

As informações da versão atual do SDK.

INativeNuiCallback: retornos de chamada do ouvinte

onNuiEventCallback: ouça informações do evento

Assinatura do método

void onNuiEventCallback(NuiEvent event, final int resultCode, final int arg2, KwsResult kwsResult, AsrResult asrResult);

Parâmetros

<table><colgroup><col style={{ width: "20%" }} /><col style={{ width: "20%" }} /><col style={{ width: "60%" }} /></colgroup><thead><tr><th> Parâmetro </th><th> Tipo </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>evento</code> </td><td> <a href="#event-types">Evento Nui</a> </td><td> O evento de retorno de chamada. </td></tr><tr><td> <code>código de resultado</code> </td><td> <code>interno</code> </td><td> O <a href="/api-reference/preparation/error-messages">código de erro</a>. Válido quando ocorre o evento EVENT_ASR_ERROR. </td></tr><tr><td> <code>arg2</code> </td><td> <code>interno</code> </td><td> Um parâmetro reservado. </td></tr><tr><td> <code>asrResult</code> </td><td> <code>AsrResult</code> </td><td> O resultado do reconhecimento de fala. </td></tr><tr><td> <code>kwsResult</code> </td><td> <code>KwsResult</code> </td><td> O recurso de despertar por voz. Você não precisa usar este parâmetro. </td></tr></tbody></table>

onNuiAudioStateChanged: ouça o estado do áudio

O SDK usa esse retorno de chamada para notificá-lo quando iniciar ou interromper a gravação.

Assinatura do método

void onNuiAudioStateChanged(AudioState state);

Estados de AudioState

<table><colgroup><col style={{ width: "25%" }} /><col style={{ width: "75%" }} /></colgroup><thead><tr><th> Estado </th><th> Descrição </th></tr></thead><tbody><tr><td> <code>ESTADO_OPEN</code> </td><td> A interação começou. Você pode abrir o dispositivo de gravação e começar a gravar. </td></tr><tr><td> <code>ESTADO_PAUSA</code> </td><td> A interação foi interrompida. Você pode parar de gravar. </td></tr><tr><td> <code>ESTADO_CLOSE</code> </td><td> A instância do SDK foi lançada. Você pode fechar totalmente o dispositivo de gravação. </td></tr></tbody></table>

onNuiNeedAudioData: fornece dados de áudio

Após o início da conversa, esse retorno de chamada é acionado continuamente. Forneça os dados de áudio neste retorno de chamada. Você não precisa usar esse retorno de chamada quando audio_update_manually está definido para "true".

Assinatura do método

int onNuiNeedAudioData(byte[] buffer, int len);

Parâmetros

Valor de retorno

O número de bytes realmente preenchidos.

onNuiAssistEventCallback: receba eventos e dados auxiliares

Este retorno de chamada recebe eventos auxiliares e dados relacionados do SDK.

Assinatura do método

void onNuiAssistEventCallback_(int event, byte[] info, int info_len,
                               byte[] data);

Parâmetros

onNuiLogTrackCallback: escuta logs de rastreamento

Esse retorno de chamada recebe logs internos detalhados do SDK para ajudar na solução de problemas e na depuração.

default void onNuiLogTrackCallback(Constants.LogLevel level, String log)

`NuiEvent`: tipos de eventos

<col style={{ width: "75%" }} />

</colgroup>

<thead> <tr> <th> Evento </th>

  <th>
    **Descrição**
  </th>
</tr>

</thead>

<tbody> <tr> <td> EVENT_TRANSCRIBER_STARTED </td>

  <td>
    A tarefa foi iniciada com sucesso.
  </td>
</tr>

<tr>
  <td>
    `EVENT_VAD_START`
  </td>

  <td>
    Acionado imediatamente após o início da tarefa. Isto não significa que o início da fala tenha sido detectado.
  </td>
</tr>

<tr>
  <td>
    `EVENT_VAD_END`
  </td>

  <td>
    O final da fala foi detectado.
  </td>
</tr>

<tr>
  <td>
    `EVENT_ASR_PARTIAL_RESULT`
  </td>

  <td>
    Um resultado intermediário de reconhecimento de fala.
  </td>
</tr>

<tr>
  <td>
    `EVENT_ASR_ERROR`
  </td>

  <td>
    Ocorreu um erro durante a conversa de voz.
  </td>
</tr>

<tr>
  <td>
    `EVENT_MIC_ERROR`
  </td>

  <td>
    Disparado quando nenhum dado de áudio é recebido por dois segundos consecutivos.
  </td>
</tr>

<tr>
  <td>
    `EVENT_SENTENCE_END`
  </td>

  <td>
    O final de uma frase foi detectado e um resultado de reconhecimento completo foi retornado.
  </td>
</tr>

<tr>
  <td>
    `EVENT_TRANSCRIBER_COMPLETE`
  </td>

  <td>
    A conversa de voz terminou.
  </td>
</tr>

<tr>
  <td>
    `EVENT_AUDIO_TRANSCRIPTION`
  </td>

  <td>
    Um evento incremental de transcrição de texto para saída de áudio. Os segmentos de transcrição são retornados no modo de streaming.
  </td>
</tr>

<tr>
  <td>
    `EVENT_AUDIO_TRANSCRIPTION_COMPLETED`
  </td>

  <td>
    A transcrição para saída de áudio está completa.
  </td>
</tr>

<tr>
  <td>
    `EVENT_OTHER_RESULT`
  </td>

  <td>
    Outras informações de evento, como o resultado de uma chamada de função.
  </td>
</tr>

<tr>
  <td>
    `EVENT_ASR_TTS_START`
  </td>

  <td>
    O modelo começou a retornar áudio TTS.
  </td>
</tr>

<tr>
  <td>
    `EVENT_ASR_TTS_DATA`
  </td>

  <td>
    Áudio TTS retornado pelo modelo.
  </td>
</tr>

<tr>
  <td>
    `EVENT_ASR_TTS_COMPLETE`
  </td>

  <td>
    O modelo terminou de retornar o áudio TTS.
  </td>
</tr>

<tr>
  <td>
    `EVENT_AEC_DATA`
  </td>

  <td>
    Dados de áudio processados pelo AEC.
  </td>
</tr>

</tbody> </table>

Qwen-Audio-3.0-Realtime conversa por voz em tempo real Android SDK

Início rápido

Procedimento de chamada

Parâmetros de solicitação

Parâmetros de conexão e controle

Parâmetros de conversação por voz

Principais APIs

NativoNui

inicializar

startDialog

stopDialog

cancelarDialog

atualizaçãoAção

atualizaçãoÁudio

atualizaçãoRefAudio

lançamento

Obter versão

INativeNuiCallback: retornos de chamada do ouvinte

onNuiEventCallback: ouça informações do evento

onNuiAudioStateChanged: ouça o estado do áudio

onNuiNeedAudioData: fornece dados de áudio

onNuiAssistEventCallback: receba eventos e dados auxiliares

onNuiLogTrackCallback: escuta logs de rastreamento

NuiEvent: tipos de eventos

`NuiEvent`: tipos de eventos