Skip to main content

SDK接入

安裝並設定百煉 C# SDK,依模型系列選擇用戶端,瞭解任務結束、逾時與錯誤處理方式。

開始使用

準備工作

  • 安裝 .NET 8 SDK 或 .NET 10 SDK。
  • 取得 API Key,並設定環境變數 DASHSCOPE_API_KEY。
長期 API Key 應保存在伺服器端,不要寫入對外散佈的桌面、行動或瀏覽器應用程式。保護方式請參閱API Key 防洩漏最佳實務。

安裝 SDK

下載並解壓縮 Bailian.DashScope-1.1.1.zip。 NuGet 套件名稱是 Bailian.DashScope,組件是 DashScope.dll,根命名空間為 DashScope。無須安裝原生程式庫或其他 NuGet 相依套件。
  • 本機 NuGet 來源(建議)
  • 直接參考 DLL
以解壓縮後的 packages/ 目錄作為本機 NuGet 來源。
以下範例使用 .NET 8。如使用 .NET 10,請將命令及路徑中的 net8.0 替換為 net10.0。
dotnet new console --framework net8.0 --name SpeechExample
cd SpeechExample
dotnet add package Bailian.DashScope --version 1.1.1 --source "/path/to/Bailian.DashScope-1.1.1/packages"
在解壓縮後的套件目錄中執行以下命令,可驗證檔案完整性:
shasum -a 256 -c SHA256SUMS.txt

設定連線

公共參數

參數類型說明
ApiKeystring?API Key;未設定時讀取 DASHSCOPE_API_KEY。
WorkspaceIdstring?業務空間 ID,透過 X-DashScope-WorkSpace 請求標頭傳送。
Urlstring完整介面位址。

設定端點網址

設定 WorkspaceId 僅新增業務空間請求標頭,不會修改介面位址。使用業務空間專屬網域時,透過 Url 設定完整位址。 在即時多模態互動、即時語音對話及即時音視訊翻譯中,SDK 會將模型名稱加入 WebSocket URL 的 model 查詢參數。語音辨識、語音合成和音訊產生則透過請求主體傳遞模型名稱。
能力URL
Qwen-Audio / Fun-ASR-Realtime / CosyVoice / Qwen-Audio-TTS-Nextwss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference
即時多模態 / 即時語音對話 / 即時音訊與視訊翻譯wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime
Qwen-Audio-ASR-Filetrans / Fun-ASRhttps://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
Qwen-Audio-ASR / Fun-ASR-Flashhttps://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Paraformer · 即時語音辨識wss://WorkspaceId.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference
Paraformer · 非即時語音辨識https://WorkspaceId.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription

驗證安裝與設定

在解壓縮後的 demo/DashScope.Cli/ 目錄執行以下命令。範例將音訊轉為 16 kHz 單聲道 PCM,再進行即時語音辨識。請將 WorkspaceId 替換為與 API Key 對應的工作空間 ID。
dotnet build -p:TargetFrameworks=net8.0
curl -fL "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav" -o input.wav
ffmpeg -i input.wav -f s16le -ac 1 -ar 16000 input.pcm
dotnet bin/Debug/net8.0/DashScope.Cli.dll asr --audio input.pcm --model qwen-audio-3.1-asr-flash-streaming --url "wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference"

適用範圍與支援模型

此 SDK 是純受控的 .NET 用戶端,負責向百鍊傳送音訊或文字並接收結果,不提供本機擷取、編解碼、喚醒、端側 VAD 或回音消除。
類型支援模型C# 用戶端
即時多模態
  • Qwen-Omni-Realtime:qwen3.8-omni-flash-realtime、qwen3.5-omni-plus-realtime、qwen3.5-omni-plus-realtime-2026-03-15、qwen3.5-omni-flash-realtime、qwen3.5-omni-flash-realtime-2026-03-15、qwen3-omni-flash-realtime-2025-09-15
QwenRealtimeConversation
即時語音辨識
  • Qwen-Audio-ASR-Streaming:qwen-audio-3.1-asr-flash-streaming、qwen-audio-3.0-asr-flash-streaming
  • Qwen-Audio-ASR-Message:qwen-audio-3.1-asr-flash-message
  • Fun-ASR-Realtime:fun-asr-realtime、fun-asr-flash-8k-realtime、fun-asr-realtime-2026-02-28、fun-asr-flash-8k-realtime-2026-01-28
  • Paraformer:paraformer-realtime-v2、paraformer-realtime-8k-v2
