Skip to main content
Transcribing an episode is one call: send it to POST /v1/transcripts. An episode that is already transcribed comes back at once; anything else comes back as a job you poll for a minute or two. There is no quote to take first. Everything below sends one header, Authorization: Bearer <your key>, and uses the base URL the API Reference declares. Replace hk_live_... with a key from your dashboard:
1

Send the episode

Name it by its Apple Podcasts link (in Apple Podcasts, Share → Copy Link on the episode), its feed URL and GUID, an episode_id from an earlier answer, or an upload of your own:
Two answers are possible:
  • 200 with is_cached: true and the transcript in the body. Done; the response’s X-Credits-Charged header says what it cost.
  • 202 with a job_id and the credits it holds, reserved_credits. Go to the next step.
The Idempotency-Key is optional; send one and a retry of the same request returns the same job instead of starting a second.
2

Wait for the job

status moves from queued through transcribing to completed. Every ten seconds is a reasonable interval; an hour of audio is typically done in a few minutes.
3

Read it

format is one of json, text, srt, vtt or md. Reading a transcript you paid for costs nothing, as often as you like.

​
Capping what a call may spend

The job holds a ceiling — its estimate plus 25% — and settles at the audio it actually measured, never above the ceiling. To refuse any call that could take more than you allow, send max_credits:
A call over the cap is refused with 422 max_credits_exceeded before anything is held, and the message names the figure it would have needed. dry_run: true answers the price without spending, if you want to see it first. Credits explains the rest.

​
Next

  • Submit and poll: every field, every state, and the idempotency rules.
  • Price a selection: many episodes at once, as one group.
  • Don’t know the episode yet? GET /v1/search/shows?q=… and GET /v1/shows/{show_id}/episodes find it; both are in the API Reference.