API tạo giọng đọc

1. Lấy khoá API

Đăng nhập trang tài khoản → tab Tài khoản → mục 🔌 Khoá API cho lập trình viên → bấm Tạo khoá mới.

Khoá có dạng tsv_xxxxxxxx… và chỉ hiện đúng một lần — hãy lưu lại ngay. Mỗi tài khoản giữ tối đa 5 khoá; xoá khoá cũ bất cứ lúc nào.

Mọi lệnh gọi đều gửi kèm khoá ở header:

Authorization: Bearer tsv_xxxxxxxx…

Hoặc dùng header x-api-key: tsv_xxxxxxxx… — cái nào cũng được.

2. Tạo giọng đọc — POST /tts

Ví dụ nhanh bằng curl, lưu thẳng ra file MP3:

curl -X POST "https://idnfafxgrbabypfokgve.supabase.co/functions/v1/api/tts" \
  -H "Authorization: Bearer tsv_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"text":"Xin chào, đây là Tân Seven Voice.","voice":"Minh Đức","lang":"vi","response":"binary"}' \
  --output giong.mp3

Các tham số

Kết quả trả về (mặc định JSON)

{
  "audio_base64": "SUQzBAAAAAAA…",
  "format": "mp3",
  "cost": 41,
  "credits": 9764,
  "seconds": 3.85,
  "voice": "Minh Đức"
}

• cost — số ký tự lần gọi này tiêu tốn (đúng bằng độ dài text).
• credits — số ký tự còn lại trong tài khoản sau khi trừ.
• seconds — độ dài audio tạo ra.

Nếu gửi "response":"binary", kết quả là file audio thô; số liệu nằm ở header X-Cost và X-Credits-Remaining.

3. Danh sách giọng — GET /voices

Trả về đủ 68 giọng kèm ngôn ngữ, thể loại, giới tính/vùng miền. Không tốn ký tự, không cần khoá.

curl "https://idnfafxgrbabypfokgve.supabase.co/functions/v1/api/voices"

{
  "total": 68,
  "voices": [
    { "name": "Minh Đức",  "lang": "vi", "genre": "📰 Tin tức",   "info": "Nam · Bắc" },
    { "name": "Ngọc Linh", "lang": "vi", "genre": "📖 Kể chuyện", "info": "Nữ · Bắc" },
    …
  ]
}

4. Xem ký tự còn lại — GET /me

curl "https://idnfafxgrbabypfokgve.supabase.co/functions/v1/api/me" \
  -H "Authorization: Bearer tsv_xxxxxxxx"

{ "credits": 9764, "name": "Tân" }

5. Ví dụ Python

import requests

API  = "https://idnfafxgrbabypfokgve.supabase.co/functions/v1/api"
KEY  = "tsv_xxxxxxxx"          # để trong biến môi trường, đừng viết thẳng vào code

r = requests.post(f"{API}/tts",
    headers={"Authorization": f"Bearer {KEY}"},
    json={
        "text": "Chào mừng bạn đến với kênh của Tân Seven.",
        "voice": "Ngọc Linh",
        "lang": "vi",
        "speed": 1.0,
        "response": "binary",
    }, timeout=300)

r.raise_for_status()
open("giong.mp3", "wb").write(r.content)
print("Còn lại:", r.headers.get("X-Credits-Remaining"), "ký tự")

Văn bản dài

Một lần gọi nhận tối đa 200.000 ký tự, nhưng bài càng dài thì càng lâu và dễ hết thời gian chờ. Cách chạy êm nhất: cắt thành đoạn ~1.000 ký tự, gọi 2–3 đoạn song song rồi ghép file lại — giống hệt cách trang web đang làm.

6. Mã lỗi

7. Tính phí

• 1 ký tự văn bản = 1 ký tự trong tài khoản — API và trang web dùng chung một túi.
• Giọng nhân bản tính phí y như giọng thường.
• /voices và /me miễn phí.