FunAsrSpeechTranscriber
即時語音合成
  • Qwen-Audio-TTS:qwen-audio-3.1-tts-flash、qwen-audio-3.1-tts-plus、qwen-audio-3.0-tts-flash、qwen-audio-3.0-tts-plus
  • CosyVoice:cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2
CosyVoiceSpeechSynthesizer
音訊產生
  • Qwen-Audio-TTS-Next:qwen-audio-3.1-tts-next
CosyVoiceSpeechSynthesizer
即時語音對話
  • Qwen-Audio-Realtime:qwen-audio-3.1-realtime-plus、qwen-audio-3.1-realtime-flash、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash
QwenRealtimeConversation
即時音訊與視訊翻譯
  • Qwen-LiveTranslate-Realtime:qwen3.5-livetranslate-flash-realtime、qwen3.5-livetranslate-flash-realtime-2026-05-19、qwen3.8-livetranslate-flash-realtime
QwenLiveTranslator
非即時語音辨識(非同步)
  • Qwen-Audio-ASR-Filetrans:qwen-audio-3.1-asr-flash-filetrans、qwen-audio-3.0-asr-flash-filetrans
  • Fun-ASR:fun-asr
  • Paraformer:paraformer-v2、paraformer-8k-v2
FunAsrFileTranscriber
非即時語音辨識(單次請求)
  • Qwen-Audio-ASR:qwen-audio-3.1-asr-flash、qwen-audio-3.0-asr-flash
  • Fun-ASR-Flash:fun-asr-flash-2026-06-15
FunAsrFlashFileTranscriber
在已編譯的範例專案目錄中執行以下命令,可檢視隨附範例程式內建的模型清單。
dotnet bin/Debug/net8.0/DashScope.Cli.dll models --names-only

注意事項

模型與音色相容性

多個模型系列共用一個用戶端類別時,請明確設定 Model,否則 SDK 會使用該類別的預設模型。SDK 的 ModelRouting 方法會依名稱比對部分模型系列。請以本頁的支援模型表確認適用的用戶端。 更換合成模型時,請一併確認該模型支援所選音色。Qwen-Audio-TTS 與 CosyVoice 共用一個用戶端,但不共用音色清單。選擇音色請參閱Qwen-Audio-TTS音色列表和CosyVoice音色列表。

結束或取消呼叫

  • 即時語音辨識
  • 即時語音對話
  • 非即時語音辨識
即時辨識與雙工合成使用 StopAsync() 等待最終結果。重複呼叫不會再次觸發完成事件。若要捨棄傳輸中的結果,呼叫 CancelAsync() 立即中斷連線;此方法可重複呼叫。在 StopAsync() 等待期間取消,等待中的呼叫會收到 240069;取消後再呼叫 StopAsync() 會收到 240014。未正常結束就直接釋放,會透過 Failed 事件回報 240069。

錯誤碼

呼叫失敗時,等候結果可能會擲出 DashScopeException。即時語音辨識與語音合成也可透過 Failed 事件接收連線錯誤。 可使用 ServerErrorCode 和 ServerErrorMessage 排查伺服器端錯誤。聯絡技術支援時,請提供該次呼叫傳回的 TaskId 與 RequestId(如有)。
錯誤碼DashScopeErrorCode說明
240001ConfigInvalid設定無效。
240002IllegalParam參數無效或缺少參數。
240014StateInvalid目前狀態不允許此操作。
240051UpdateAudioError傳送音訊失敗。
240062NetworkError網路或連線錯誤。
240069SocketClosed連線已關閉;從錯誤訊息區分本機取消或遠端關閉。
240070AuthFailed驗證失敗。
240072HttpSendFailedHTTP 請求傳送失敗。
240073HttpReceiveFailedHTTP 回應本文為空。
240074HttpResponseInvalid回應不是有效的 JSON,或缺少必要欄位。
240075HttpServerError服務端傳回錯誤,請查看服務端錯誤欄位。
240080ServerError伺服器傳回 task-failed,請查看 ServerErrorCode。
240091ConnectionTimeout建立連線的逾時。
240092StartTimeout等待任務啟動事件的逾時。
240093StopTimeout等待任務完成的逾時。