Skip to content

Documentation menu

Hohe Labs
Developer hub v1
Documentation

api reference

Text to speech

POST /v1/tts for instant audio, or a job for the natural voice.

Amharic text in, audio out. There are two voices and they are delivered differently, because they cost very different amounts to run. Pick by which trade you want: an answer now, or the better voice.

Which voice

  • hohe-tts answers immediately, in the response itself. 16 kHz WAV, one voice.
  • hohe-tts-natural is a job you collect. 24 kHz WAV, several voices, and it sounds considerably better.

GET /v1/models reports this as a delivery field of sync or async, so you do not have to hardcode which is which.

Instant audio

POST /v1/tts with a JSON body. text is required, model defaults to hohe-tts, and the response body is the WAV itself rather than JSON around it. The cost is in the x-credits-charged header, so you do not have to parse anything to know what you paid.

bash
curl https://api.hohelabs.com/v1/tts \
  -H 'Authorization: Bearer hohe_YOUR_KEY' \
  -H 'Idempotency-Key: greeting-001' \
  -H 'Content-Type: application/json' \
  -d '{"text":"ሰላም፣ እንኳን ደህና መጡ።"}' \
  -o greeting.wav

Synthesis is billed per character of the text you sent, counted as Unicode code points, which for Amharic is one per Ge’ez syllable. You can therefore work out the cost before you call.

The natural voice, as a job

POST /v1/tts/jobs with the same text, plus an optional voice. The response is 202 with a job ID. Up to 2,000 characters per job, and ten jobs queued per workspace at a time.

bash
curl https://api.hohelabs.com/v1/tts/jobs \
  -H 'Authorization: Bearer hohe_YOUR_KEY' \
  -H 'Idempotency-Key: chapter-07' \
  -H 'Content-Type: application/json' \
  -d '{"text":"ሰላም፣ እንኳን ደህና መጡ።","voice":"male-01"}'

Collect the audio

GET /v1/tts/jobs/{id} returns queued, working, ready or failed. Poll every 10 to 30 seconds rather than every second: a queued job is usually waiting for the machine to start, which takes a few minutes, and polling faster will not make it sooner. Once the status is ready the response carries an audio_url.

bash
curl https://api.hohelabs.com/v1/tts/jobs/JOB_ID -H 'Authorization: Bearer hohe_YOUR_KEY'

curl https://api.hohelabs.com/v1/tts/jobs/JOB_ID/audio -H 'Authorization: Bearer hohe_YOUR_KEY' -o chapter.wav

GET /v1/tts/jobs lists your 30 most recent. Jobs and their audio are kept for 24 hours, so download what you need and keep your own copy. Another workspace cannot read your jobs.

Billing and failures

Both models use the same tts.synthesize price and the same monthly free allowance, billed on the characters you submitted. The charge and the audio commit together, so a failed job is not charged and collecting the audio does not charge again. Asking for an unknown voice fails the job with the reason in its error field.

Send an Idempotency-Key on both endpoints. Reusing a key with different text returns 409 idempotency_conflict rather than quietly handing back the wrong audio.

All documentation