Skip to main content

SDK Java do Qwen-LiveTranslate-Realtime

Este documento descreve como usar o SDK Java do DashScope para chamar o modelo de tradução de áudio e vídeo em tempo real Qwen-LiveTranslate-Realtime.

Para a conexão e a autenticação, consulte Acesso por WebSocket. Para os campos de eventos e exemplos JSON, consulte Eventos do cliente e Eventos do servidor.

Antes de começar

  1. Instale o DashScope SDK versão 2.22.5 ou posterior.
  2. Obtenha uma chave de API.
  3. Defina a chave da API como variável de ambiente:
   # Linux / macOS
   export DASHSCOPE_API_KEY=<your-api-key>
   source ~/.bashrc

   # Windows
   set DASHSCOPE_API_KEY=<your-api-key>
  1. Consulte a Visão geral do modelo Qwen-LiveTranslate para verificar idiomas e vozes compatíveis.
O Alibaba Cloud Model Studio lançou domínios específicos por workspace para as regiões China (Beijing) e Singapore. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade nas solicitações de inferência. Recomendamos migrar para os novos domínios:
  • China (Beijing): de wss://dashscope.aliyuncs.com para wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: de wss://dashscope-intl.aliyuncs.com para wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} é o ID do seu workspace, disponível na página Workspace Details no console do Alibaba Cloud Model Studio. O domínio existente permanece totalmente funcional.

Início rápido

Conecte-se, envie áudio e receba o texto traduzido:
WebSocketwss://WorkspaceId.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime
WebSocketwss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime

import com.alibaba.dashscope.audio.omni.*;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.google.gson.JsonObject;
import java.util.Arrays;

// 1. Build connection parameters
OmniRealtimeParam param = OmniRealtimeParam.builder()
        .model("qwen3.5-livetranslate-flash-realtime")
        .url("wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime")
        .apikey(System.getenv("DASHSCOPE_API_KEY"))
        .build();

// 2. Define a callback to handle server events
OmniRealtimeCallback callback = new OmniRealtimeCallback() {
    @Override public void onOpen() { System.out.println("Connected"); }

    @Override
    public void onEvent(JsonObject message) {
        String type = message.get("type").getAsString();
        if ("response.audio_transcript.done".equals(type)) {
            System.out.println("Translation: " + message.get("transcript").getAsString());
        }
    }

    @Override
    public void onClose(int code, String reason) {
        System.out.println("Closed: " + code + " " + reason);
    }
};

// 3. Open a session and start streaming audio
OmniRealtimeConversation conversation = new OmniRealtimeConversation(param, callback);
conversation.connect();

// 4. Configure translation target language
OmniRealtimeConfig config = OmniRealtimeConfig.builder()
        .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
        .translationConfig(OmniRealtimeTranslationParam.builder()
                .language("en")
                .build())
        .build();
conversation.updateSession(config);

// 5. Send Base64-encoded audio chunks (PCM 16 kHz, 16-bit, mono)
conversation.appendAudio(audioBase64);

// 6. End the session when done
conversation.endSession();

Parâmetros da solicitação

OmniRealtimeParam

Use OmniRealtimeParam.builder() para definir estes parâmetros e estabelecer a conexão WebSocket.
OmniRealtimeParam param = OmniRealtimeParam.builder()
        .model("qwen3.5-livetranslate-flash-realtime")
        .url("wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime")
        // API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
        // If an environment variable is not configured, replace the next line with your Model Studio API key: .apikey("sk-xxx")
        .apikey(System.getenv("DASHSCOPE_API_KEY"))
        .build();

Parâmetro

Tipo

Obrigatório

Descrição

model

String

Sim

Nome do modelo. Recomendamos qwen3.5-livetranslate-flash-realtime.

url

String

Sim

Endpoint WebSocket. Use wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime (China (Beijing)) ou wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime (Singapore).

Substitua {WorkspaceId} pelo seu workspace ID real.

apikey

String

Não

Chave da API para autenticação. Se não estiver definida, configure-a pela variável de ambiente DASHSCOPE_API_KEY.

OmniRealtimeConfig

Defina estas configurações com OmniRealtimeConfig.builder() e chame conversation.updateSession(config) após conectar-se.
// Set custom translation phrases
Map<String, Object> phrases = new HashMap<>();
phrases.put("Inteligencia Artificial", "Artificial Intelligence");
phrases.put("Aprendizaje Automático", "Machine Learning");

