Tài liệu API

Hướng dẫn tích hợp SnapVoice API

Mọi thứ bạn cần để tích hợp text-to-speech và voice cloning của SnapVoice vào sản phẩm — xác thực, endpoint, ví dụ code và xử lý lỗi.

Giới thiệu

SnapVoice API là REST API giúp tạo giọng nói tiếng Việt tự nhiên và nhân bản giọng. Mọi request đều qua HTTPS và trả về audio WAV hoặc JSON theo định dạng chuẩn.

Base URL

base url

https://api.snapvoice.ai

Xác thực

Mọi request cần header xi-api-key chứa API key của bạn. Tạo và quản lý key trong trang API Keys của dashboard.

Gửi key trong header của mỗi request:

header

xi-api-key: $SNAPVOICE_API_KEY

Không để lộ API key ở phía trình duyệt. Key chỉ nên dùng ở server.

Tạo API key

Bắt đầu nhanh

Gọi endpoint text-to-speech với voice_id và đoạn văn bản để nhận file audio WAV.

cURL

curl -X POST https://api.snapvoice.ai/v1/text-to-speech/$VOICE_ID \
  -H "xi-api-key: $SNAPVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Xin chào từ SnapVoice",
    "model_id": "snapvoice_vi_v1"
  }' \
  --output speech.wav

Danh sách endpoint

Tất cả endpoint nằm dưới tiền tố /v1. Endpoint cần xác thực được đánh dấu xi-api-key.

Method	Endpoint	Xác thực	Mô tả
GET	/v1/models	—	List available TTS models.
GET	/v1/voices	—	List voices (premade + your cloned voices when a key is sent).
GET	/v1/voices/{voice_id}	—	Get a single voice and its settings.
POST	/v1/text-to-speech/{voice_id}	xi-api-key	Generate speech from text. Returns audio/wav.
POST	/v1/voices/add	xi-api-key	Register a cloned voice.
GET	/v1/history	xi-api-key	List your past generations.
GET	/v1/user/subscription	xi-api-key	Get your character quota and usage.

GET/v1/models

List available TTS models.

Request

request

curl https://api.snapvoice.ai/v1/models

Response

response

{
  "status": "success",
  "message": "OK",
  "data": [
    {
      "model_id": "snapvoice_vi_v1",
      "name": "SnapVoice Vietnamese v1",
      "languages": [{ "language_id": "vi", "name": "Vietnamese" }],
      "can_do_tts": true,
      "can_clone": true
    }
  ]
}

GET/v1/voices

List voices (premade + your cloned voices when a key is sent).

Request

request

curl https://api.snapvoice.ai/v1/voices \
  -H "xi-api-key: $SNAPVOICE_API_KEY"

Response

response

{
  "status": "success",
  "data": {
    "voices": [
      {
        "voice_id": "0b1c…",
        "name": "SnapVoice Default",
        "category": "premade",
        "language": "vi",
        "settings": { "stability": 0.5, "similarity_boost": 0.75 }
      }
    ]
  }
}

POST/v1/text-to-speech/{voice_id}

Generate speech from text. Returns audio/wav.

Request

request

curl -X POST https://api.snapvoice.ai/v1/text-to-speech/{voice_id} \
  -H "xi-api-key: $SNAPVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Xin chào từ SnapVoice","model_id":"snapvoice_vi_v1"}' \
  --output speech.wav

Response

response

# Binary audio/wav (24 kHz mono 16-bit) is written to speech.wav.
# On error a JSON body is returned instead:
{ "status": "error", "message": "Character quota exceeded", "data": null }

GET/v1/user/subscription

Get your character quota and usage.

Request

request

curl https://api.snapvoice.ai/v1/user/subscription \
  -H "xi-api-key: $SNAPVOICE_API_KEY"

Response

response

{
  "status": "success",
  "data": {
    "tier": "free",
    "character_count": 1280,
    "character_limit": 10000
  }
}

Tùy chỉnh giọng

Mỗi voice có các tham số điều chỉnh chất lượng và phong cách giọng đọc:

Tham số	Kiểu	Khoảng	Mô tả
stability	number	0.0 – 1.0	Higher = more consistent/monotone; lower = more expressive but variable.
similarity_boost	number	0.0 – 1.0	How closely the output matches the reference voice.
style	number	0.0 – 1.0	Exaggerates the speaking style of the voice.
use_speaker_boost	boolean	true / false	Boosts similarity to the original speaker at a small latency cost.

Xử lý lỗi

API dùng mã trạng thái HTTP chuẩn. Body lỗi luôn có dạng { status: "error", message }.

Mã	Ý nghĩa
400	Bad request — missing or invalid parameters (e.g. empty text).
401	Missing or invalid xi-api-key.
403	Forbidden — the key cannot access this resource.
404	Resource not found (e.g. unknown voice_id).
429	Rate limit hit or character quota exceeded.
502	Upstream synthesis error — retry with backoff.