PUBLIC API · /api/v1

API Reference

Build TTS, speech-to-text, and voice clone into your app. Base URL: https://hvoice.app (also https://xgemini.vn)

Authentication

Send a Bearer token on every request:

Authorization: Bearer hv_live_…

You can also use the JWT from Google sign-in (Studio session). API keys start with hv_live_.

Create a key while signed in: POST /api/v1/account/api-keys (JWT only). The full key is returned once.
List / revoke keys: GET and DELETE /api/v1/account/api-keys/:id (JWT only).
Rate limit theo gói: mini ~40, basic ~60, standard ~90, mặc định 30 request/phút (synthesize/STT/preview).
Job concurrency: mặc định 1 processing/user; khi GPU full job vào queued (FIFO + ưu tiên platinum).
Markup giọng: clone ×1, luxury ×2, premium ×3, platinum ×4 (trừ ký tự).
Fail/timeout: hoàn ký tự đã trừ. Webhook: PUT /api/v1/account/webhook nhận job.completed / job.failed.

Create an API key

curl -X POST https://hvoice.app/api/v1/account/api-keys \
  -H "Authorization: Bearer <studio_jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Default"}'

Response includes key (store it immediately) and key_prefix.

Endpoints

Method	Path	Description
GET	/api/v1/voices	Voice library (library + your clones)
POST	/api/v1/tts/synthesize	Create a TTS job
GET	/api/v1/tts/jobs	List recent jobs (`?limit=`, max 50)
GET	/api/v1/tts/jobs/:jobId	Job status and audio URLs
DELETE	/api/v1/tts/jobs/:jobId	Delete a job
GET	/api/v1/tts/jobs/:jobId/parts.zip	Download part WAVs as zip
GET	/api/v1/tts/jobs/:jobId/transcript.srt	Download SRT transcript
POST	/api/v1/tts/jobs/:jobId/parts/:index/retry	Retry one part; optional `{"text"}`
POST	/api/v1/stt	Speech-to-text (multipart `audio`)
POST	/api/v1/voices/clone	Clone a voice (multipart `audio` + `name`)
POST	/api/v1/voices/transcribe-ref	Transcribe a reference clip
GET	/api/v1/account/usage	Token balance and ledger
GET/PUT	/api/v1/account/webhook	HTTPS webhook URL for job events
GET	/api/v1/account/api-keys	List key prefixes (JWT)
POST	/api/v1/account/api-keys	Create key (JWT)
DELETE	/api/v1/account/api-keys/:id	Revoke key (JWT)

Synthesize

JSON body fields:

Field	Notes
text	Required. Source text (or use `source_srt`).
voice_id	From `GET /voices`.
format	e.g. `mp3`, `wav`.
speed	Playback speed.
language	e.g. `vi`, `en`.
title	Optional job title.
pitch / pitch_semitones	Pitch shift in semitones.
volume / volume_pct	Volume percent.
instruct	Style instruction string.
gender, age, style, accent	Merged into `instruct` if empty.
pause_settings	Pause configuration object.
source_srt	Optional SRT for timed dubbing.

curl -X POST https://hvoice.app/api/v1/tts/synthesize \
  -H "Authorization: Bearer hv_live_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"Xin chào","voice_id":"YOUR_VOICE_ID","format":"mp3","language":"vi"}'

Poll GET /api/v1/tts/jobs/:jobId until status is completed, failed, or while waiting check queued (queue_position, eta_seconds). Credits are held on create and refunded on fail.

Speech to text

curl -X POST https://hvoice.app/api/v1/stt \
  -H "Authorization: Bearer hv_live_…" \
  -F "audio=@sample.mp3" \
  -F "lang=vi"

Accepts audio/video up to 40 MB. STT does consume character credits (duration-based). Optional field: lang or language.

Voice clone

curl -X POST https://hvoice.app/api/v1/voices/clone \
  -H "Authorization: Bearer hv_live_…" \
  -F "audio=@ref.wav" \
  -F "name=My voice" \
  -F "ref_text=optional transcript" \
  -F "language=vi"

You must have legal rights to the voice sample — see Terms · Voice Clone. If ref_text is omitted, Whisper transcribes when ASR is configured.

Usage

curl https://hvoice.app/api/v1/account/usage \
  -H "Authorization: Bearer hv_live_…"

Webhook

curl -X PUT https://hvoice.app/api/v1/account/webhook \
  -H "Authorization: Bearer hv_live_…" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url":"https://example.com/hooks/hvoice"}'

POSTs JSON {event, job_id, status, audio_url, error, …} on job completed/failed.

Admin endpoints are not part of this public reference. Questions: Zalo · Telegram.