快速開始

從一把 API Key 到第一個音檔，中間只有三步。

1. 準備 API Key

金鑰由 VoAI 依合約發放。取得後放進環境變數，不要寫進版控：

export VOAI_API_KEY="your-api-key"

$env:VOAI_API_KEY = "your-api-key"

金鑰等同帳號額度，絕不要放在前端。 瀏覽器或 App 端請改由自家後端代打，避免金鑰外流被盜刷點數。

2. 先看看有哪些配音員

每位配音員支援的風格與模型版本不同，先查一次可用組合。詳見配音員與模型。

curl --location '{{BASE_URL}}/TTS/GetSpeaker' \
  --header "x-api-key: $VOAI_API_KEY"

3. 生成第一個音檔

挑一位配音員與風格送出請求，回應本身就是音檔位元流，直接寫檔即可。完整參數見文字轉語音。

curl --location '{{BASE_URL}}/TTS/Speech' \
  --header "x-api-key: $VOAI_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 os
import requests

resp = requests.post(
    "{{BASE_URL}}/TTS/Speech",
    headers={
        "x-api-key": os.environ["VOAI_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"))

using System.Net.Http.Json;

var http = new HttpClient();
http.DefaultRequestHeaders.Add("x-api-key", Environment.GetEnvironmentVariable("VOAI_API_KEY"));
http.DefaultRequestHeaders.Add("x-output-format", "wav");

var resp = await http.PostAsJsonAsync("{{BASE_URL}}/TTS/Speech", new
{
    version = "Sota+",
    text = "VoAI 絕好聲創的聲音，符合臺灣口音，又自然流暢。",
    speaker = "佑希",
    style = "聊天",
    speed = 1,
});
resp.EnsureSuccessStatusCode();

await File.WriteAllBytesAsync("output.wav", await resp.Content.ReadAsByteArrayAsync());

讀懂回應的 header

Header	說明
`x-used-quota`	本次消耗的點數
`x-sample-rate`	實際採樣率
`x-bit-depth`	位元深度
`x-channels`	聲道數

錯誤處理

非 2xx 的回應一律是 JSON，格式固定為 { "msg": "錯誤說明" }。

400 參數不合法、超出限制，或額度不足

401 沒帶 x-api-key 或金鑰無效

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

529 代表同時進行中的請求太多，不是伺服器故障。重試策略見帳務與額度。

接下來

文字轉語音

停頓標籤、語速音調微調、streaming 輸出。