Konthora API

Base URL

All endpoints live under the versioned base URL below. Requests and responses are JSON, except for file downloads, which return the audio or transcript file itself.

https://devsharif-konthora-api.hf.space/api/v1

There is no other version: the path always starts with /api/v1. Browser (fetch) calls are accepted from konthora.dev.bd and from localhost development origins only; server-side calls from anywhere are fine.

Authentication

There are no API keys. Creating a job returns a jobId and an accessToken. Send that token as a Bearer token on every later call for that job — status checks, audio downloads, transcripts, and result files:

Authorization: Bearer YOUR_TOKEN

• The token is shown once. The create-job response is the only place the full token appears; the server stores only a hash of it. If you lose the token, there is no way to recover the job — create a new one.
• One token per job. A token only works for the job it was issued with. Using it on another job returns 401.
• Public endpoints need no token. Listing voices, reading transcription capabilities, and fetching a voice preview are unauthenticated.

Text to speech

Turn text into spoken audio. Kokoro is the default engine; Edge voices are Microsoft neural voices served as a second engine while Edge is reachable. Use the same voices the text-to-speech workspace offers — see all voices for the catalogue.

List voices

curl https://devsharif-konthora-api.hf.space/api/v1/tts/voices

Each voice carries id, displayName, gender, accent, language, recommended, speed limits (defaultSpeed, minimumSpeed, maximumSpeed), engine (kokoro or edge), and previewUrl. The preview URL is empty for Edge voices — they have no hosted preview clips, and the on-demand preview endpoint below is what serves them.

Create a job

curl -X POST https://devsharif-konthora-api.hf.space/api/v1/tts/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Welcome to Konthora. This is how my voice sounds.",
    "voiceId": "af_heart",
    "engine": "kokoro",
    "accent": "American English",
    "speed": 1.0,
    "outputFormat": "mp3",
    "sentencePauseMs": 220,
    "paragraphPauseMs": 500,
    "normalizeText": true
  }'

Check job status

curl https://devsharif-konthora-api.hf.space/api/v1/tts/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

status is one of queued, processing, completed, failed, or expired. progressStage gives finer detail: queued, preparing_text, generating_speech, processing_audio, finalizing_file, then completed, failed, or expired.

The response also includes createdAt and expiresAt, durationSeconds (null until the audio exists), characterCount, outputFormat (the format actually produced — see the format note below), errorCode and errorMessage on failure, and downloadUrl, which is only present once the job is completed.

Download the audio

curl https://devsharif-konthora-api.hf.space/api/v1/tts/jobs/JOB_ID/audio \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o konthora-speech.mp3

Preview a voice

curl https://devsharif-konthora-api.hf.space/api/v1/tts/preview/en-US-AriaNeural \
  -o preview.mp3

• Edge voices only. Kokoro voices and unknown ids return 404 VOICE_UNSUPPORTED. Kokoro previews are static clips served through the previewUrl field of the voice list instead.
• One fixed sentence per language. The clip reads a single sentence in the voice's language — English, Bangla, Hindi, Spanish, French, Italian, or Portuguese; any other language falls back to the English sentence.
• Cached, and cheap. The clip is synthesized once per voice and then served from disk (cached by browsers for a day). Previews have their own rate-limit bucket of 120 per hour and never consume the 30-per-hour TTS job quota.
• Edge must be up. If Edge is unreachable when you ask, the endpoint returns 503 even if the voice is still listed in the catalogue.

Format note: Kokoro synthesis produces a WAV master; MP3 output is made by transcoding it with FFmpeg, and Edge synthesis produces MP3, which is transcoded to WAV the same way. If FFmpeg is unavailable on the server, the requested format is silently replaced with the other one and the status response's outputFormat tells you which file you actually got — so always read that field instead of assuming your request was honoured.

Transcription

Turn an audio or video file into a timestamped transcript. Transcription is English only: the model is faster-whisper small.en, so auto detection maps to English and the reported detected language is always en. The same flow powers the audio-to-text workspace.

Capabilities

curl https://devsharif-konthora-api.hf.space/api/v1/transcription/capabilities

Create a job

curl -X POST https://devsharif-konthora-api.hf.space/api/v1/transcription/jobs \
  -F "file=@recording.mp3" \
  -F "language=auto" \
  -F "timestampMode=sentence" \
  -F "exportFormat=txt"

After upload, the server inspects the media container with FFprobe (rejecting files longer than 600 seconds or with no audio track) and extracts the audio to a 16 kHz mono WAV with FFmpeg before transcribing. If the upload is cancelled or the file cannot be read, the job is cleaned up and the queue slot is released.

Check job status

curl https://devsharif-konthora-api.hf.space/api/v1/transcription/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

status is one of queued, processing, completed, failed, or expired. progressStage moves through uploading (while the file streams in), inspecting_media, extracting_audio, transcribing, and formatting_transcript.

The response also includes the original filename and size, media duration, detected language and its probability, transcript and word counts, segment count, the timestamp mode and export format you chose, expiresAt, errorCode and errorMessage on failure, and resultUrl, which is only present once the job is completed.

Get the structured transcript

curl https://devsharif-konthora-api.hf.space/api/v1/transcription/jobs/JOB_ID/transcript \
  -H "Authorization: Bearer YOUR_TOKEN"

Download the transcript file

curl "https://devsharif-konthora-api.hf.space/api/v1/transcription/jobs/JOB_ID/result?format=srt" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o transcript.srt

Limits and expiry

Limits are enforced per client IP over a sliding one-hour window. When a limit is hit the response is 429 with a Retry-After header telling you how many seconds to wait.

A full queue returns 503 QUEUE_FULL, and hitting the active-job cap returns 429 — both mean “wait for a running job to finish”, not “wait an hour.” Listing voices, reading capabilities, polling status, and downloading results are not rate-limited.

Expiry: finished jobs — completed or failed — are kept for 60 minutes after they finish. The status response's expiresAt tells you exactly when. After that the audio or transcript files are deleted from disk and the job reports expired; later reads return 410 JOB_EXPIRED. Download results promptly — there is no way to extend a job's life.

Errors

Errors are JSON with a machine-readable code and a human-readable message: {"code": "RATE_LIMITED", "message": "..."}. Note that request validation failures return 400, not the 422 FastAPI would send by default.

Things to know before you build

• Jobs live in server memory. Job records are kept in memory, not in a database. If the API service restarts, job ids from before the restart stop resolving (404) — keep your tokens and downloads short-lived, and do not store job ids as permanent references.
• One worker per queue. TTS and transcription each run a single worker, so jobs run one at a time; long texts and long files queue behind whatever is already running.
• Edge voices can disappear mid-day. Edge is an unofficial free endpoint with no SLA. Its voices only appear in the voice list while a cached availability probe says Edge is reachable, and preview requests can still 503 if Edge goes down between probes.
• Transcription is English only. Uploading non-English audio still runs, but the model only knows English — the transcript will be wrong, not an error.
• Download URLs are relative. The downloadUrl and resultUrl fields in status responses are paths like /api/v1/tts/jobs/…/audio; resolve them against the base URL above.
• Poll, don't guess. There are no webhooks. Poll the status endpoint every couple of seconds and stop when the status is completed, failed, or expired.

Prefer the website? The text-to-speech workspace and the audio-to-text workspace use exactly this API, with the same voices, limits, and 60-minute expiry.