Tài liệu API HVoice

Tích hợp TTS, STT và nhân bản giọng vào sản phẩm của bạn. Base URL API: https://hvoice.app/api/v1

Getting started

1. Tạo API key trong Studio → Tích hợp API. Full key chỉ hiện một lần — lưu ngay.
2. GET /voices lấy voice_id và xem credit_multiplier.
3. POST /tts/synthesize với text + voice_id → nhận job_id.
4. Poll GET /tts/jobs/:jobId đến completed → dùng audio_url (hoặc nhận webhook).

Authentication

Mọi request TTS/STT/voices gửi:

Authorization: Bearer hv_live_…

• Tạo key: Studio UI hoặc POST /account/api-keys (JWT) → response có key (một lần) + key_prefix.
• Liệt kê / thu hồi: GET / DELETE /account/api-keys/:id (JWT).

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

Limits & billing

Markup giọng

Gói dùng thử chỉ dùng một số giọng thư viện. Clone: encode miễn phí; Whisper chỉ trừ nếu không gửi ref_text.

Voices

Danh sách giọng thư viện + clone của bạn. Dùng id làm voice_id. Xem credit_multiplier trước khi trừ.

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

{
  "voices": [
    {
      "id": "YOUR_VOICE_ID",
      "name": "HN - Ngọc Huyền",
      "language": "vi",
      "gender": "female",
      "preview_url": "/library/audio/….mp3",
      "avatar_url": "/…",
      "beta_tier": "premium",
      "credit_multiplier": 3,
      "is_cloned": 0,
      "voice_source": "library"
    }
  ],
  "provider": "hvoice"
}

Alias: GET /voices/cloned · Preview: GET /voices/:voiceId/preview.

TTS Synthesize

Tạo job TTS bất đồng bộ. Poll job (hoặc webhook) đến completed.

Response tạo job

{
  "job_id": "uuid-string",
  "status": "processing",
  "audio_url": null,
  "estimated_time": 60,
  "tokens_used": 120,
  "credit_multiplier": 3,
  "text_len": 40
}

Khi GPU đầy: status: "queued" kèm queue_position, eta_seconds. Credit trừ khi tạo job; hoàn nếu fail.

Pause settings

Giây nghỉ sau mỗi dấu (0–3). Schema đồng bộ Studio.

{
  "pause_settings": {
    "use_punctuation_pauses": true,
    "punctuation_pauses": {
      ".": 0.45,
      ",": 0.25,
      ":": 0.35,
      ";": 0.3,
      "?": 0.45,
      "!": 0.45,
      "\n": 0.6
    }
  }
}

Tắt: bỏ field hoặc use_punctuation_pauses: false.

Jobs & parts

Poll — processing

{
  "job_id": "uuid-string",
  "status": "processing",
  "audio_url": null,
  "progress": "Đang tạo · 2/11 đoạn xong · 45%",
  "estimated_time": 10
}

Poll — completed

{
  "job_id": "uuid-string",
  "status": "completed",
  "audio_url": "https://hvoice.app/audio/jobs/….mp3",
  "duration_seconds": 5.2,
  "text_len": 1200,
  "tokens_used": 3600
}

status: queued | processing | completed | failed | cancelled. Poll mỗi ~1.5–2s đến trạng thái kết thúc.

SRT → audio

Upload file .srt → một job audio. Tổng ký tự lời cue ≤ 100.000 / request.

curl -X POST https://hvoice.app/api/v1/tts/synthesize-srt \
  -H "Authorization: Bearer hv_live_…" \
  -F "file=@subtitles.srt" \
  -F "voice_id=YOUR_VOICE_ID" \
  -F "format=mp3" \
  -F "language=vi" \
  -F "title=Phụ đề tập 1"

Hoặc JSON POST /tts/synthesize với source_srt.

Voice clone

1. Gửi mẫu audio + ref_text → nhận voice_id.
2. Đợi vài giây (enrolling); synthesize lần đầu dùng giọng mới.
3. TTS với voice_id clone — trừ theo credit_multiplier (thường ×2.5).
4. Xóa: DELETE /voices/:voiceId.