OmniRealtimeConfig config = OmniRealtimeConfig.builder()
        .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
        .voice("Cherry")
        .inputAudioFormat(OmniRealtimeAudioFormat.PCM_16000HZ_MONO_16BIT)
        .outputAudioFormat(OmniRealtimeAudioFormat.PCM_24000HZ_MONO_16BIT)
        .InputAudioTranscription("qwen3-asr-flash-realtime")
        .translationConfig(OmniRealtimeTranslationParam.builder()
                .language("en")
                .corpus(OmniRealtimeTranslationParam.Corpus.builder()
                        .phrases(phrases)
                        .build())
                .build())
        .build();

conversation.updateSession(config);

Parâmetro

Tipo

Obrigatório

Descrição

modalities

List<OmniRealtimeModality>

Não

Modalidades de saída. Padrão: [AUDIO, TEXT]. Use [TEXT] para saída apenas em texto.

voice

String

Não

Voz para fala sintetizada. A voz padrão para qwen3.5-livetranslate-flash-realtime é Tina. Consulte supported voices.

inputAudioFormat

OmniRealtimeAudioFormat

Não

Formato do áudio de entrada. Padrão: PCM_16000HZ_MONO_16BIT.

outputAudioFormat

OmniRealtimeAudioFormat

Não

Formato do áudio de saída. Padrão: PCM_24000HZ_MONO_16BIT.

InputAudioTranscription

String

Não

Modelo ASR para transcrever a fala original. Defina como qwen3-asr-flash-realtime para receber a transcrição no idioma de origem junto à tradução.

translationConfig

OmniRealtimeTranslationParam

Não

Configurações de tradução. Consulte OmniRealtimeTranslationParam abaixo.

enableTurnDetection

boolean

Não

Ativa ou desativa o VAD (Detecção de Atividade de Voz).

Valor padrão: true. Ative o modo VAD, em que o servidor detecta automaticamente o início e o fim da fala e aciona a tradução.

Defina como false para alternar para o modo Manual, no qual o cliente envia o áudio manualmente pelo método commit(). Para descrições detalhadas dos parâmetros, consulte a descrição de turn_detection no documento Client events.

Parâmetros extras da sessão Alguns parâmetros de sessão não têm um método de configuração específico no SDK. Passe esses parâmetros por OmniRealtimeConfig.builder().parameters(Map). As entradas do Map são gravadas diretamente em session. Por exemplo, prepare os parâmetros abaixo para ativar a clonagem de voz em tempo real:
Map<String, Object> options = new HashMap<>();
options.put("frequency", "once");

Map<String, Object> parameters = new HashMap<>();
parameters.put("enable_voice_clone", true);
parameters.put("voice_clone_options", options);
Na cadeia do builder da configuração existente, defina .voice("default") e adicione .parameters(parameters). Mantenha as configurações de idioma e áudio e chame conversation.updateSession(config) após construir a configuração. Consulte Clonagem de voz para as combinações de frequência e voz.

OmniRealtimeTranslationParam

Configure o idioma de destino e a terminologia personalizada com OmniRealtimeTranslationParam.builder().
// Set translation phrases
Map<String, Object> phrases = new HashMap<>();
phrases.put("Inteligencia Artificial", "Artificial Intelligence");  // Source language word: Target language translation
phrases.put("Aprendizaje Automático", "Machine Learning");

OmniRealtimeTranslationParam translationParam = OmniRealtimeTranslationParam.builder()
        .language("en")  // Target language code
        .corpus(OmniRealtimeTranslationParam.Corpus.builder()
                .phrases(phrases)
                .build())
        .build();

Parâmetro

Tipo

Obrigatório

Descrição

language

String

Não

Código do idioma de destino. Padrão: en. Consulte os supported languages.

corpus

Corpus

Não

Terminologia personalizada para termos específicos do domínio.

corpus.phrases

Map<String, Object>

Não

Mapeamento de termos: as chaves são termos de origem e os valores são traduções de destino. Exemplo: {"Inteligencia Artificial": "Artificial Intelligence"}

Interfaces principais

OmniRealtimeConversation

Gerencia a conexão WebSocket e o ciclo de vida da transmissão de áudio. Importação: com.alibaba.dashscope.audio.omni.OmniRealtimeConversation

Método

Descrição

OmniRealtimeConversation(OmniRealtimeParam param, OmniRealtimeCallback callback)

Crie uma instância de conversa com parâmetros de conexão e um callback de eventos.

void connect()

Abre a conexão WebSocket. Aciona os eventos session.created e session.updated. Lança NoApiKeyException e InterruptedException.

void updateSession(OmniRealtimeConfig config)

