# CantoneseTTS.com Developer REST API & Studio VIP MCP 實戰教學 (`v1.1`)

> 專為香港創作者、網店團隊、自動化工程師與 AI Coding Agent 設計嘅地道廣東話配音 API。一次請求同步回傳高音質 `.mp3` 音軌、剪映 CapCut `.srt` 時間軸字幕同網頁 `.vtt` (WebVTT) 字幕，並與網頁配音室共用同一個 PostgreSQL 原子級點數錢包。

* **Base URL**: `https://cantonesetts.com`
* **Interactive Console & Live Key Manager**: `https://cantonesetts.com/zh-HK/developer`
* **OpenAPI 3.1 JSON Spec**: `https://cantonesetts.com/openapi.json`
* **Pricing Reference**: `https://cantonesetts.com/pricing.md`

---

## 1. 三層商業權限與防濫用機制 (3-Tier Access Model)

| 會員等級 | 適用方案 | 網頁工作台 (`/tts`) | REST API (`/api/v1/*`) | MCP Agent Server (`/api/mcp`) | 速率上限 |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **免費試用 (`free_trial`)** | 新註冊送 50 點體驗額 | 可用 | 未開通 (`402 PAYMENT_REQUIRED`) | 未開通 (`402`) | 0 RPM |
| **標準付費 (`paid_rest`)** | 1 萬字按量包 (HK$100) / Lite (HK$88/月) / Creator Pro (HK$198/月) | 可用 | **已解鎖** (`Bearer ctts_live_...`) | 未開通 (`403 STUDIO_VIP_REQUIRED`) | 30 RPM (最多 5 條 Key) |
| **宗師方案 (`studio_vip`)** | Studio VIP 月費 (HK$388/月) / 年費 / 10 萬字 VIP 包 (HK$698) | 可用 (含 3 軌混聲台) | **已解鎖** (含 VIP 獨佔混聲) | **獨佔解鎖** (Claude / Cursor 直駁) | 90 RPM (最多 10 條 Key) |

**計費與自動退點保障**：
* 網頁同 API 共用同一個 PostgreSQL 錢包。標準廣東話聲線連 7 種情緒調校每 1 個中文字扣 5 點（即 10,000 標準字包 = 50,000 點）。
* 每次呼叫 `/api/v1/tts` 會先原子預留點數；萬一上游合成超時或失敗，系統會 **100% 自動退回預扣點數**，絕唔會白扣錢包。

---

## 2. 新手 3 步零門檻 Demo（3 分鐘跑通第一條廣東話 MP3 + 字幕）

### Step 1：喺後台拎你嘅專屬 API Key
1. 登入 `https://cantonesetts.com/zh-HK/developer`（確保帳號已購買任何 HK$100 起按量包或月費方案）。
2. 喺「Developer API 金鑰管理」輸入名稱（例如 `My Reels Bot`），撳 **生成新 API 金鑰**。
3. 即場複製以 `ctts_live_` 開頭嘅完整金鑰（金鑰本體只顯示一次，伺服器只儲存 SHA-256 雜湊值）。

```bash
export CANTONESETTS_API_KEY="ctts_live_貼上你條專屬金鑰"
```

### Step 2：查詢可用香港聲線同錢包餘額

```bash
# 查看所有公開聲線代號 (canto_* / blend_* / 你自己複製嘅 clone_*) 及 7 種情緒
curl -sS https://cantonesetts.com/api/v1/voices \
  -H "Authorization: Bearer $CANTONESETTS_API_KEY" | jq .

# 查看目前共用錢包剩餘點數與可讀標準字數
curl -sS https://cantonesetts.com/api/v1/usage \
  -H "Authorization: Bearer $CANTONESETTS_API_KEY" | jq .
```

### Step 3：一句指令生成地道廣東話 `.mp3` + `.srt` + `.vtt`

```bash
curl -sS -X POST https://cantonesetts.com/api/v1/tts \
  -H "Authorization: Bearer $CANTONESETTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "喂大家好呀！今日限時閃購低至 $198，撳下面條 Link 即刻鎖定優惠啦！",
    "voice_id": "canto_yuki_ig",
    "emotion": "happy",
    "colloquialize": true,
    "speed": 1.05,
    "pitch": 0
  }' | jq .
```

**回傳 JSON 結構範例 (`200 OK`)**：

