C# 調用百度語音識別 TTS REST API 處理下行數據完整範例

前言

百度語音識別 REST API 提供了強大的語音轉文字能力，開發者常見的疑問是如何在 C# 中正確處理下行（回傳）數據。本文整理官方文件重點，並提供完整的 C# 呼叫範例，幫助你快速整合。

API 呼叫方式總覽

• 請求方法：POST
• 服務位址：https://vop.baidu.com/server_api
• 音訊格式：支援 pcm、wav、opus、speex、amr、x-flac；採樣率 8k/16k、16bit、單聲道
• 語言選項：中文 (zh)、粵語 (ct)、英文 (en)

兩種上傳模式

1. 隱式發送 (JSON Base64)

將音訊 Base64 編碼後放入 JSON 的 speech 欄位，並指定原始長度 len（單位：位元組）。

Content-Type: application/json
{
  "format": "speex",
  "rate": 8000,
  "channel": 1,
  "token": "your_token",
  "cuid": "mac_address_or_imei",
  "len": 4096,
  "speech": "base64_encoded_audio_data"
}

注意：len 為原始音訊長度，非 Base64 後長度；speech 與 len 綁定，url 與 callback 綁定，二擇一。

2. 顯式發送 (HTTP Body 直傳)

音訊二進位直接放在 HTTP Body，參數以 Query String 傳遞，Header 中標示音訊格式。

Content-Type: audio/amr;rate=8000
Content-Length: [raw_audio_length]

POST https://vop.baidu.com/server_api?lan=zh&cuid=xxx&token=xxx

下行回應格式 (統一 JSON)

成功時 err_no = 0，結果在 result 陣列 (1~5 個候選)，UTF-8 編碼。

{
  "err_no": 0,
  "err_msg": "success.",
  "corpus_no": "15984125203285346378",
  "sn": "481D633F-73BA-726F-49EF-8659ACCC2F3D",
  "result": ["北京天氣"]
}

失敗範例：

{"err_no":2000,"err_msg":"data empty.","sn":null}

常見錯誤碼對照

C# 完整呼叫範例 (隱式發送)

using System;
using System.IO;
using System.Net;
using System.Text;
using Newtonsoft.Json;

public class BaiduAsrClient
{
    private const string ApiUrl = "https://vop.baidu.com/server_api";
    private readonly string _token;
    private readonly string _cuid;

    public BaiduAsrClient(string token, string cuid)
    {
        _token = token;
        _cuid = cuid;
    }

    public string Recognize(byte[] audioData, string format = "pcm", int rate = 16000)
    {
        var requestObj = new
        {
            format = format,
            rate = rate,
            channel = 1,
            cuid = _cuid,
            token = _token,
            len = audioData.Length,
            speech = Convert.ToBase64String(audioData)
        };

        string json = JsonConvert.SerializeObject(requestObj);
        byte[] postData = Encoding.UTF8.GetBytes(json);

        var request = (HttpWebRequest)WebRequest.Create(ApiUrl);
        request.Method = "POST";
        request.ContentType = "application/json";
        request.ContentLength = postData.Length;

        using (var stream = request.GetRequestStream())
        {
            stream.Write(postData, 0, postData.Length);
        }

        using (var response = (HttpWebResponse)request.GetResponse())
        using (var reader = new StreamReader(response.GetResponseStream(), Encoding.UTF8))
        {
            return reader.ReadToEnd(); // JSON 字串，自行反序列化取 result
        }
    }
}

關鍵提醒

1. 確保 token 有效且未過期，定期刷新。
2. cuid 建議使用裝置唯一識別碼 (MAC / IMEI)，長度 ≤ 64 字元。
3. 音訊必須符合格式要求，否則會收到 3300/3301 錯誤。
4. 生產環境建議加入重試機制與日誌記錄 (sn 欄位可用於除錯)。

參考資源

• 百度語音識別 REST API 官方文件
• C# HttpWebRequest 非同步寫法可參考 這篇部落格