Sign in
Public API v1

Submit a TTS generation job

Submits a text-to-speech job. Returns immediately with a jobId. Poll GET /v1/tts/{jobId} to check progress and retrieve the audio URL when complete. Tokens are deducted on submission, billed by the submitted character count (minimum 50, × the AI surcharge only when you opt in with aiRefine: true), and refunded if the job permanently fails.

post/api/v1/tts

Request body

textstring required

Vietnamese text to synthesize.

voiceIdstring

Voice ID — must be one returned by GET /v1/voices for the requested engine. Omit to use that engine's default voice.

emotion'natural' | 'storytelling' | 'tin_tuc' | 'tu_nhien' | 'doc_truyen' | 'emotion_0' | 'emotion_1' | 'emotion_2' | 'emotion_3' | 'emotion_4' | 'emotion_5' | 'emotion_6' | 'emotion_7' | 'emotion_8' | 'emotion_9' | 'emotion_10' | 'emotion_11' | 'emotion_12' | 'emotion_13' | 'emotion_14' | 'emotion_15' | 'emotion_16' | 'emotion_17' | 'emotion_18' | 'emotion_19'
speednumber

Playback rate of the synthesized speech. 1.0 is the natural pace.

engine'v3' | 'v4'

TTS engine: "v3" (48 kHz, default, full feature set) or "v4" (48 kHz, reference-based voices, premium rate). Omit to use the configured default. The voice must belong to the engine you pick.

aiRefineboolean

AI text refinement. Defaults to FALSE on the public API: the text is synthesized as submitted, with no AI moderation and no pronunciation normalization, billed at the plain per-character rate. Set true to run the same AI step the web app uses — formulas, acronyms and mixed-in English are read correctly and the content is checked — billed with the AI surcharge and one extra model round-trip of latency. Deterministic text preparation is applied either way.

Example request

{
  "text": "Xin chào Việt Nam!",
  "voiceId": "Trúc Ly",
  "emotion": "natural",
  "speed": 1,
  "engine": "v3"
}

Response

Job accepted and queued. Poll GET /api/v1/tts/{jobId}.

jobIdstring required
statusstring required
messagestring required

Example response

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "message": "Job queued. Poll GET /v1/tts/{jobId} for status and audio URL."
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.