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 tạo giọng nói đa ngôn ngữ và nhân bản giọng. Danh mục model/voice được đồng bộ trực tiếp từ hệ thống TTS AI; kết quả tổng hợp trả về audio WAV.

Base URL

base url

https://api.snapvoice.ai

Xác thực

Endpoint tạo audio, history và tài khoản cần header xi-api-key. Danh mục model, voice và audio preview được đọc công khai.

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

Lấy provider voice ID từ /v1/tts/voices, sau đó gọi text-to-speech với voice_id, model_id và văn bản để nhận 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": "silver-tts"
  }' \
  --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/tts/models	—	List live TTS models from the synthesis provider.
GET	/v1/tts/voices	—	List live built-in voices. Filter by model, language, or category.
GET	/v1/tts/voices/{voice_id}/preview?model={model_id}	—	Stream an MP3 voice preview. Supports HEAD and Range requests.
POST	/v1/text-to-speech/{voice_id}	xi-api-key	Generate speech from text. Returns audio/wav.
GET	/v1/history?page=1&page_size=20	xi-api-key	List generation history, paginated at 20 items per page by default.
GET	/v1/user/subscription	xi-api-key	Get your character quota and usage.

GET/v1/tts/models

List live TTS models from the synthesis provider.

Request

request

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

Response

response

{
  "object": "list",
  "data": [
    {
      "id": "silver-tts",
      "tasks": ["basic", "voice_clone", "voice_design"],
      "sample_rate": 24000,
      "voice_count": 15,
      "voices_url": "/v1/tts/voices?model=silver-tts",
      "voices": [
        {
          "id": "vi_01",
          "name": "Mai Trinh",
          "language": "vi",
          "category": "conversational",
          "model": "silver-tts",
          "preview_url": "/v1/tts/voices/vi_01/preview?model=silver-tts"
        }
      ]
    }
  ]
}

GET/v1/tts/voices

List live built-in voices. Filter by model, language, or category.

Request

request

curl "https://api.snapvoice.ai/v1/tts/voices?model=silver-tts&language=vi"

Response

response

{
  "object": "list",
  "data": [
    {
      "id": "vi_01",
      "name": "Mai Trinh",
      "language": "vi",
      "category": "conversational",
      "use_cases": ["chatbot", "virtual_assistant", "customer_service", "dialogue"],
      "model": "silver-tts",
      "sample_rate": 24000,
      "preview_url": "/v1/tts/voices/vi_01/preview?model=silver-tts"
    }
  ]
}

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":"silver-tts"}' \
  --output speech.wav

Response

response

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

GET/v1/history?page=1&page_size=20

List generation history, paginated at 20 items per page by default.

Request

request

curl "https://api.snapvoice.ai/v1/history?page=1&page_size=20" \
  -H "xi-api-key: $SNAPVOICE_API_KEY"

Response

response

{
  "status": "success",
  "data": {
    "history": [],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 45,
      "total_pages": 3
    }
  }
}

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
  }
}

Model và giọng

Voice tự xác định model sở hữu. voice_id và model_id phải là một cặp hợp lệ từ live catalog:

Tham số	Kiểu	Khoảng	Mô tả
voice_id	path	GET /v1/tts/voices	Provider voice ID, for example vi_01 or vi_female_north.
model_id	string	silver-tts	Vietnamese model with 15 built-in voices and voice cloning.
text	string	1–3000 chars	Text to synthesize. Credits are charged by character count.

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.
503	The TTS model is not ready or the provider is unavailable.