> ## 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.

# Summaries

> Extract summaries from media files

<CardGroup cols={2}>
  <Card title="Get Summary" icon="download" href="#get-summary">
    Retrieve existing summary data with structured insights
  </Card>

  <Card title="Stream Summary" icon="bolt" href="#stream-summary">
    Generate summaries in real-time with live progress
  </Card>
</CardGroup>

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

<Note>
  Summaries provide structured, time-stamped insights from your media content, available in both default format and
  compressed key points.
</Note>

<Tabs>
  <Tab title="Quick Start">
    <Steps>
      <Step title="Generate Transcript">
        First, ensure you have a transcript by calling `/transcripts/stream`
      </Step>

      <Step title="Stream Summary">
        Call `/summaries/stream` to generate your summary
      </Step>

      <Step title="Retrieve Results">
        Use `/summaries` to get the completed summary data
      </Step>
    </Steps>
  </Tab>

  <Tab title="Supported Formats">
    <AccordionGroup>
      <Accordion title="Video Platforms">
        * **YouTube**: Full support with metadata
        * **Vimeo**: Professional and personal accounts
        * **DailyMotion**: Public and unlisted videos
      </Accordion>

      <Accordion title="Private Files">
        * **MP4**: Video files up to 2GB
        * **MP3**: Audio files with quality preservation
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

## Get summary

<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/summaries](https://videohighlight.com/api-v1/summaries)</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="summaryType" type="string" required>
  The type of the summary.

  **Options**:

  * `default` - Full summary with detailed segments
  * `compressed` - Key points only
</ResponseField>

### Response

<CodeGroup>
  ```json Summary Response theme={null}
  {
      "summary_id": "EZYkP1VvTMeYaod3wtJE",
      "video_id": "65_PmYipnpk",
      "type": "youtube",
      "video_title": "Steve Jobs - Courage",
      "language_code": "en",
      "summary_type": "default",
      "summary_segments": [
  {
      "id": "39f6bcf3-454c-44ea-9f10-6af9a76aaf6d",
      "segment": "#  Apple's Strategy for Success",
      "start_time": 0.0,
      "index": 0
  },
  {
      "id": "c51abf9d-617b-4ed4-9e3a-d411a6812f49",
      "segment": "In this section, Apple's approach to success through strategic decision-making and technology adoption is discussed.",
      "start_time": -1.0,
      "index": 1
  },
  {
      "id": "5f42ce0c-1f48-42cd-a448-1c388e10cf8c",
      "segment": "## Apple's Strategic Technological Choices",
      "start_time": -1.0,
      "index": 2
  },
  {
      "id": "12fb5076-f0bf-4571-a5be-bc5d59d8a98b",
      "segment": "-  Apple's success stems from carefully selecting promising technological advancements to invest in.",
      "start_time": 0.0,
      "index": 3
  },
  {
      "id": "7bfa8108-f67c-4f07-8b7e-a7884b022b82",
      "segment": "-  Technology progresses through cycles, and Apple focuses on emerging technologies in their prime to minimize effort and maximize impact.",
      "start_time": 29.0,
      "index": 4
  },
  {
      "id": "a6f7e219-5007-415f-9464-99c6bca653d9",
      "segment": "-  Examples include transitioning from 5-inch floppy disks to 3.5-inch disks with the Mac, being early adopters of USB, and eliminating outdated technologies like floppy drives with the MacBook Air.",
      "start_time": 55.0,
      "index": 5
  },
  {
      "id": "daa33fd2-714c-4046-8b5c-27f898a69e62",
      "segment": "## Courage in Decision-Making",
      "start_time": -1.0,
      "index": 6
  },
  {
      "id": "b887c650-e873-4479-b9af-87f7e0e69c03",
      "segment": "-  Apple demonstrates courage by removing outdated features like floppy disk drives despite criticism.",
      "start_time": 81.0,
      "index": 7
  },
  {
      "id": "ef8443bf-1386-4d45-b6e5-2dcf166865a1",
      "segment": "-  The company prioritizes future-oriented decisions over popular opinion, focusing on what will drive innovation forward.",
      "start_time": 105.0,
      "index": 8
  },
  {
      "id": "bf060daa-dff8-429e-8558-e95aafa77515",
      "segment": "## Customer-Centric Product Development",
      "start_time": -1.0,
      "index": 10
  },
  {
      "id": "1c21508c-8290-4e9b-bd75-f3d580ce2ee8",
      "segment": "-  Apple emphasizes certain features in products while omitting others based on market feedback and their vision for creating exceptional products.",
      "start_time": 131.0,
      "index": 11
  }
      ],
      "version": 1
  }
  ```

  ```json Segment Structure theme={null}
  {
      "id": "unique-segment-id",
      "segment": "Content of the segment",
      "start_time": 0.0,
      "index": 0
  }
  ```
</CodeGroup>

<ResponseField name="index" type="number">
  The index of the segment in the summary
</ResponseField>

<ResponseField name="start_time" type="number">
  The start time of the segment in seconds. `-1` means that the core concept was not associated with a specific
  timestamp
</ResponseField>

### Error responses

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

<ResponseField name="204" type="NO_CONTENT">
  The video has not been summarized 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 summarized yet, the response will be `204` with no content. Calling the Stream endpoint is
  required.
</Warning>

***

## Stream summary

<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/summaries/stream](https://videohighlight.com/api-v1/summaries/stream)</code>
</div>

<Warning>
  **Current limitation:**

  The summary stream needs to be called AFTER a transcript stream has been called, or the transcript is available.

  **Options:**

  1. Call the `/transcripts/stream` endpoint first, and after a few seconds, call the `/summaries/stream` endpoint.
  2. Call the `/transcripts/stream` endpoint and allow the transcript generation to complete. Call the
     `/summaries/stream` after the transcript is available.
  3. Ensure that the `/transcripts/get` endpoint has a non `204` response before calling the `/summaries/stream`
     endpoint.

  Calling the `/summaries/stream` endpoint before the transcript is available will not generate a summary.
</Warning>

### 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="summary_type" type="string" required>
  The type of the summary. Options: `default` (for the default Summary) or `compressed` (for Key Points)
</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 summary if it already exists
</ResponseField>

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

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

## Response Types

The streaming endpoint returns different types of messages:

### 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>

### Summary Segment Messages

```json Summary Segment theme={null}
{
    "type": "segment",
    "info": {
        "id": "95cffeb9-52ed-4e6c-a3af-7bcf6b3bd96a",
        "start_time": 1.34,
        "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",
        "index": 1
  }
}
```

<Tip>
  The `start_time` value of `-1` indicates that the core concept was not associated with a specific timestamp.
</Tip>

### Semaphore Messages

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

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

### Summary Info Messages

```json Summary Info theme={null}
{
    "type": "summary_info",
    "info": {
        "summary_id": "954zACRVRY6L5DXGPEiQ",
        "video_id": "65_PmYipnpk",
        "type": "youtube",
        "video_title": "Steve Jobs - Courage",
        "language_code": "en"
    }
}
```

### Progress Messages

```json Progress Update theme={null}
{
    "type": "summary_progress",
    "info": {
        "progress": 0.37,
        "speed": "",
        "eta": ""
    }
}
```

<Note>
  The `speed` and `eta` fields are currently not used and will return empty strings.
</Note>