Skip to main content

Integração do SDK

Instale e configure o SDK C# do Model Studio, escolha o cliente da família de modelos e saiba como lidar com a conclusão de tarefas, tempos limite e erros.

Primeiros passos

Pré-requisitos

  • Instale o SDK do .NET 8 ou do .NET 10.
  • Obter uma API key e defina a variável de ambiente DASHSCOPE_API_KEY.
Mantenha as chaves de API de longa duração no servidor. Não as inclua em aplicativos de desktop, dispositivos móveis ou navegador que você distribui. Consulte Proteger a chave de API.

Instalar o SDK

Baixe e extraia Bailian.DashScope-1.1.1.zip. O pacote NuGet chama-se Bailian.DashScope, o assembly é DashScope.dll e o namespace raiz é DashScope. Não há dependências nativas ou transitivas do NuGet.
  • Fonte NuGet local (recomendado)
  • Referenciar a DLL diretamente
Use o diretório packages/ extraído como fonte NuGet local.
Os exemplos usam .NET 8. Para .NET 10, substitua net8.0 por net10.0 nos comandos e caminhos.
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"
Para verificar os arquivos, execute este comando no diretório do pacote extraído:
shasum -a 256 -c SHA256SUMS.txt

Configurar a conexão

Parâmetros comuns

ParâmetroTipoDescrição
ApiKeystring?API key; se omitida, lê DASHSCOPE_API_KEY.
WorkspaceIdstring?ID do workspace, enviado em X-DashScope-WorkSpace.
UrlstringURL completo do endpoint.

Configurar a URL do endpoint

WorkspaceId adiciona o cabeçalho do workspace, sem alterar o endpoint. Defina o endpoint completo do workspace em Url. Na interação multimodal, na conversa por voz e na tradução de áudio e vídeo em tempo real, o SDK adiciona o nome do modelo à URL do WebSocket como parâmetro de consulta model. No reconhecimento de fala, na síntese de fala e na geração de áudio, o nome é enviado no corpo da requisição.
RecursoURL
Qwen-Audio / Fun-ASR-Realtime / CosyVoice / Qwen-Audio-TTS-Nextwss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference
Multimodal em tempo real / Conversa por voz em tempo real / Tradução de áudio e vídeo em tempo realwss://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 · Reconhecimento de fala em tempo realwss://WorkspaceId.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference
Paraformer · Reconhecimento de fala não em tempo realhttps://WorkspaceId.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription

Verificar a instalação e a configuração

Execute os comandos no diretório demo/DashScope.Cli/ extraído. O exemplo converte o áudio em PCM mono de 16 kHz para reconhecimento de fala em tempo real. Substitua WorkspaceId pelo ID do workspace da chave de API.
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"

Recursos e modelos compatíveis

Este SDK .NET gerenciado envia áudio ou texto e recebe resultados. Ele não oferece captura, codecs, detecção de palavras de ativação, VAD local ou cancelamento de eco.
TipoModelos compatíveisCliente C#
Multimodal em tempo real
  • 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
Reconhecimento de fala em tempo real
  • 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
Síntese de fala em tempo real
  • 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
Geração de Áudio
  • Qwen-Audio-TTS-Next: qwen-audio-3.1-tts-next
CosyVoiceSpeechSynthesizer
Conversa por voz em tempo real
  • 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
Tradução de áudio e vídeo em tempo real
  • Qwen-LiveTranslate-Realtime: qwen3.5-livetranslate-flash-realtime, qwen3.5-livetranslate-flash-realtime-2026-05-19, qwen3.8-livetranslate-flash-realtime
QwenLiveTranslator
Reconhecimento de fala não em tempo real (assíncrono)
  • 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
Reconhecimento de fala não em tempo real (requisição única)
  • 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
No diretório do projeto de demonstração já compilado, execute o comando a seguir para listar os IDs de modelo incluídos na demonstração.
dotnet bin/Debug/net8.0/DashScope.Cli.dll models --names-only

Observações de uso

Compatibilidade entre modelos e vozes

Se várias famílias de modelos usarem a mesma classe de cliente, defina Model explicitamente. Caso contrário, o SDK usará o modelo padrão da classe. Os métodos ModelRouting do SDK identificam algumas famílias de modelos pelo nome. Para escolher o cliente, consulte a tabela de modelos compatíveis desta página. Ao trocar o modelo de síntese, escolha uma voz compatível com ele. Qwen-Audio-TTS e CosyVoice usam o mesmo cliente, mas não a mesma lista de vozes. Para escolher uma voz, consulte Lista de vozes do Qwen-Audio-TTS e Lista de vozes do CosyVoice.

Concluir ou cancelar uma chamada

  • Reconhecimento de fala em tempo real
  • Conversa por voz em tempo real
  • Reconhecimento de fala não em tempo real
Em reconhecimento em tempo real e síntese duplex, aguarde StopAsync() para receber os resultados finais. Chamadas repetidas não disparam outro evento de conclusão. CancelAsync() encerra a conexão sem esperar e pode ser chamado mais de uma vez.Cancelar durante a espera de StopAsync() faz essa chamada falhar com 240069. Chamar StopAsync() após o cancelamento resulta em 240014. Liberar uma tarefa inacabada gera 240069 no evento Failed.

Códigos de erro

Se uma chamada falhar, aguardar seu resultado pode lançar DashScopeException. No reconhecimento e na síntese de fala em tempo real, o evento Failed também informa erros de conexão. Use ServerErrorCode e ServerErrorMessage para diagnosticar erros do servidor. Ao contatar o suporte técnico, informe o TaskId e o RequestId retornados pela chamada, se disponíveis.
Código de erroDashScopeErrorCodeDescrição
240001ConfigInvalidConfiguração inválida.
240002IllegalParamParâmetro inválido ou ausente.
240014StateInvalidOperação não permitida no estado atual.
240051UpdateAudioErrorFalha no envio de áudio.
240062NetworkErrorErro de rede ou conexão.
240069SocketClosedConexão encerrada; consulte a mensagem para distinguir cancelamento local de fechamento remoto.
240070AuthFailedFalha de autenticação.
240072HttpSendFailedFalha no envio da solicitação HTTP.
240073HttpReceiveFailedO corpo da resposta HTTP está vazio.
240074HttpResponseInvalidJSON inválido ou campo obrigatório ausente.
240075HttpServerErrorO servidor retornou um erro; consulte os campos de erro do servidor.
240080ServerErrorO serviço retornou task-failed. Consulte ServerErrorCode.
240091ConnectionTimeoutTempo limite de conexão.
240092StartTimeoutTempo limite de espera pelo evento de início da tarefa.
240093StopTimeoutTempo limite de espera pela conclusão da tarefa.