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 设置完整地址。 实时多模态、实时语音对话和实时音视频翻译通过 WebSocket URL 的 model 查询参数传递模型名,SDK 会自动添加。语音识别、语音合成和音频生成通过请求体传递模型名。
能力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等待任务完成的超时。