安装并配置百炼 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 源(推荐)
将解压后的 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"
直接引用 DLL
直接引用 DLL 时,按目标框架选择 sdk/net8.0/DashScope.dll 或 sdk/net10.0/DashScope.dll。将 DashScope.xml 放在 DLL 同一目录可在 IDE 中查看接口注释。
<ItemGroup>
<Reference Include="DashScope">
<HintPath>/path/to/Bailian.DashScope-1.1.1/sdk/net8.0/DashScope.dll</HintPath>
</Reference>
</ItemGroup>
在解压后的包目录中执行以下命令可校验文件完整性:
shasum -a 256 -c SHA256SUMS.txt
配置连接
公共参数
| 参数 | 类型 | 说明 |
|---|---|---|
|
| API Key;未设置时读取 |
|
| 业务空间 ID,通过 |
|
| 完整接口地址。 |
配置接口地址
设置 WorkspaceId 只添加业务空间请求头,不会修改接口地址。使用业务空间专属域名时,通过 Url 设置完整地址。
实时多模态、实时语音对话和实时音视频翻译通过 WebSocket URL 的 model 查询参数传递模型名,SDK 会自动添加。语音识别、语音合成和音频生成通过请求体传递模型名。
| 能力 | URL |
|---|---|
Qwen-Audio / Fun-ASR-Realtime / CosyVoice / Qwen-Audio-TTS-Next |
|
实时多模态 / 实时语音对话 / 实时音视频翻译 |
|
Qwen-Audio-ASR-Filetrans / Fun-ASR |
|
Qwen-Audio-ASR / Fun-ASR-Flash |
|
Paraformer · 实时语音识别 |
|
Paraformer · 非实时语音识别 |
|
验证安装与配置
在解压包的 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# 客户端 |
|---|---|---|
实时多模态 |
|
|
实时语音识别 |
|
|
实时语音合成 |
|
|
音频生成 |
|
|
实时语音对话 |
|
|
实时音视频翻译 |
|
|
非实时语音识别(异步) |
|
|
非实时语音识别(单次请求) |
|
|
在已编译的示例工程目录中运行以下命令,可查看随包示例程序内置的模型清单。
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。
实时语音对话
对话或翻译应在最后一轮应答结束后调用 FinishAsync(),客户端按模型选择 FinishMode。
非实时语音识别
异步文件转写中,取消本地等待并不会取消服务端任务;如需取消,须在任务排队时调用 CancelTaskAsync(taskId)。
错误码
调用失败时,等待调用结果可能抛出 DashScopeException。实时语音识别和语音合成还可通过 Failed 事件接收连接错误。
使用 ServerErrorCode 和 ServerErrorMessage 排查服务端错误。联系技术支持时,请提供本次调用返回的 TaskId 和 RequestId(如有)。
| 错误码 | DashScopeErrorCode | 说明 |
|---|---|---|
240001 |
| 配置无效。 |
240002 |
| 参数无效或缺少参数。 |
240014 |
| 当前状态不允许该操作。 |
240051 |
| 发送音频失败。 |
240062 |
| 网络或连接错误。 |
240069 |
| 连接已关闭;根据错误消息区分本地取消或对端关闭。 |
240070 |
| 鉴权失败。 |
240072 |
| HTTP 请求发送失败。 |
240073 |
| HTTP 响应体为空。 |
240074 |
| 响应不是合法 JSON,或缺少必需字段。 |
240075 |
| 服务端返回错误,查看服务端错误字段。 |
240080 |
| 服务端返回 |
240091 |
| 建立连接的超时。 |
240092 |
| 等待任务启动事件的超时。 |
240093 |
| 等待任务完成的超时。 |