PUBLIC API · /api/v1

API Reference

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

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: 30 requests per minute per customer.

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	/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 or failed. Character credits are deducted from your plan balance.

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 not consume character credits. 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"

If ref_text is omitted, Whisper transcribes the clip when ASR is configured. Returns voice_id for synthesize.

Usage

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

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