voai.ai Dialogue API 詳細使用說明

本頁補充說明 /generate-dialogue API 的進階使用方式，協助您更靈活地進行角色語音配置。

✨ 基本用法回顧

若您僅需一次性定義每段語音的 speaker 與參數，可使用以下格式：

{
  "input": {
     "dialogue": [
      {
        "voai_script_text": "今天的進度會議[:1.5]你準備好了嗎？",
        "voice": {
          "name": "佑希",
          "style": "聊天",
          "version": "Neo"
        },
        "audio_config": {
          "speed": 1,
          "pitch_shift": 0,
          "style_weight": 0,
          "breath_pause": 0
        }
      },
      {
        "voai_script_text": "差不多了，我剛把簡報做完。",
        "voice": {
          "name": "子墨",
          "style": "預設",
          "version": "Classic"
        }
      }
    ]
  }
}

這種方式簡單直觀，適合對話角色不多或設定差異不大的情境。

🌟 進階用法：使用 `preset_speakers`

若角色出現頻繁，或語音參數固定，建議使用 preset_speakers 預先定義角色資料，並在 dialogue 區塊中透過 preset_id 引用，讓結構更清晰、維護更方便。

範例

{
  "input": {
    "preset_speakers": [
      {
        "id": "neo的聊天佑希",
        "voice": {
          "name": "佑希",
          "style": "聊天",
          "version": "Neo"
        },
        "audio_config": {
          "speed": 1,
          "pitch_shift": 0,
          "style_weight": 0,
          "breath_pause": 0
        }
      },
      {
        "id": "預設子墨",
        "voice": {
          "name": "子墨",
          "style": "預設",
          "version": "Classic"
        }
      }
    ],
    "dialogue": [
      {
        "voai_script_text": "網際智慧的聲音，不僅清晰自然，還融入了情感與真實感。",
        "preset_id": "neo的聊天佑希"
      },
      {
        "voai_script_text": "這是真的！我非常認同",
        "preset_id": "預設子墨"
      },
      {
        "voai_script_text": "他們還展現了[:2]先進技術的極致魅力。它是業界的標竿，深受廣大用戶的信賴與推崇，是現代智慧語音技術的代表作。",
        "preset_id": "neo的聊天佑希",
        "audio_config": {
          "speed": 1.5,
          "pitch_shift": 0,
          "style_weight": 0,
          "breath_pause": 0
        }
      }
    ]
  }
}

優點

避免重複撰寫相同角色資料
可統一管理語音參數，減少維護成本
程式碼結構更清晰、邏輯更易追蹤

使用邏輯與參數規則

preset_id、voice、audio_config 可同時存在：

語音設定會優先使用該 dialogue 物件中的 voice，其次才會從對應的 preset_id 取得，如皆未指定將拋出錯誤。
audio_config 優先取當前物件的設定，若無則參考 preset_id 的設定，兩者皆無時將使用系統預設值：

speed: 預設為 1，範圍 [0.5, 1.5]
pitch_shift: 預設為 0，範圍 [-5, 5]
style_weight: 預設為 0，範圍 [0, 1]，僅限 Classic 模型有效
breath_pause: 預設為 0，範圍 [0, 10]

preset_speakers 中 voice 為必填，audio_config 為選填。
preset_id 不應重複，若重複，系統會採用陣列中索引值較大的那筆。

特別說明： 上述範例中的第三段對話，即便 "neo的聊天佑希" 已定義了 audio_config，仍會套用該段對話內部的 audio_config 設定，因為 dialogue 欄位優先權更高。

📌 小提醒

停頓標籤 [:秒數] 支援小數點後一位，最大 5 秒。
為避免自然度下降，建議 任兩標籤之間的字數不少於 20 字。
角色風格請依據 GetSpeaker API 回傳值做選擇。

🎵 輸出格式與採樣率設定

輸出格式 (x-output-format)

支援的格式包含：wav、pcm、mp3。

wav: 標準 WAV 格式，適合大多數應用場景。
mp3: 壓縮格式，檔案較小，適合網路傳輸。
pcm: 原始音頻數據格式。⚠️ 重要：當選擇 pcm 格式時，系統會採用 streaming（邊生成邊傳輸） 模式，可即時接收音頻數據，無需等待完整音檔生成完成。

採樣率 (x-sample-rate)

可選的採樣率參數，用於控制音頻品質。支援的值：8000、16000、32000、44100 或 null（預設為 null，使用系統預設值）。

⚠️ 重要限制：如果對話中有任何角色使用 Neo 版本，採樣率最多只能要求到 32000。超過此值將回傳錯誤。
如果未指定採樣率，系統會根據對話中使用的模型版本自動選擇：
- 如果對話中包含 Classic 版本，預設使用 44100
- 如果對話中僅使用 Neo 版本，預設使用 32000
較高的採樣率（如 44100）提供更好的音質，但檔案較大；較低的採樣率（如 8000）檔案較小，但音質較低。

請求範例

curl --location 'https://connect.voai.ai/TTS/generate-dialogue' \
    --header 'x-output-format: wav' \
    --header 'x-api-key: {your-api-key}' \
    --header 'Content-Type: application/json' \
    --data '{...}'

多角色對話語音 API 詳細使用說明