```json
{
  "ok": true,
  "request_id": "job_8f31c9a20b14",
  "voice_id": "canto_yuki_ig",
  "emotion": "happy",
  "speed": 1.05,
  "pitch": 0,
  "normalized_text": "喂大家好呀！今日限時閃購低至一百九十八蚊，撳下面條 Link 即刻鎖定優惠啦！",
  "audio_url": "https://cantonesetts.com/api/canto/audio/tts_20261115_a1b2c3.mp3",
  "duration_sec": 5.42,
  "srt": "1\n00:00:00,000 --> 00:00:01,450\n喂大家好呀！\n\n2\n00:00:01,450 --> 00:00:05,420\n今日限時閃購低至一百九十八蚊，撳下面條 Link 即刻鎖定優惠啦！\n",
  "vtt": "WEBVTT\n\n1\n00:00:00.000 --> 00:00:01.450\n喂大家好呀！\n\n2\n00:00:01.450 --> 00:00:05.420\n今日限時閃購低至一百九十八蚊，撳下面條 Link 即刻鎖定優惠啦！\n",
  "billable_chars": 36,
  "credits_deducted": 180,
  "credits_remaining": 49820,
  "standard_chars_remaining": 9964
}
```

---

## 3. 常用語言與自動化工具即貼即用範本

### Python 自動出片腳本（自動儲存 `voiceover.mp3` + `subtitles.srt`）

```python
import os
import requests

API_KEY = os.environ["CANTONESETTS_API_KEY"]
BASE_URL = "https://cantonesetts.com"

resp = requests.post(
    f"{BASE_URL}/api/v1/tts",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "text": "好多香港老闆以為拍 Reels 要請人錄音，其實用 API 三秒就搞掂晒旁白同字幕！",
        "voice_id": "blend_boutique_queen",
        "emotion": "surprised",
        "colloquialize": True,
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

mp3_bytes = requests.get(data["audio_url"], timeout=30).content
with open("voiceover.mp3", "wb") as f:
    f.write(mp3_bytes)

with open("subtitles.srt", "w", encoding="utf-8") as f:
    f.write(data["srt"])

print(f"完成！音訊長度 {data['duration_sec']}s，剩餘約 {data['standard_chars_remaining']} 標準字")
```

### TypeScript / Node.js (`fetch`) 範本

```typescript
const apiKey = process.env.CANTONESETTS_API_KEY!;

const res = await fetch("https://cantonesetts.com/api/v1/tts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "呢個星期限定優惠，買滿 $500 即享全港順豐免運費！",
    voice_id: "canto_marcus_host",
    emotion: "happy",
    colloquialize: true,
  }),
});

if (!res.ok) {
  throw new Error(`TTS API failed (${res.status}): ${await res.text()}`);
}

const result = await res.json();
console.log("MP3 URL:", result.audio_url);
console.log("WebVTT Captions:\n", result.vtt);
```

### n8n / Make.com 無代碼自動化設定表 (`HTTP Request` 節點)

| 欄位 | 設定值 |
| :--- | :--- |
| **Method** | `POST` |
| **URL** | `https://cantonesetts.com/api/v1/tts` |
| **Authentication** | Header Auth (`Name`: `Authorization`, `Value`: `Bearer ctts_live_...`) |
| **Body Content Type** | `JSON` |
| **JSON Body** | `{"text": "{{ $json.script }}", "voice_id": "canto_yuki_ig", "emotion": "happy", "colloquialize": true}` |
| **下一步下載 MP3** | 加一個 HTTP Request (`GET`) 讀取 `{{ $json.audio_url }}`，Response Format 揀 `File` 即可傳去 FFmpeg、Google Drive 或 Telegram Bot。 |

---

## 4. 書面語自動轉地道香港口語端點 (`POST /api/v1/script/colloquialize`)

如果上游文案係 ChatGPT 寫出嚟嘅書面語（「這個產品他們今天不買就沒有了，只需 $198」），可以先獨立轉換再審稿，或者直接喺 `/api/v1/tts` 傳 `"colloquialize": true`。

```bash
curl -sS -X POST https://cantonesetts.com/api/v1/script/colloquialize \
  -H "Authorization: Bearer $CANTONESETTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "這個產品他們今天不買就沒有了，只需 $198。"}' | jq .
```

---

## 5. 熱門公開聲線與 7 種情緒速查表