curl -X POST https://hvoice.app/api/v1/voices/clone \
  -H "Authorization: Bearer hv_live_…" \
  -F "name=Giọng thương hiệu" \
  -F "ref_text=Nội dung đọc đúng y như trong file audio mẫu." \
  -F "language=vi" \
  -F "audio=@/path/to/sample.wav"

Bạn phải có quyền hợp pháp với mẫu giọng — xem Điều khoản · Voice Clone.

Speech to text

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

Audio/video tối đa ~40 MB. STT trừ ký tự theo thời lượng. Field: lang hoặc language. Alias nhận dạng mẫu: POST /voices/transcribe-ref.

Account

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

Trả số dư ký tự, ledger gần đây, và thông tin gói.

Webhooks

Đăng ký URL HTTPS. Server POST JSON khi job completed hoặc failed.

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

GET /account/webhook — xem URL hiện tại. Gửi webhook_url: "" để xoá.

Payload

{
  "event": "job.completed",
  "job_id": "uuid-string",
  "status": "completed",
  "audio_url": "https://hvoice.app/audio/jobs/….mp3",
  "error": null,
  "text_len": 1200,
  "tokens_used": 3600
}

Errors

Body lỗi thường dạng:

{
  "error": "Mô tả lỗi",
  "code": "QUEUE_FULL",
  "needed": 5000,
  "balance": 1200
}

Code samples

cURL

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

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, đây là ví dụ chuyển văn bản thành giọng nói.",
    "voice_id": "YOUR_VOICE_ID",
    "format": "mp3",
    "speed": 1.0,
    "language": "vi"
  }'

curl https://hvoice.app/api/v1/tts/jobs/JOB_ID \
  -H "Authorization: Bearer hv_live_…"

Python — synthesize + poll

import time
import requests

API_KEY = "hv_live_…"
BASE = "https://hvoice.app/api/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def synthesize(text, voice_id, pause_settings=None):
    payload = {
        "text": text,
        "voice_id": voice_id,
        "format": "mp3",
        "speed": 1.0,
        "language": "vi",
    }
    if pause_settings:
        payload["pause_settings"] = pause_settings
    r = requests.post(f"{BASE}/tts/synthesize", headers=HEADERS, json=payload, timeout=120)
    r.raise_for_status()
    return r.json()["job_id"]

def wait_job(job_id, timeout=600):
    t0 = time.time()
    while time.time() - t0 < timeout:
        r = requests.get(f"{BASE}/tts/jobs/{job_id}", headers=HEADERS, timeout=60)
        r.raise_for_status()
        d = r.json()
        if d.get("status") in ("completed", "failed", "cancelled"):
            return d
        time.sleep(2)
    raise TimeoutError(job_id)

job_id = synthesize(
    "Xin chào. Đây là ví dụ.",
    "YOUR_VOICE_ID",
    pause_settings={
        "use_punctuation_pauses": True,
        "punctuation_pauses": {".": 0.5, ",": 0.2, "\n": 0.6},
    },
)
print(wait_job(job_id))

JavaScript — synthesize + poll

const API_KEY = "hv_live_…";
const BASE = "https://hvoice.app/api/v1";

async function synthesize(text, voiceId, pauseSettings) {
  const body = {
    text,
    voice_id: voiceId,
    format: "mp3",
    speed: 1.0,
    language: "vi",
  };
  if (pauseSettings) body.pause_settings = pauseSettings;
  const res = await fetch(`${BASE}/tts/synthesize`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error(await res.text());
  const { job_id } = await res.json();
  for (;;) {
    const j = await fetch(`${BASE}/tts/jobs/${job_id}`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    }).then((r) => r.json());
    if (["completed", "failed", "cancelled"].includes(j.status)) return j;
    await new Promise((r) => setTimeout(r, 2000));
  }
}

// synthesize("Xin chào, đây là ví dụ.", "YOUR_VOICE_ID")
//   .then((j) => console.log("Audio URL", j.audio_url))
//   .catch(console.error);

Quản lý key: Studio · Tích hợp API · Bảng giá · Hỗ trợ: Zalo · Telegram