Docs

Summaries

Extract summaries from media files

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

Get summary

GET https://videohighlight.com/api-v1/summaries

Path variables

videoId string required
- The video ID for the file.
- For YouTube video this it is the last part of the YouTube URL. For https://www.youtube.com/watch?v=65_PmYipnpk, the videoId is: 65_PmYipnpk
- For Vimeo videos this is the last part of the URL. For https://vimeo.com/318971562, the videoId is: 318971562
- For DailyMotion videos this is the last part of the URL. For https://www.dailymotion.com/video/x8w5pyg, the videoId is: x8w5pyg

Request parameters

type string required
- The media type of the video. It can be youtube, vimeo, dailymotion, or private
languageCode string required
- The language code of the input audio in ISO-639-1 format, like en or en-US
summaryType string required
- The type of the summary. It can be default (for the default Summary) or compressed (for Key Points)

Response

Summary object

{
    "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
}

index The index of the segment in the summary
start_time The start time of the segment in seconds. -1 means that the core concept was not associated with a specific timestamp

Error responses

200 - OK - The summary has been successfully retrieved.
204 - NO_CONTENT - The video has not been summarized yet.
400 - BAD_REQUEST - The request is invalid.
401 - UNAUTHORIZED - The request is unauthorized.
500 - INTERNAL_SERVER_ERROR - The server has encountered an error.

If the video has not been summarized yet, the response will be 204 with no content. Calling the Stream endpoint is required

Stream summary

POST https://videohighlight.com/api-v1/summaries/stream

Current limitation:

The summary stream needs to be called AFTER a transcript stream has been called, or the transcript is available.
- Option 1: Call the /transcripts/stream endpoint first, and after a few seconds, call the /summaries/stream endpoint.
- Option 2: Call the /transcripts/stream endpoint and allow the transcript generation to complete. Call the /summaries/stream after the transcript is available.
- Option 3: Ensure that the 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.

Request body

video_id string required
type string required
- The media type of the video. It can be youtube, vimeo, dailymotion, or private
language_code string required
- The language code of the input audio in ISO-639-1 format, like en or fr
summary_type string required
- The type of the summary. It can be default (for the default Summary) or compressed (for Key Points)
use_sse boolean required
regenerate boolean required

Request body

{
    "video_id": "65_PmYipnpk",
    "type": "youtube",
    "language_code": "en",
    "summary_type": "default",
    "use_sse": true,
    "regenerate": false
}

Responses

Summary Messages

Error Message

{
    "type": "error",
    "info": {
        "type": "[ERROR-FILE-DOWNLOAD]",
        "message": "This video can not be downloaded."
    }
}

Error Message Types

[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 Automatic Speech Recognition (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 connection to the Automatic Speech Recognition (ASR) service has failed
[ERROR-REMOTE-ASR-TIMEOUT] - The connection to the Automatic Speech Recognition (ASR) service has timed out
[ERROR-UNEXPECTED] - An unexpected error has occurred

Summary Segment Message

{
    "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
  }
}

index The index of the segment in the summary
start_time The start time of the segment in seconds. -1 means that the core concept was not associated with a specific timestamp

Semaphore Message

{
    "type": "semaphore",
    "info": {
        "status": "[DONE]"
    }
}

Semaphore Types

[DONE] - The summary has been successfully generated
[INSUFFICIENT_DATA] - The summary has been processed, but there is not sufficient data to complete it (e.g., the video is too short)
[KEEP_ALIVE] - The summary is still being processed

Semaphore Info Message

{
    "type": "summary_info",
    "info": {
        "summary_id": "954zACRVRY6L5DXGPEiQ",
        "video_id": "65_PmYipnpk",
        "type": "youtube",
        "video_title": "Steve Jobs - Courage",
        "language_code": "en"
    }
}

Summary Progress Message

{
    "type": "summary_progress",
    "info": {
        "progress": 0.37,
        "speed": "",
        "eta": ""
    }
}

progress The progress of the summary
speed and eta are not used at the moment

Transcripts Chrome Extension (Screenshots)