使用 C# SDK 透過 WebSocket 呼叫 Qwen-LiveTranslate-Realtime,將輸入語音即時翻譯成目標語言的文字與音頻。
安裝 SDK
下載 Bailian.DashScope-1.1.0.zip 並解壓。在 C# 項目中使用時,從本地 NuGet 源安裝 SDK。
快速開始
- 取得 API Key 並將 API Key 設定為環境變數
DASHSCOPE_API_KEY。API Key 和業務空間須屬於同一地區。 - 建立 .NET 10 主控台專案並依照上文安裝 SDK。
- 將
input.pcm放在專案目錄。使用 16 kHz、單聲道、16 bit 小端序裸 PCM。若來源檔案是 WAV,請先轉成裸 PCM。
設定新加坡地區的業務空間 WebSocket 位址。將 WorkspaceId 替換為實際的業務空間 ID。各模型適用的地區與位址請參閱 WebSocket 接入。
export DASHSCOPE_REALTIME_URL="wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime"
C# 呼叫範例
以下程式碼會依即時節奏傳送一段裸 PCM 音頻,等待回應結束後,再將音頻寫入 output.pcm。用以下代碼取代 Program.cs。
using DashScope.Qwen;
if (args.Length < 2)
throw new ArgumentException("Usage: <input.pcm> <model> [voice]");
using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(60));
var ct = timeout.Token;
await using var client = new QwenLiveTranslator(new QwenLiveTranslateOptions
{
Model = args[1],
Voice = args.Length > 2 ? args[2] : null,
Url = Environment.GetEnvironmentVariable("DASHSCOPE_REALTIME_URL")
?? throw new InvalidOperationException("Set DASHSCOPE_REALTIME_URL to your workspace WebSocket endpoint."),
Modalities = ["text", "audio"],
SourceLanguage = "zh",
TargetLanguage = "en",
SampleRate = 16000,
});
using var output = File.Create("output.pcm");
var completed = new TaskCompletionSource<string?>(TaskCreationOptions.RunContinuationsAsynchronously);
client.TranslationCompleted += (_, e) => Console.WriteLine(e.Text);
client.TranslatedAudioChunk += (_, e) => output.Write(e.Pcm);
client.ResponseCompleted += (_, e) => completed.TrySetResult(e.Status);
client.ErrorOccurred += (_, e) => completed.TrySetException(
new InvalidOperationException($"{e.ServerErrorCode}: {e.ServerErrorMessage}"));
await client.ConnectAsync(ct);
using var input = File.OpenRead(args[0]);
var frame = new byte[640];
int size;
while ((size = await input.ReadAsync(frame.AsMemory(), ct)) > 0)
{
await client.AppendAudioAsync(frame.AsMemory(0, size), ct);
await Task.Delay(20, ct);
}
Array.Clear(frame);
for (var i = 0; i < 60; i++)
{
await client.AppendAudioAsync(frame, ct);
await Task.Delay(20, ct);
}
await client.FinishAsync(ct);
var status = await completed.Task.WaitAsync(ct);
if (status != "completed" || output.Length == 0)
throw new InvalidOperationException($"Status: {status}, audio bytes: {output.Length}");
將快速開始中的裸 PCM 檔案放入專案目錄,執行。
dotnet run -- input.pcm qwen3.8-livetranslate-flash-realtime Serena
API 參考
使用 DashScope.Qwen.QwenLiveTranslator,建立實例時傳入 QwenLiveTranslateOptions。3.5 與 3.8 的伺服器端設定與事件欄位有差異,詳細內容請以對應模型的客戶端事件 為準。
連接與翻譯選項
| 選項 | 類型 | 預設值 | 說明 |
|---|---|---|---|
ApiKey | string? | null | 百煉 API Key。未設定時讀取 DASHSCOPE_API_KEY。 |
Url | string | wss://dashscope.aliyuncs.com/api-ws/v1/realtime | WebSocket 位址。SDK 會將 Model 拼接至 URL 的 model 查詢參數。 |
WorkspaceId | string? | null | 業務空間 ID。設定後透過 X-DashScope-WorkSpace 請求頭傳遞。使用業務空間專屬網域時,透過 Url 指定完整地址。 |
ConnectTimeout | TimeSpan | 10 s | 建立 WebSocket 連接的逾時時間。 |
StartTimeout | TimeSpan | 10 s | 等待 session.created 的逾時時間。 |
StopTimeout | TimeSpan | 10 s | 等待 session.finished 的逾時時間,適用於等待該事件的收尾方式。 |
FinishMode | QwenRealtimeFinishMode? | null | 留空時按模型選擇收尾方式。可讀取實例的 FinishMode 查看實際取值。 |
Model | string | qwen3.5-livetranslate-flash-realtime | 模型 ID。 |
Modalities | IList<string> | ["text", "audio"] | 輸出模態。僅需譯文時設為 ["text"]。 |
Voice | string? | null | 輸出譯音時使用的音色。未設定時由伺服器端選擇預設值。使用 3.8 且輸出語音時需指定該模型支援的音色。 |
EnableVoiceClone | bool? | null | 聲音復刻開關。 |
VoiceCloneFrequency | string | once | once 在會話開始時複製一次,always 每句複製,never 使用已有的複製音色 ID。請依型號確認可用方式。 |
SampleRate | int | 16000 | 輸入取樣率,單位為 Hz。請選擇模型支援的取樣率。 |
InputAudioFormat | string | pcm | 輸入音訊格式。SDK 選項接受 pcm 或 opus,實際可用格式以模型之客戶端事件參考為準。 |
OutputAudioFormat | string? | null | 輸出音訊格式,例如 pcm。留空時使用服務端預設值。 |
TranscriptionModel | string? | qwen3-asr-flash-realtime | 來源語音辨識模型。使用 qwen3.5-livetranslate-flash-realtime 時,將此項與 SourceLanguage 均設為 null 可省略 input_audio_transcription 設定。3.8 版本的來源語音辨識始終啟用。 |
SourceLanguage | string? | null | 來源語言代碼,例如 zh。留空時由服務端自動偵測。 |
TargetLanguage | string | en | 目標語言代碼,例如 en。 |
SkipSameLanguageText | bool? | null | 當來源語言與目標語言相同時跳過翻譯輸出。請依所用版本確認支援情況。 |
SkipSameLanguageAudio | bool? | null | 當來源語言與目標語言相同時跳過翻譯聲音輸出。請依所用版本確認支援情況。 |
CorpusPhrases | IDictionary<string, string>? | null | 翻譯熱詞,從來源詞映射至目標詞,對應 translation.corpus.phrases。 |
VadThreshold | double? | 0.5 | 服務端 VAD 閾值,取值範圍 -1.0 至 1.0。 |
VadSilenceMs | int | 1000 | 服務端判定語音結束前所需的靜音時長,單位為毫秒。 |
EnableDebugInfo | bool? | null | 請求服務端回傳除錯資訊。 |
使用 3.8 進行音視頻翻譯時,先按WebSocket 接入 將 session.input_modalities 設為 ["audio", "video"],再隨音訊傳送圖片幀。AppendImageAsync 負責傳送圖片幀。配置或傳送 SDK 未封裝的欄位時,可使用 SendRawEventAsync 發送完整的客戶端事件。
方法
除了 DisposeAsync 外,下列方法返回 Task。ct 為可選取消權杖。
| 方法 | 說明 |
|---|---|
ConnectAsync(CancellationToken ct = default) | 建立連接,等待 session.created,然後發送 session.update。 |
AppendAudioAsync(ReadOnlyMemory<byte> pcm, CancellationToken ct = default) | 發送一幀音訊。SDK 將字節編碼為 Base64 並透過 input_audio_buffer.append 發送。 |
AppendImageAsync(string imageBase64, CancellationToken ct = default) | 發送一幀 Base64 圖像,對應 input_image_buffer.append。需使用支援圖片輸入的模型,並提前啟用音訊與圖片輸入。 |
SendRawEventAsync(string frameJson, CancellationToken ct = default) | 原樣發送一條完整的客戶端事件 JSON,可用於 SDK 尚未單獨封裝的事件。 |
FinishAsync(CancellationToken ct = default) | 依照實際 FinishMode 正常結束會話。 |
AbortAsync() | 立即關閉連接,放棄途中的結果。 |
DisposeAsync() | 異步釋放資源,返回 ValueTask。 |
事件
| 事件 | 事件參數 | 觸發條件 |
|---|---|---|
SessionReady | string? | 會話就緒,值為 session.id。 |
SourceTranscriptUpdated | QwenTranscriptEventArgs | 目前的來源語音轉寫。啟用來源語音轉寫後才會回傳。 |
SourceTranscriptCompleted | QwenTranscriptEventArgs | 一句來源語音的最終轉寫。 |
TranslationTextDelta | QwenTextDeltaEventArgs | 翻譯增量。需要最終翻譯時,讀取 TranslationCompleted。 |
TranslationCompleted | QwenTranscriptEventArgs | 本句的完整翻譯。 |
TranslatedAudioChunk | QwenAudioChunkEventArgs | 翻譯音訊片段。音訊格式和取樣率以會話設定和模型實際回傳為準。 |
TranslatedAudioCompleted | EventArgs | 本輪翻譯音訊全部下發。 |
ResponseCompleted | QwenResponseSummary | 收到 response.done,回傳狀態和用量。 |
RawServerEvent | QwenServerEventArgs | 原始服務端事件,可讀取事件類型和 JSON 物件。 |
ErrorOccurred | DashScopeErrorEventArgs | 服務端錯誤或連接異常。 |
事件參數欄位見 C# SDK 結果物件。翻譯場景的用量為會話累計值。
會話收尾
送出所有音訊後,呼叫 FinishAsync 結束工作階段,讓伺服器傳回剩餘的譯文和翻譯音訊。LiveTranslate 預設使用 FinishAndWait,送出 session.finish 並等待 session.finished。