帳務與額度

所有功能共用同一份點數。這裡說明各功能怎麼計費、怎麼查剩餘額度，以及併發上限怎麼處理。

計費方式

功能	計費單位	費率
文字轉語音（Classic / Neo / Sota+）	字數	1 字 1 點
多角色對話	字數	依各句使用的模型分別計算
虛擬人影像	音檔長度	每秒 200 點（不足一秒以一秒計）

語音生成成功後，回應的 x-used-quota header 會回報本次實際消耗。虛擬人則是在建立任務時預扣，任務失敗會自動退回。

查詢剩餘額度

GET /Key/Usage

回應

data.total integer

可使用的總額度。

data.current integer

剩餘額度。

data.expiration string

API 金鑰的有效期限。

curl --location '{{BASE_URL}}/Key/Usage' \
  --header 'x-api-key: your-api-key'

import requests

resp = requests.get(
    "{{BASE_URL}}/Key/Usage",
    headers={"x-api-key": "your-api-key"},
    timeout=30,
)
resp.raise_for_status()

usage = resp.json()["data"]
print(f"剩餘 {usage['current']} / {usage['total']}，到期日 {usage['expiration']}")

併發上限

每把金鑰同時進行中的生成請求數量有上限。超過時會收到 529 —— 這不是伺服器故障，而是提醒你放慢速度。

建議用指數退避重試（1s、2s、4s…），並在自家服務端就限制同時發出的請求數，不要靠 529 當流量閥。

import time
import requests

def generate(payload, max_retry=5):
    delay = 1
    for attempt in range(max_retry):
        resp = requests.post(
            "{{BASE_URL}}/TTS/Speech",
            headers={"x-api-key": "your-api-key"},
            json=payload,
            timeout=120,
        )

        if resp.status_code != 529:
            resp.raise_for_status()
            return resp.content

        time.sleep(delay)
        delay *= 2

    raise RuntimeError("併發持續額滿，請降低送出速率")

免費版的限制

免費版帳號無法使用 pcm 輸出格式，指定時會直接回 400。若需要 streaming 低延遲輸出，請洽 VoAI 升級方案。

錯誤

401 未提供或無效的 API Key

500 伺服器內部錯誤