安装并配置百炼 C# SDK,按模型系列选择客户端,了解任务收尾、超时和错误处理。
开始使用
准备工作
- 安装 .NET 8 SDK 或 .NET 10 SDK。
- 获取 API Key,并设置环境变量
DASHSCOPE_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。配置连接
公共参数
| 参数 | 类型 | 说明 |
|---|---|---|
ApiKey | string? | API Key;未设置时读取 DASHSCOPE_API_KEY。 |
WorkspaceId | string? | 业务空间 ID,通过 X-DashScope-WorkSpace 请求头发送。 |
Url | string | 完整接口地址。 |
配置接口地址
设置 WorkspaceId 只添加业务空间请求头,不会修改接口地址。使用业务空间专属域名时,通过 Url 设置完整地址。
实时多模态、实时语音对话和实时音视频翻译通过 WebSocket URL 的 model 查询参数传递模型名,SDK 会自动添加。语音识别、语音合成和音频生成通过请求体传递模型名。
| 能力 | URL |
|---|---|
| Qwen-Audio / Fun-ASR-Realtime / CosyVoice / Qwen-Audio-TTS-Next | wss://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-ASR | https://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription |
| Qwen-Audio-ASR / Fun-ASR-Flash | https://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。
适用范围和支持模型
该 SDK 是纯托管的 .NET 客户端,负责向百炼发送音频或文本并接收结果,不提供本地采集、编解码、唤醒、端侧 VAD 或回声消除。
| 类型 | 支持模型 | C# 客户端 |
|---|---|---|
| 实时多模态 |
| QwenRealtimeConversation |
| 实时语音识别 |
| FunAsrSpeechTranscriber |
| 实时语音合成 |
| CosyVoiceSpeechSynthesizer |
| 音频生成 |
| CosyVoiceSpeechSynthesizer |
| 实时语音对话 |
| QwenRealtimeConversation |
| 实时音视频翻译 |
| QwenLiveTranslator |
| 非实时语音识别(异步) |
| FunAsrFileTranscriber |
| 非实时语音识别(单次请求) |
| FunAsrFlashFileTranscriber |
注意事项
模型与音色兼容性
多个模型系列共用一个客户端类时,请显式设置 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 | 说明 |
|---|---|---|
| 240001 | ConfigInvalid | 配置无效。 |
| 240002 | IllegalParam | 参数无效或缺少参数。 |
| 240014 | StateInvalid | 当前状态不允许该操作。 |
| 240051 | UpdateAudioError | 发送音频失败。 |
| 240062 | NetworkError | 网络或连接错误。 |
| 240069 | SocketClosed | 连接已关闭;根据错误消息区分本地取消或对端关闭。 |
| 240070 | AuthFailed | 鉴权失败。 |
| 240072 | HttpSendFailed | HTTP 请求发送失败。 |
| 240073 | HttpReceiveFailed | HTTP 响应体为空。 |
| 240074 | HttpResponseInvalid | 响应不是合法 JSON,或缺少必需字段。 |
| 240075 | HttpServerError | 服务端返回错误,查看服务端错误字段。 |
| 240080 | ServerError | 服务端返回 task-failed,请查看 ServerErrorCode。 |
| 240091 | ConnectionTimeout | 建立连接的超时。 |
| 240092 | StartTimeout | 等待任务启动事件的超时。 |
| 240093 | StopTimeout | 等待任务完成的超时。 |