Atualiza a configuração da sessão após a conexão. Aciona o evento session.updated. Defina apenas os parâmetros necessários; valores padrão aplicam-se aos omitidos.

void appendAudio(String audioBase64)

Envia um trecho de áudio codificado em Base64 ao servidor. O servidor detecta automaticamente os limites da fala e inicia a tradução.

void commit()

No modo Manual, confirma o áudio adicionado previamente ao buffer do servidor pelo método appendAudio. Ao receber a confirmação, o servidor começa a gerar a resposta de tradução. No modo VAD, este método é desnecessário, pois o servidor confirma automaticamente. Aciona o evento input_audio_buffer.committed.

void clearAppendedAudio()

Limpa dados de áudio não confirmados do buffer do servidor. Aciona o evento input_audio_buffer.cleared.

void endSession()

Encerra a sessão adequadamente. O servidor conclui a tradução em andamento antes de enviar session.finished. Lança InterruptedException.

void close(int code, String reason)

Interrompe a tarefa e fecha a conexão WebSocket.

String getSessionId()

Retorna o ID da sessão.

String getResponseId()

Retorna o ID da resposta mais recente do servidor.

long getFirstTextDelay()

Retorna a latência do primeiro texto da resposta mais recente (milissegundos).

long getFirstAudioDelay()

Retorna a latência do primeiro áudio da resposta mais recente (milissegundos).

OmniRealtimeCallback

Processa eventos do servidor entregues via WebSocket. Estenda esta classe e implemente cada método para tratar eventos. Importação: com.alibaba.dashscope.audio.omni.OmniRealtimeCallback

Método

Parâmetros

Descrição

void onOpen()

Nenhum

Chamado quando a conexão WebSocket é estabelecida.

abstract void onEvent(JsonObject message)

message: Objeto JSON contendo um server-side event.

Invocado para cada evento do servidor. Analise o campo type para determinar o tipo de evento.

abstract void onClose(int code, String reason)

code: Código de status do WebSocket. reason: Descrição do encerramento.

Chamado quando a conexão WebSocket é fechada.

Tipos comuns de eventos recebidos em onEvent:

Tipo de evento

Descrição

input_audio_buffer.speech_started

Servidor detectou fala no fluxo de áudio.

input_audio_buffer.speech_stopped

Servidor detectou o fim de um segmento de fala.

conversation.item.input_audio_transcription.completed

Transcrição no idioma de origem pronta. Leia message.get("transcript"). Requer InputAudioTranscription definido.

response.audio_transcript.done

Texto traduzido pronto. Leia message.get("transcript").

response.audio.delta

Trecho de áudio traduzido disponível. Leia message.get("delta") para obter dados de áudio em Base64.

error

Erro ocorrido. Leia message.get("error").getAsJsonObject().get("message") para detalhes.

Exemplo completo

Este exemplo captura áudio do microfone, traduz em tempo real e reproduz a fala traduzida no alto-falante do sistema. Funcionamento:
  1. Conecta-se ao Qwen-LiveTranslate via WebSocket.
  2. Configura tradução de espanhol para inglês com terminologia personalizada.
  3. Transmite áudio do microfone em trechos de 100 ms.
  4. Visualize transcrição original e texto traduzido.
  5. Reproduz áudio traduzido no alto-falante.
import com.alibaba.dashscope.audio.omni.*;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.google.gson.JsonObject;

import javax.sound.sampled.*;
import java.util.*;
import java.util.concurrent.atomic.AtomicBoolean;

/**
 * Example of using a microphone with the real-time audio and video translation model.
 */
public class Main {
    private static final int INPUT_CHUNK_SIZE = 3200;   // 100 ms of 16 kHz, 16-bit, mono audio
    private static final int OUTPUT_CHUNK_SIZE = 4800;  // 100 ms of 24 kHz, 16-bit, mono audio
    private static final AtomicBoolean running = new AtomicBoolean(true);
    private static SourceDataLine speaker;  // Speaker

