> ## Documentation Index
> Fetch the complete documentation index at: https://docs.videohighlight.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transcripts

> Extract transcripts from media files

<CardGroup cols={2}>
  <Card title="Get transcript" icon="download" href="#get-transcript">
    Retrieve existing transcript data
  </Card>

  <Card title="Stream transcript" icon="bolt" href="#stream-transcript">
    Generate transcripts in real-time
  </Card>
</CardGroup>

You can transcribe YouTube, Vimeo, DailyMotion and private media files (.mp4 and .mp3). More formats will be introduced soon.

<Note>
  Transcripts provide accurate, time-stamped text versions of your video content with optional AI formatting for
  enhanced readability.
</Note>

## Get transcript

<div className="mb-4">
  <code className="text-green-600 font-bold">GET</code> <code className="bg-gray-100 px-2 py-1 rounded">[https://videohighlight.com/api-v1/transcripts](https://videohighlight.com/api-v1/transcripts)</code>
</div>

### Path variables

<ResponseField name="videoId" type="string" required>
  The video ID for the file.

  <Expandable title="Video ID Examples">
    * **YouTube**: For `https://www.youtube.com/watch?v=65_PmYipnpk`, the videoId is: `65_PmYipnpk`
    * **Vimeo**: For `https://vimeo.com/318971562`, the videoId is: `318971562`
    * **DailyMotion**: For `https://www.dailymotion.com/video/x8w5pyg`, the videoId is: `x8w5pyg`
  </Expandable>
</ResponseField>

### Request parameters

<ResponseField name="type" type="string" required>
  The media type of the video.

  **Options**: `youtube`, `vimeo`, `dailymotion`, or `private`
</ResponseField>

<ResponseField name="languageCode" type="string" required>
  The language code of the input audio in ISO-639-1 format.

  **Examples**: `en`, `en-US`, `fr`, `es`
</ResponseField>

<ResponseField name="aiFormatted" type="boolean" required>
  If true, the transcript will be formatted by the AI.

  <Note>
    This is applicable for auto-generated transcripts from video platforms like YouTube. It is not applicable for
    private videos.
  </Note>
</ResponseField>

### Response

<CodeGroup>
  ```json Transcript Response theme={null}
  {
      "transcript_video_id": "92195d82-bff5-4b3b-bc7b-9ae684fa34ba",
      "video_id": "65_PmYipnpk",
      "type": "youtube",
      "language_code": "en",
      "video_title": "Steve Jobs - Courage",
      "video_duration": 214,
      "transcript": {
      "transcript_segments": [
  {
      "id": "95cffeb9-52ed-4e6c-a3af-7bcf6b3bd96a",
      "start": "0:00:01",
      "segment": "Apple is a company that has doesn't have the most resources of everybody in the world and the way we've succeeded is by",
      "start_time": 1.34,
      "end_time": 15.24,
      "segment_length": 119
  },
  {
      "id": "ec56262e-7216-4919-a952-271ee445e34b",
      "start": "0:00:13",
      "segment": "choosing what horses to ride really carefully technically we try to look for these technical vectors that that have a",
      "start_time": 12.99,
      "end_time": 23.34,
      "segment_length": 117
  },
  {
      "id": "12e6c87a-bb03-47e4-afeb-1a85c03b7e22",
      "start": "0:00:20",
      "segment": "...",
      "start_time": 19.89,
      "end_time": 31.949,
      "segment_length": 110
  }
      ]
  }
  }
  ```

  ```json Segment Structure theme={null}
  {
      "id": "unique-segment-id",
      "start": "0:00:01",
      "segment": "Transcript text content",
      "start_time": 1.34,
      "end_time": 15.24,
      "segment_length": 119
  }
  ```
</CodeGroup>

<ResponseField name="start" type="string">
  Human-readable timestamp in HH:MM:SS format
</ResponseField>

<ResponseField name="start_time" type="number">
  Start time of the segment in seconds
</ResponseField>

<ResponseField name="end_time" type="number">
  End time of the segment in seconds
</ResponseField>

<ResponseField name="segment_length" type="number">
  Length of the transcript segment text in characters
</ResponseField>

### Error responses

<ResponseField name="200" type="OK">
  The transcript has been successfully retrieved.
</ResponseField>

<ResponseField name="204" type="NO_CONTENT">
  The video has not been transcribed yet.
</ResponseField>

<ResponseField name="400" type="BAD_REQUEST">
  The request is invalid.
</ResponseField>

<ResponseField name="401" type="UNAUTHORIZED">
  The request is unauthorized.
</ResponseField>

<ResponseField name="500" type="INTERNAL_SERVER_ERROR">
  The server has encountered an error.
</ResponseField>

<Warning>
  If the video has not been transcribed yet, the response will be `204` with no content. Calling the Stream endpoint
  is required.
</Warning>

***

## Stream transcript

<div className="mb-4">
  <code className="text-blue-600 font-bold">POST</code> <code className="bg-gray-100 px-2 py-1 rounded">[https://videohighlight.com/api-v1/transcripts/stream](https://videohighlight.com/api-v1/transcripts/stream)</code>
</div>

### Request body

<ResponseField name="video_id" type="string" required>
  The unique identifier for the video
</ResponseField>

<ResponseField name="type" type="string" required>
  The media type of the video. Options: `youtube`, `vimeo`, `dailymotion`, or `private`
</ResponseField>

<ResponseField name="language_code" type="string" required>
  The language code of the input audio in ISO-639-1 format, like `en` or `fr`
</ResponseField>

<ResponseField name="ai_formatted" type="boolean" required>
  If true, the transcript will be formatted by the AI. This is applicable for auto-generated transcripts from video
  platforms like YouTube. It is not applicable for private videos.
</ResponseField>

<ResponseField name="use_sse" type="boolean" required>
  Whether to use Server-Sent Events for streaming
</ResponseField>

<ResponseField name="regenerate" type="boolean" required>
  Whether to regenerate the transcript if it already exists
</ResponseField>

<CodeGroup>
  ```json Request Example theme={null}
  {
      "video_id": "65_PmYipnpk",
      "type": "youtube",
      "language_code": "en",
      "ai_formatted": false,
      "use_sse": true,
      "regenerate": false
  }
  ```

  ```curl cURL Example theme={null}
  curl -X POST "https://videohighlight.com/api-v1/transcripts/stream" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "video_id": "65_PmYipnpk",
  "type": "youtube",
  "language_code": "en",
  "ai_formatted": false,
  "use_sse": true,
  "regenerate": false
  }'
  ```
</CodeGroup>

## Response Types

The streaming endpoint returns different types of messages:

### Download Progress Messages

```json Download Progress theme={null}
{
    "type": "download_progress",
    "info": {
        "progress": 0.5,
        "speed": "1.5x",
        "eta": "1m 30s"
    }
}
```

<Tip>
  Download progress shows real-time information about video file processing, including speed and estimated time to
  completion.
</Tip>

### Error Messages

<CodeGroup>
  ```json Error Response theme={null}
  {
      "type": "error",
      "info": {
      "type": "[ERROR-FILE-DOWNLOAD]",
      "message": "This video can not be downloaded."
  }
  }
  ```

  ```json Error Types theme={null}
  {
      "ERROR": "Generic error message",
      "ERROR-FILE-DOWNLOAD": "The video can not be downloaded",
      "ERROR-FILE-DOWNLOAD-TO-ASR": "The video can not be downloaded by the ASR service",
      "ERROR-VIDEO-PRIVATE": "The video is private",
      "ERROR-VIDEO-GEO-RESTRICTION": "The video is not available in your region",
      "ERROR-VIDEO-COPYRIGHT": "The video is copyrighted",
      "ERROR-VIDEO-UNAVAILABLE": "The video is not available",
      "ERROR-GENERIC-STREAMING-EXCEPTION": "Generic error message",
      "ERROR-REMOTE-ASR-CONNECTION": "The ASR service connection has failed",
      "ERROR-REMOTE-ASR-TIMEOUT": "The ASR service connection has timed out",
      "ERROR-UNEXPECTED": "An unexpected error has occurred"
  }
  ```
</CodeGroup>

### Transcript Segment Messages

```json Transcript Segment theme={null}
{
    "type": "segment",
    "info": {
        "id": "b44f3bba-91ee-4c47-b2c4-c5a132c9e730",
        "start_time": 1.959,
        "end_time": 15.36,
        "text": "apple is a company that has doesn't have the most resources of everybody in the world and um the way we've succeeded is",
        "text_length": 119,
        "timestamp": "0:00:02",
        "asr": true,
        "language_code": "en",
        "progress": 0.2
    }
}
```

<ResponseField name="asr" type="boolean">
  Indicates whether this segment was generated using Automatic Speech Recognition
</ResponseField>

<ResponseField name="text_length" type="number">
  The character length of the transcript text
</ResponseField>

<ResponseField name="progress" type="number">
  Current progress of the transcription process (0.0 to 1.0)
</ResponseField>

### Semaphore Messages

<CodeGroup>
  ```json Completion Status theme={null}
  {
      "type": "semaphore",
      "info": {
      "status": "[DONE]"
  }
  }
  ```

  ```json Status Types theme={null}
  {
      "DONE": "The transcript has been successfully generated",
      "INSUFFICIENT_DATA": "Not sufficient data to complete (e.g., video too short)"
  }
  ```
</CodeGroup>

### Transcript Info Messages

```json Transcript Info theme={null}
{
    "type": "transcript_info",
    "info": {
        "transcript_video_id": "95cffeb9-52ed-4e6c-a3af-7bcf6b3bd96a",
        "video_id": "65_PmYipnpk",
        "type": "youtube",
        "video_title": "Steve Jobs - Courage",
        "video_duration": 214,
        "language_code": "en",
        "asr": true
    }
}
```

<ResponseField name="video_duration" type="number">
  Duration of the video in seconds
</ResponseField>

<ResponseField name="transcript_video_id" type="string">
  Unique identifier for this specific transcript
</ResponseField>

### Progress Messages

```json Progress Update theme={null}
{
    "type": "transcript_progress",
    "info": {
        "progress": 0.5,
        "language_code": "en",
        "asr": true
    }
}
```

<Note>
  Progress messages provide real-time updates on transcription completion percentage and processing status.
</Note>