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

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

{
  "object": "list",
  "data": [
    {
      "id": "silverai/silver-tts-pro",
      "tasks": ["basic", "voice_clone", "voice_design"],
      "sample_rate": 24000,
      "voice_count": 19,
      "voices_url": "/v1/tts/voices?model=silverai/silver-tts-pro",
      "voices": [
        {
          "id": "vi_02",
          "name": "Ngọc Hân",
          "language": "vi",
          "category": "conversational",
          "model": "silverai/silver-tts-pro",
          "preview_url": "/v1/tts/voices/vi_02/preview"
        }
      ]
    }
  ]
}

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

{
  "object": "list",
  "data": [
    {
      "id": "vi_02",
      "name": "Ngọc Hân",
      "language": "vi",
      "category": "conversational",
      "use_cases": ["chatbot", "virtual_assistant", "customer_service", "dialogue"],
      "model": "silverai/silver-tts-pro",
      "sample_rate": 24000,
      "preview_url": "/v1/tts/voices/vi_02/preview"
    }
  ]
}

curl --fail-with-body "https://api.snapvoice.ai/v1/tts/voices/vi_02/preview" --output preview.audio

# Binary audio; current previews may be audio/x-wav.
# HEAD returns headers without audio; a valid Range request returns 206.
# An unsatisfiable Range returns 416; an unknown preview returns 404.

curl --fail-with-body --max-time 330 -X POST "https://api.snapvoice.ai/v1/text-to-speech/vi_02" \
  -H "xi-api-key: $SNAPVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Xin chào từ SnapVoice","model_id":"silverai/silver-tts-pro"}' \
  --output speech.wav

# Binary audio/wav (mono 16-bit) is written to speech.wav.
# For MP3, POST to ".../vi_02?output_format=mp3" and save speech.mp3
# (mp3_44100_128 style values are accepted and map to mp3).
# Model IDs come from /v1/tts/models; current models return 24 kHz.
# On error a JSON body is returned instead:
{ "status": "error", "message": "Insufficient credits", "data": null }
# Insufficient credits returns HTTP 402, not 429.
# X-History-Item-Id correlates the audio with generation history.

curl --fail-with-body --no-buffer --max-time 330 -X POST "https://api.snapvoice.ai/v1/text-to-speech/vi_02/stream" \
  -H "xi-api-key: $SNAPVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Xin chào từ SnapVoice","model_id":"silverai/silver-tts-flash"}' \
  | ffplay -f s16le -ar 24000 -ch_layout mono -nodisp -autoexit -

# Raw PCM chunks (mono, 16-bit little-endian) arrive as they are generated.
# Headers: X-Audio-Sample-Rate: 24000, X-Audio-Channels: 1,
#          X-Audio-Sample-Format: s16le, X-History-Item-Id: <id>
# Only output_format=pcm (or pcm_24000) is accepted.
# Credits are charged like a normal request. If the upstream fails mid-stream
# the connection is reset and the credits are refunded.

curl https://api.snapvoice.ai/v1/speech-to-text/languages

{
  "object": "list",
  "data": [
    { "code": "vi", "name": "Vietnamese" },
    { "code": "en", "name": "English" }
  ],
  "credits_per_second": 10,
  "max_duration_seconds": 600,
  "max_file_bytes": 26214400
}

curl --fail-with-body --max-time 330 -X POST "https://api.snapvoice.ai/v1/speech-to-text" \
  -H "xi-api-key: $SNAPVOICE_API_KEY" \
  -F "[email protected]" \
  -F "language=vi"

{
  "transcription_id": "8d1f0c3a-5b7e-4f2a-9c61-2e4b7a9d0f13",
  "text": "Xin chào, hôm nay bạn thế nào?",
  "language_code": "vi",
  "duration_seconds": 3.2,
  "credit_cost": 40
}
# language_code is null when auto-detected. Accepts WAV, MP3, M4A, OGG,
# FLAC and WebM. Too long or unreadable audio returns 400, too large 413,
# insufficient credits 402.

# Build the JSON body from reference.wav (requires jq).
base64 < reference.wav | tr -d '\n' > reference.b64
jq -n --rawfile audio reference.b64 \
  '{name: "My voice", reference_audio: $audio, consent: true}' > body.json

curl --fail-with-body --max-time 330 -X POST "https://api.snapvoice.ai/v1/voice-enrollments" \
  -H "xi-api-key: $SNAPVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

{
  "status": "success",
  "message": "Voice enrolled",
  "data": {
    "enrollment_id": "3f6b1c2e-8d4a-4b7e-9c1f-2a5d6e7f8a90",
    "name": "My voice",
    "language": "vi",
    "status": "ready",
    "reference_audio_duration_sec": 8.4,
    "reference_text": "Transcript of reference.wav (optional)",
    "remove_background_noise": false,
    "preview_url": "https://…signed-url…/preview.wav",
    "created_at": "2026-10-15T05:00:00.000Z"
  }
}
# reference_audio: base64 of a 16-bit PCM WAV file (any sample rate,
# mono or stereo) or raw 24 kHz mono 16-bit PCM. 1–22 seconds.

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

{
  "status": "success",
  "message": "OK",
  "data": {
    "history": [],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 0,
      "total_pages": 1
    }
  }
}

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

{
  "status": "success",
  "message": "OK",
  "data": {
    "tier": "free",
    "character_count": 1280,
    "character_limit": 10000,
    "extra_credits": 0,
    "credits_remaining": 8720
  }
}