Retrieve the transcription of an asset

{
  "status": "ready",
  "words": [
    {
      "start": 0,
      "end": 0.32,
      "value": "Good"
    },
    {
      "start": 0.32,
      "end": 0.68,
      "value": "evening."
    },
    {
      "start": 0.8,
      "end": 1.15,
      "value": "Welcome"
    },
    {
      "start": 1.15,
      "end": 1.42,
      "value": "back."
    },
    {
      "start": 1.9,
      "end": 2.14,
      "value": "Thank"
    },
    {
      "start": 2.14,
      "end": 2.4,
      "value": "you."
    }
  ],
  "sentences": [
    {
      "start": 0,
      "end": 0.68,
      "value": "Good evening."
    },
    {
      "start": 0.8,
      "end": 1.42,
      "value": "Welcome back."
    },
    {
      "start": 1.9,
      "end": 2.4,
      "value": "Thank you."
    }
  ],
  "utterances": [
    {
      "start": 0,
      "end": 1.42,
      "value": "Good evening. Welcome back.",
      "speaker": "SPEAKER_00"
    },
    {
      "start": 1.9,
      "end": 2.4,
      "value": "Thank you.",
      "speaker": "SPEAKER_01"
    }
  ]
}

This method retrieves the transcription of a video or audio asset. An asset that has a transcription returns 200 with the current transcription status. The endpoint returns 404 when the asset cannot be found or has no transcription.

The platform generates transcriptions asynchronously. Poll this endpoint to monitor the transcription status.

When the status is ready, the response contains the segmentations you requested that the transcription supports. A transcription does not always support every segmentation, so read the segmentations the response returns rather than assuming every requested one is present.

This method retrieves the transcription of a video or audio asset. An asset that has a transcription returns `200` with the current transcription status. The endpoint returns `404` when the asset cannot be found or has no transcription. The platform generates transcriptions asynchronously. Poll this endpoint to monitor the transcription status. When the status is `ready`, the response contains the segmentations you requested that the transcription supports. A transcription does not always support every segmentation, so read the segmentations the response returns rather than assuming every requested one is present.

Authentication

x-api-keystring

Your API key.

Note

You can find your API key on the API Keys page.

Your API key. <Note title="Note"> You can find your API key on the <a href="https://playground.twelvelabs.io/dashboard/api-keys" target="_blank">API Keys</a> page. </Note>

Path parameters

asset_idstringRequired

The unique identifier of the asset.

Query parameters

includelist of enumsOptional

Specifies the transcriptions to return. Each value segments the transcription differently:

words: One entry for each word.
sentences: One entry for each chunk the speech recognition model detects as a sentence.
utterances: One entry for each speaker turn.

Send repeated values, such as the ?include=words&include=utterances query string. The platform also accepts one comma-separated value, such as the ?include=words,utterances query string.

Default: words.

Specifies the transcriptions to return. Each value segments the transcription differently: - `words`: One entry for each word. - `sentences`: One entry for each chunk the speech recognition model detects as a sentence. - `utterances`: One entry for each speaker turn. Send repeated values, such as the `?include=words&include=utterances` query string. The platform also accepts one comma-separated value, such as the `?include=words,utterances` query string. **Default**: `words`.

Allowed values:

Response

The transcription status and the requested transcriptions have been successfully retrieved.

statusenum

Indicates the current status of the transcription.

Values:

pending: The platform has not started transcribing the asset.
processing: The platform is transcribing the asset.
ready: The transcription is available.
failed: The platform could not transcribe the asset. The error field describes the reason.

Allowed values:

wordslist of objectsOptional

One entry for each word. Present when the status is ready, the include parameter lists words, and the transcription supports word-level segmentation.

sentenceslist of objectsOptional

One entry for each chunk the speech recognition model detects as a sentence. Present when the status is ready, the include parameter lists sentences, and the transcription supports sentence-level segmentation.

utteranceslist of objectsOptional

One entry for each speaker turn. Present when the status is ready, the include parameter lists utterances, and the transcription supports speaker-turn segmentation.

errorobjectOptional

Details about the failure. Present when the status is failed.

Errors

400

Bad Request Error

404

Not Found Error