    public static void main(String[] args) throws InterruptedException {
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        if (apiKey == null || apiKey.isEmpty()) {
            System.err.println("Set the DASHSCOPE_API_KEY environment variable.");
            System.exit(1);
        }

        // Create connection parameters.
        OmniRealtimeParam param = OmniRealtimeParam.builder()
                .model("qwen3.5-livetranslate-flash-realtime")
                .url("wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime")
                .apikey(apiKey)
                .build();

        // Create a callback handler.
        OmniRealtimeCallback callback = new OmniRealtimeCallback() {
            @Override
            public void onOpen() {
                System.out.println("[Connection established]");
            }

            @Override
            public void onEvent(JsonObject message) {
                String type = message.get("type").getAsString();
                switch (type) {
                    case "input_audio_buffer.speech_started":
                        System.out.println("====== Speech input detected ======");
                        break;
                    case "input_audio_buffer.speech_stopped":
                        System.out.println("====== Speech input ended ======");
                        break;
                    case "conversation.item.input_audio_transcription.completed":
                        String originalText = message.get("transcript").getAsString();
                        System.out.println("[Original text] " + originalText);
                        break;
                    case "response.audio_transcript.done":
                        String translatedText = message.get("transcript").getAsString();
                        System.out.println("[Translation result] " + translatedText);
                        break;
                    case "response.audio.delta":
                        // Decode and play the translated audio.
                        String audioB64 = message.get("delta").getAsString();
                        byte[] audioBytes = Base64.getDecoder().decode(audioB64);
                        if (speaker != null) {
                            speaker.write(audioBytes, 0, audioBytes.length);
                        }
                        break;
                    case "error":
                        JsonObject error = message.get("error").getAsJsonObject();
                        System.err.println("[Error] " + error.get("message").getAsString());
                        break;
                }
            }

            @Override
            public void onClose(int code, String reason) {
                System.out.println("[Connection closed] code: " + code + ", reason: " + reason);
            }
        };

        // Create a session.
        OmniRealtimeConversation conversation = new OmniRealtimeConversation(param, callback);

        try {
            // Initialize the speaker (for playing the translated speech).
            AudioFormat speakerFormat = new AudioFormat(24000, 16, 1, true, false);
            DataLine.Info speakerInfo = new DataLine.Info(SourceDataLine.class, speakerFormat);
            speaker = (SourceDataLine) AudioSystem.getLine(speakerInfo);
            speaker.open(speakerFormat, OUTPUT_CHUNK_SIZE * 4);
            speaker.start();

            // Initialize the microphone (for capturing speech input).
            AudioFormat micFormat = new AudioFormat(16000, 16, 1, true, false);
            DataLine.Info micInfo = new DataLine.Info(TargetDataLine.class, micFormat);
            if (!AudioSystem.isLineSupported(micInfo)) {
                System.err.println("Microphone is not available.");
                System.exit(1);
            }
            TargetDataLine microphone = (TargetDataLine) AudioSystem.getLine(micInfo);
            microphone.open(micFormat);
            microphone.start();

            // Connect to the server.
            conversation.connect();

            // Configure translation parameters.
            Map<String, Object> phrases = new HashMap<>();
            phrases.put("Inteligencia Artificial", "Artificial Intelligence");
            phrases.put("Aprendizaje Automático", "Machine Learning");

            OmniRealtimeConfig config = OmniRealtimeConfig.builder()
                    .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
                    .voice("Cherry")
                    .inputAudioFormat(OmniRealtimeAudioFormat.PCM_16000HZ_MONO_16BIT)
                    .outputAudioFormat(OmniRealtimeAudioFormat.PCM_24000HZ_MONO_16BIT)
                    .InputAudioTranscription("qwen3-asr-flash-realtime")
                    .translationConfig(OmniRealtimeTranslationParam.builder()
                            .language("en")
                            .corpus(OmniRealtimeTranslationParam.Corpus.builder()
                                    .phrases(phrases)
                                    .build())
                            .build())
                    .build();

            conversation.updateSession(config);

            // Register a shutdown hook.
            Runtime.getRuntime().addShutdownHook(new Thread(() -> {
                System.out.println("\n[Exiting...]");
                running.set(false);
                microphone.stop();
                microphone.close();
                speaker.stop();
                speaker.close();
                try {
                    conversation.endSession();
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                }
                conversation.close(1000, "User stopped");
            }));

            System.out.println("[Starting real-time translation] Speak into the microphone. Press Ctrl+C to exit.");

            // Continuously capture and send microphone audio.
            byte[] buffer = new byte[INPUT_CHUNK_SIZE];
            while (running.get()) {
                int bytesRead = microphone.read(buffer, 0, buffer.length);
                if (bytesRead > 0) {
                    conversation.appendAudio(Base64.getEncoder().encodeToString(buffer));
                }
            }

        } catch (NoApiKeyException e) {
            System.err.println("API Key error: " + e.getMessage());
        } catch (Exception e) {
            System.err.println("An exception occurred: " + e.getMessage());
            e.printStackTrace();
        }
    }
}
Substitua os placeholders pelos seus valores:

Placeholder

Descrição

Exemplo

<your-api-key>

Chave da API do Model Studio

sk-xxxxxxxx

Tópicos relacionados