文字轉語音

把一段文字變成自然的語音。短句直接用「簡易」端點，需要停頓控制或長文本則用「進階」端點。兩者的回應都是音檔位元流本身。

怎麼選

	簡易 `/TTS/Speech`	進階 `/TTS/generate-voice`
請求結構	扁平	分成 input / voice / audio_config
停頓標籤	不支援	支援 `[:秒數]`
適合	單句、短段落	長文本、需要節奏控制

共通設定

輸出格式

用 x-output-format header 指定，預設 wav。

格式	MIME	說明
`wav`	audio/wav	預設，完整生成後才回傳
`mp3`	audio/mpeg	檔案較小，適合網路傳輸
`pcm`	audio/pcm	streaming 邊生成邊傳輸，延遲最低。免費版無法使用

把 pitch_shift 設成非 0 時，無法以 streaming 傳輸，即使指定了 pcm 也會等完整生成。

採樣率

用 x-sample-rate header 指定，可填 8000、16000、 32000、44100。上限依模型而異，超過會回 400：

Classic — 預設 44100
Neo — 預設與上限皆為 32000
Sota+ — 預設與上限皆為 24000

回應 header

成功時除了音檔本身，還會附帶 x-used-quota（本次消耗點數）、 x-sample-rate、x-bit-depth、x-channels。

簡易：單句轉語音

POST /TTS/Speech

Request body

version string 選填預設 Sota+

Classic、Neo 或 Sota+。

text string 必填

要轉成語音的文字，上限 1000 字。

speaker string 必填

配音員名稱，如 佑希。可用清單見配音員與模型。

style string 必填

語音風格，如 預設、聊天。每位配音員支援的風格不同。

speed number 選填預設 1

語速，範圍 [0.5, 1.5]。

pitch_shift number 選填預設 0

音調偏移，範圍 [-5, 5]。非 0 時無法 streaming。

style_weight number 選填預設 0.5

風格強度，範圍 [0, 1]。僅 Classic 支援。

breath_pause number 選填預設 0

句間停頓秒數，範圍 [0, 10]。

curl --location '{{BASE_URL}}/TTS/Speech' \
  --header 'x-api-key: your-api-key' \
  --header 'x-output-format: wav' \
  --header 'Content-Type: application/json' \
  --data '{
    "version": "Sota+",
    "text": "VoAI 絕好聲創的聲音，符合臺灣口音，又自然流暢。",
    "speaker": "佑希",
    "style": "聊天",
    "speed": 1,
    "pitch_shift": 0,
    "style_weight": 0.5,
    "breath_pause": 0
  }' \
  --output output.wav

import requests

resp = requests.post(
    "{{BASE_URL}}/TTS/Speech",
    headers={"x-api-key": "your-api-key", "x-output-format": "wav"},
    json={
        "version": "Sota+",
        "text": "VoAI 絕好聲創的聲音，符合臺灣口音，又自然流暢。",
        "speaker": "佑希",
        "style": "聊天",
        "speed": 1,
    },
    timeout=120,
)
resp.raise_for_status()

with open("output.wav", "wb") as f:
    f.write(resp.content)

print("used quota:", resp.headers.get("x-used-quota"))

import { writeFile } from "node:fs/promises";

const resp = await fetch("{{BASE_URL}}/TTS/Speech", {
  method: "POST",
  headers: {
    "x-api-key": "your-api-key",
    "x-output-format": "wav",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    version: "Sota+",
    text: "VoAI 絕好聲創的聲音，符合臺灣口音，又自然流暢。",
    speaker: "佑希",
    style: "聊天",
  }),
});

if (!resp.ok) throw new Error(await resp.text());
await writeFile("output.wav", Buffer.from(await resp.arrayBuffer()));

進階：停頓標籤與長文本

POST /TTS/generate-voice

請求拆成 input、voice、audio_config 三段。文字內可插入 [:2] 表示停頓 2 秒。

停頓標籤規則

兩個停頓標記之間的文字建議不少於 20 字
標記與開頭／結尾之間的文字建議不少於 20 字
有效位數到小數點後一位
最多 5 秒，超過視為 5 秒

Request body

input.voai_script_text string 必填

帶停頓標籤的文字，上限 1000 字。

voice object 必填

包含 name（配音員）、style（風格）、model（模型版本）。

audio_config object 選填

speed、pitch_shift、style_weight、 breath_pause，範圍與簡易端點相同。未指定則用預設值。

curl --location '{{BASE_URL}}/TTS/generate-voice' \
  --header 'x-api-key: your-api-key' \
  --header 'x-output-format: wav' \
  --header 'Content-Type: application/json' \
  --data '{
    "input": {
      "voai_script_text": "絕好聲創的聲音，不僅清晰自然，還融入了情感與真實感，展現了[:2]先進技術的極致魅力。它是業界的標竿，深受廣大用戶的信賴與推崇，是現代智慧語音技術的代表作。"
    },
    "voice": {
      "name": "佑希",
      "style": "預設",
      "model": "Neo"
    },
    "audio_config": {
      "speed": 1,
      "pitch_shift": 0,
      "style_weight": 0.5,
      "breath_pause": 0
    }
  }' \
  --output output.wav

import requests

resp = requests.post(
    "{{BASE_URL}}/TTS/generate-voice",
    headers={"x-api-key": "your-api-key", "x-output-format": "wav"},
    json={
        "input": {
            "voai_script_text": "絕好聲創的聲音，不僅清晰自然，還融入了情感與真實感，展現了[:2]先進技術的極致魅力。它是業界的標竿，深受廣大用戶的信賴與推崇，是現代智慧語音技術的代表作。"
        },
        "voice": {"name": "佑希", "style": "預設", "model": "Neo"},
        "audio_config": {"speed": 1, "pitch_shift": 0, "style_weight": 0.5, "breath_pause": 0},
    },
    timeout=180,
)
resp.raise_for_status()

with open("output.wav", "wb") as f:
    f.write(resp.content)

錯誤

400 參數不合法、免費版使用 pcm、採樣率超出模型上限，或額度不足

401 未提供或無效的 API Key

529 併發數量已達上限，請退避後重試

500 伺服器內部錯誤