### 7 種情緒參數 (`emotion`)
* `happy`：開心活力（網店促銷、開箱首選）
* `surprised`：驚喜反差（Reels 頭 3 秒留人 Hook 首選）
* `neutral`：自然平穩（新聞財經、企業教學、電話 IVR）
* `angry`：激動張力（痛點質問、短劇衝突位）
* `sad`：感性溫柔（深夜故事、心靈療癒）
* `fearful`：懸疑緊張（奇案解說、都市傳說）
* `disgusted`：無奈吐嘈（港式貼地自嘲、踩雷實測）

### 精選聲線代號 (`voice_id`)
* `canto_yuki_ig`：Yuki 活力 IG 女聲（全部付費方案可用）
* `canto_marcus_host`：Marcus 專業男主持（全部付費方案可用）
* `canto_chloe_anchor`：Chloe 知性女主播（全部付費方案可用）
* `canto_alan_konglish`：Alan 科技潮男 Konglish 中英夾雜（全部付費方案可用）
* `blend_boutique_queen`：Mandy 輕熟女店長混調聲（全部付費方案可用）
* `blend_midnight_mystery`：Victor 深夜奇案講故佬（Studio VIP 獨佔）
* `clone_<你的專屬ID>`：你喺網頁版上傳 10 秒錄音複製嘅個人專屬聲紋（自動出現喺 `GET /api/v1/voices`）

> 呼叫 `GET /api/v1/voices` 可隨時取得完整 30+ 把聲線清單與即時試聽連結。

---

## 6. Studio VIP 獨佔：MCP AI Agent 伺服器接入教學 (`/api/mcp`)

升級至 **Studio VIP**（月費 HK$388 / 年費 / 10 萬字 VIP 按量包 HK$698）後，同一個 `ctts_live_...` 金鑰會自動解鎖 `https://cantonesetts.com/api/mcp`（Streamable HTTP JSON-RPC 2.0）。你可以喺 Claude Code、Cursor 或自建 Agent 入面直接用自然語言講：「幫我將呢篇文轉做香港口語，再用 Yuki 開心語氣出條廣東話 MP3 同 SRT 字幕」。

### Claude Code 一行指令安裝

```bash
claude mcp add --transport http cantonesetts https://cantonesetts.com/api/mcp \
  --header "Authorization: Bearer ctts_live_貼上你條VIP金鑰"
```

### Cursor (`.cursor/mcp.json`) 設定檔

```json
{
  "mcpServers": {
    "cantonesetts": {
      "url": "https://cantonesetts.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ctts_live_貼上你條VIP金鑰"
      }
    }
  }
}
```

**內建 4 個 MCP Tools**：
1. `list_cantonese_voices`：列出可用香港聲線、混聲配方與自訂聲紋。
2. `colloquialize_cantonese_script`：將書面語及港幣銀碼轉成地道香港口語。
3. `synthesize_cantonese_tts`：合成 `.mp3` 音軌 + `.srt` + `.vtt` 字幕並回傳餘額。
4. `get_wallet_usage`：檢查共用 PostgreSQL 錢包點數與方案狀態。

---

## 7. 錯誤代碼對照表 (Error Handling)

| HTTP 狀態碼 | `code` 代碼 | 原因與處理方法 |
| :--- | :--- | :--- |
| `400` | `MISSING_TEXT` / `TEXT_TOO_LONG` / `INVALID_EMOTION` / `UNKNOWN_VOICE_ID` | 檢查 `text`（單次上限 1,200 字）、`emotion` 或先呼叫 `GET /api/v1/voices` 核對 `voice_id`。 |
| `401` | `MISSING_API_KEY` / `INVALID_API_KEY` | Header 漏咗 `Authorization: Bearer ctts_live_...` 或該金鑰已喺後台撤銷。 |
| `402` | `PAYMENT_REQUIRED` / `INSUFFICIENT_CREDITS` | 帳號仍處於免費試用（未曾課金），或錢包點數不足。前往 `/zh-HK/billing` 購買任何方案即刻恢復。 |
| `403` | `STUDIO_VIP_REQUIRED` / `STUDIO_VIP_VOICE_REQUIRED` | 非 Studio VIP 方案嘗試呼叫 `/api/mcp` 或 VIP 獨佔混聲；升級至 Studio VIP 即可解鎖。 |
| `429` | `RATE_LIMIT_EXCEEDED` | 超出每分鐘請求上限（標準 30 RPM / Studio VIP 90 RPM），請稍候 2 至 5 秒重試。 |
| `502` | `SYNTHESIS_TEMP_UNAVAILABLE` | 上游語音引擎短暫繁忙；預扣點數已 **100% 自動原子退回**，可安全重試。 |