HEheygen
Audio

Create Transcription

Changed on

Transcribe an audio or video file with scribe-v2. The request waits for the transcript and answers 200 with it. Audio is limited to 10 minutes with diarize on and 30 minutes with it off. Send an Idempotency-Key header with every request: it is required. Repeating a request with the same key and body returns the original result instead of transcribing again, and a duplicate sent while the original is still running gets 409 request_in_progress. The transcription is priced at the vendor's cost for the decoded audio length. A request the workspace's API credits cannot cover is refused with 402 insufficient_credit before the model runs. The credits are charged once the transcript is made, and a failed transcription is not charged. If the balance no longer covers the charge when the transcript is ready, the request answers 402 insufficient_credit without it. Read status rather than assuming the POST finished the transcription.

post/v3/audio/transcriptions

Request

  • Base URL
    https://api.heygen.com
  • URL
    https://api.heygen.com/v3/audio/transcriptions
  • Auth
    • API key in header x-api-key
    • or HTTP bearer

Headers

Idempotency-Keystring required

Required client-supplied key for safely retrying a request that charges. A retry within 24 hours that shares this key returns the original response instead of running again. The body must be the same: a different body under the same key returns 409 conflict. A retry that arrives while the original is still in flight gets a 409 request_in_progress. When the original could not be confirmed, repeating it with the same key settles that attempt instead of starting another. Scope is the space plus the request path, so the same key on another video is independent, and a key sent by another member of the space replays that member's response. A missing or blank value is rejected with 400. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default.

Request body

model'scribe-v2' required

Transcription model.

languagestring nullable

Spoken language as a lowercase ISO 639 code, such as en. Detected from the audio when omitted.

word_timestampsboolean

Return per-word timings in each segment.

diarizeboolean

Label speakers. Audio is limited to 10 minutes with this on and 30 minutes with it off.

num_speakersinteger nullable

Expected number of speakers; only valid with diarize true.

Response

The finished transcription with its transcript.

Changes