SDK overview
Install and configure the Model Studio C# SDK, select a client for your model family, and handle completion, timeouts, and errors.
Getting started
Prerequisites
- Install the .NET 8 or .NET 10 SDK.
- Get an API key, then set the
DASHSCOPE_API_KEYenvironment variable.
WarningKeep long-lived API keys on your server. Do not embed them in distributed desktop, mobile, or browser applications. For guidance, see Protect your API key.
Install the SDK
Download and extract Bailian.DashScope-1.1.1.zip.
The NuGet package is Bailian.DashScope; the assembly is DashScope.dll and the root namespace is DashScope. The package has no native libraries or transitive NuGet dependencies.
Local NuGet source (recommended)
Use the extracted packages/ directory as a local NuGet source.
NoteThe examples use .NET 8. For .NET 10, replace net8.0 with net10.0 in commands and paths.
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"
Reference the DLL directly
For direct DLL references, select sdk/net8.0/DashScope.dll or sdk/net10.0/DashScope.dll for the target framework. Keep DashScope.xml next to the DLL for IDE documentation.
<ItemGroup>
<Reference Include="DashScope">
<HintPath>/path/to/Bailian.DashScope-1.1.1/sdk/net8.0/DashScope.dll</HintPath>
</Reference>
</ItemGroup>
To verify the download, run this command from the extracted package directory:
shasum -a 256 -c SHA256SUMS.txt
Configure the connection
Common options
| Parameter | Type | Description |
|---|---|---|
|
| API key; falls back to |
|
| Workspace ID, sent in |
|
| Full endpoint URL. |
Configure the endpoint URL
Setting WorkspaceId adds the workspace request header; it does not change the endpoint. Set the complete workspace endpoint in Url.
For real-time multimodal interaction, voice conversation, and audio and video translation, the SDK adds the model name to the WebSocket URL as the model query parameter. For speech recognition, speech synthesis, and audio generation, it sends the model name in the request body.
| Capability | URL |
|---|---|
Real-time speech recognition / Real-time speech synthesis / Audio Generation |
|
Real-time multimodal / Real-time voice conversation / Real-time audio and video translation |
|
Qwen-Audio-ASR-Filetrans / Fun-ASR / Paraformer |
|
Qwen-Audio-ASR / Fun-ASR-Flash |
|
Verify the installation and configuration
Run the following commands in the extracted demo/DashScope.Cli/ directory. The example converts audio to 16 kHz mono PCM and runs real-time speech recognition. Replace WorkspaceId with the workspace ID for your API key.
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.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference"
Supported capabilities and models
Use this managed .NET SDK to send audio or text to Model Studio and receive results. It does not capture or encode audio, detect wake words, or perform local VAD or echo cancellation.
| Type | Supported models | C# client |
|---|---|---|
Real-time multimodal |
|
|
Real-time speech recognition |
|
|
Real-time speech synthesis |
|
|
Real-time speech synthesis |
|
|
Audio Generation |
|
|
Real-time voice conversation |
|
|
Real-time audio and video translation |
|
|
Non-real-time speech recognition (asynchronous) |
|
|
Non-real-time speech recognition (single request) |
|
|
Run the following command in the built demo project directory to list the model IDs included in the demo.
dotnet bin/Debug/net8.0/DashScope.Cli.dll models --names-only
Usage notes
Model and voice compatibility
If several model families share a client class, set Model explicitly. Otherwise, the SDK uses the class default. The SDK’s ModelRouting methods match some model families by name. Use the supported models table on this page to find the client for a model.
When you change a synthesis model, choose a voice supported by that model. Qwen-Audio-TTS and CosyVoice share a client, not a voice list. To select a voice, see Qwen-Audio-TTS voice list and CosyVoice voice list.
Finish or cancel a call
Real-time speech recognition
For realtime recognition and duplex synthesis, await StopAsync() to receive the final results. Calling it again does not raise another completion event. CancelAsync() closes the connection without waiting; it can be called more than once.
If you cancel while StopAsync() is waiting, that pending call fails with 240069. Calling StopAsync() after cancellation fails with 240014. Disposing an unfinished task instead of stopping it reports 240069 through Failed.
Real-time voice conversation
For conversation or translation, finish the session with FinishAsync() after the last response; the client selects the model’s FinishMode.
Non-real-time speech recognition
For asynchronous file transcription, canceling a local wait does not cancel the remote job: use CancelTaskAsync(taskId) while the job is pending.
Sambert
Sambert takes the full text once per instance. Select the speaker with Model, not Voice. After StartAsync(text), await WaitFinishedAsync(); the server ends the task.
Error codes
When a call fails, awaiting its result can throw DashScopeException. For real-time speech recognition and speech synthesis, subscribe to Failed to receive connection errors.
Use ServerErrorCode and ServerErrorMessage to diagnose server errors. When contacting technical support, include the TaskId and RequestId returned by the call, if available.
| Error code | DashScopeErrorCode | Description |
|---|---|---|
240001 |
| Invalid configuration. |
240002 |
| Invalid or missing parameter. |
240014 |
| Operation not allowed in the current state. |
240051 |
| Audio send failure. |
240062 |
| Network or connection error. |
240069 |
| Connection closed; check the message for a local cancellation or remote closure. |
240070 |
| Authentication failure. |
240072 |
| Failed to send the HTTP request. |
240073 |
| The HTTP response body is empty. |
240074 |
| Invalid JSON or a required response field is missing. |
240075 |
| Server returned an error; inspect the server error fields. |
240080 |
| The service reported |
240091 |
| Connection timeout. |
240092 |
| Timeout waiting for the task-start event. |
240093 |
| Timeout waiting for task completion. |