API Integration

Your first transcription

Transcription happens in the background. Creating a job returns immediately; check its status until the result is ready.

1. 1

   Create a job

   Send POST /transcripts with a direct, public media URL. Keep the returned id.

2. 2

   Check its progress

   Poll GET /transcripts/{id} every 15–30 seconds until status is complete or error.

3. 3

   Use your transcript

   Read JSON from data, or download export_url when you request SRT or VTT.

Job status

Treat any other status as still in progress. New intermediate states may be added.

Authentication

Send your API key in the Authorization header of every request, exactly as shown when you created it.

Authorization: <your api key>

Do not add a Bearer prefix.

New keys start with tp_live_. The full key is shown only once, when you create it. If you lose it, revoke it and create a new one; a revoked key stops working immediately.

An active subscription and the required API key scope are needed.

Create a transcript

Start a transcription job for a media file at a public URL. The response returns once the job is queued, with status: "initializing".

Taption downloads the file directly. Share-page links, such as a Google Drive or Dropbox preview page, will not work.

media_urlstringrequired

Direct download link to your media file.

Maximum 2048 characters

extensionstringrequired

The media file's format.

mp3wavm4aaacflacwmaopusmp4

languagestringrequired

Language spoken in the media, as a language tag. See the Languages reference.

View language tags

namestring

Display name for the transcript. Defaults to the file name in `media_url`. Longer names are cut to 200 characters.

Maximum 200 characters

export_typestring

Output format. Defaults to json, which returns parsed transcript content in data. srt and vtt return a file link in export_url.

jsonsrtvtt

Default: json

max_charinteger

Maximum characters per caption segment. Defaults to `16` for Chinese, Japanese, Korean and Cantonese, and `65` for other languages. Values outside 1-200 are ignored and the default is used.

1–200

Responses

Retrieve a transcript

Get the current status and result of a transcript. Poll every 15–30 seconds while the job is in progress.

For json or an omitted export type, the completed result appears in data. For srt or vtt, download the file from export_url.

idstringrequired

The transcript ID returned by POST /transcripts.Maximum 256 characters

Responses

The transcript object

Creation and status requests return a JSON object. Its fields describe the job and, when ready, its output.

idstring

The transcript ID. Use it with `GET /transcripts/{id}`.

statusstring

Where the job is: `initializing`, `transcribing`, `complete` or `error`. Treat any other value as still in progress.

dataJSON

Parsed JSON export when ready for json or omitted export_type; otherwise an empty string.

export_urlstring

Download link for an srt or vtt export. Empty until ready. Omitted from status responses for json or omitted export_type.

messagestring

Extra detail about the current status. While `transcribing`, this may be a progress stage such as `ANALYZING` or `FINALIZING`. When `status` is `error`, it describes the failure. Written for people; do not parse it.

error_codestring

Optional machine-readable code for a submission limit error.

limitinteger

The applicable account limit, included with HTTP 429.

Errors & retries

Use the HTTP status code to decide what to do next. The message field is written for people; its wording may change.

API responses include an X-Request-Id header. Include it when you contact support about a request.