Summaries

get /summaries

List summaries

List all summarries for your videos in a project.

videoId string

Use this parameter to filter for a summary that belongs to a specific video.

origin string

Use this parameter to filter for summaries based on the way they were created: automatically or manually via the API.

Enum: auto

api

sourceStatus string

Use this parameter to filter for summaries based on the current status of the summary source.

These are the available statuses:

missing : the input for a summary is not present. waiting : the input video is being processed and a summary will be generated. failed : a technical issue prevented summary generation. completed : the summary is generated. unprocessable : the API rules the source video to be unsuitable for summary generation. An example for this is an input video that has no audio.

Enum: missing

waiting

failed

completed

unprocessable

sortBy string

Use this parameter to choose which field the API will use to sort the response data. The default is value .

These are the available fields to sort by:

createdAt : Sorts the results based on date and timestamps when summaries were created.
updatedAt : Sorts the results based on date and timestamps when summaries were last updated.
videoId : Sorts the results based on video IDs.

Enum: createdAt

updatedAt

videoId

sortOrder string

Use this parameter to sort results. asc is ascending and sorts from A to Z. desc is descending and sorts from Z to A.

Enum: asc

desc

currentPage int

Choose the number of search results to return per page. Minimum value: 1

Default: 1

pageSize int

Results per page. Allowed values 1-100, default is 25.

Default: 25

Responses

Created

Response body Headers

data array required

An array of summary objects.

pagination object (Pagination) required

Example: { "itemsTotal": 123, "pagesTotal": 7, "pageSize": 20, "currentPage": 3, "currentPageItems": 20, "links": { "first": { "rel": "first", "uri": "/videos/search?currentPage=1&pageSize=20" }, "previous": { "rel": "previous", "uri": "/videos/search?currentPage=2&pageSize=20" }, "next": { "rel": "next", "uri": "/videos/search?currentPage=4&pageSize=20" }, "last": { "rel": "last", "uri": "/videos/search?currentPage=6&pageSize=20" } } }

itemsTotal int

Total number of items that exist.

pagesTotal int

Number of items listed in the current page.

pageSize int

Maximum number of item per page.

currentPage int

The current page index.

currentPageItems int

The number of items on the current page.

links array required

X-RateLimit-Limit int

The request limit per minute.

X-RateLimit-Remaining int

The number of available requests left for the current time window.

X-RateLimit-Retry-After int

The number of seconds left until the current rate limit window resets.

Response examples

Created

{
  "data": [
    {
      "summaryId": "summary_1CGHWuXjhxmeH4WiZ51234",
      "createdAt": "2024-07-14T23:36:07+00:00",
      "updatedAt": "2024-07-14T23:36:07+00:00",
      "videoId": "vilkR8K3N7yrRcxcMt91234",
      "origin": "auto",
      "sourceStatus": "completed"
    },
    {
      "summaryId": "summary_123HWuXjhxmeH4WiZ55678",
      "createdAt": "2024-07-15T23:36:07+00:00",
      "updatedAt": "2024-07-15T23:36:07+00:00",
      "videoId": "vibaBXK3N7yrRcxcMt95678",
      "origin": "auto",
      "sourceStatus": "waiting"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 25,
    "pagesTotal": 1,
    "itemsTotal": 11,
    "currentPageItems": 11,
    "links": [
      {
        "rel": "self",
        "uri": "https://ws.api.video/summaries?currentPage=1"
      },
      {
        "rel": "first",
        "uri": "https://ws.api.video/summaries?currentPage=1"
      },
      {
        "rel": "last",
        "uri": "https://ws.api.video/summaries?currentPage=1"
      }
    ]
  }
}

post /summaries

Generate video summary

Generate an abstract and key takeaways for a video.

videoId string required

Create a summary of a video using the video ID.

Example: "vi4k0jvEUuaTdRAEjQ4Jfrgz"

origin string

Use this parameter to define how the API generates the summary. The only allowed value is auto , which means that the API generates a summary automatically.

If you do not set this parameter, the API will not generate a summary automatically .

In this case, sourceStatus will return missing , and you have to manually add a summary using the PATCH /summaries/{summaryId}/source endpoint operation.

Enum: auto
Example: "auto"

attributes array

Use this parameter to define the elements of a summary that you want to generate. If you do not define this parameter, the API generates a full summary with all attributes. The possible values are abstract and takeaways .

Responses

Created

Response body Headers

summaryId string

The unique identifier of the summary object.

Example: "summary_1CGHWuXjhxmeH4WiZ51234"

createdAt string

Returns the date and time when the summary was created in ATOM date-time format.

Format: date-time
Example: "2024-05-28T11:15:07+00:00"

updatedAt string

Returns the date and time when the summary was last updated in ATOM date-time format.

Format: date-time
Example: "2024-05-28T11:15:07+00:00"

videoId string

The unique identifier of the video object.

Example: "vi4k0jvEUuaTdRAEjQ4Prklg"

origin string

Returns the origin of how the summary was created.

api means that no summary was generated automatically. You can add summary manually using the PATCH /summaries/{summaryId}/source endpoint operation. Until this happens, sourceStatus returns missing .
auto means that the API generated the summary automatically.

Enum: api

auto

sourceStatus string

Returns the current status of summary generation.

Enum: missing

waiting

failed

completed

unprocessable

X-RateLimit-Limit int

The request limit per minute.

X-RateLimit-Remaining int

The number of available requests left for the current time window.

X-RateLimit-Retry-After int

The number of seconds left until the current rate limit window resets.

Conflict

Response body Headers

type string

A link to the error documentation.

title string

A description of the error that occurred.

name string

The name of the parameter that caused the error.

status int

The HTTP status code.

detail string

A solution for the error.

X-RateLimit-Limit int

The request limit per minute.

X-RateLimit-Remaining int

The number of available requests left for the current time window.

X-RateLimit-Retry-After int

The number of seconds left until the current rate limit window resets.

Request examples

{
  "videoId": "vi4k0jvEUuaTdRAEjQ4Jfrgz",
  "origin": "auto",
  "attributes": [
    "abstract"
  ]
}

Response examples

Created

{
  "summaryId": "summary_1CGHWuXjhxmeH4WiZ51234",
  "createdAt": "2024-07-14T23:36:07+00:00",
  "updatedAt": "2024-07-14T23:36:07+00:00",
  "videoId": "vilkR8K3N7yrRcxcMt91234",
  "origin": "auto",
  "sourceStatus": "completed"
}

Conflict

{
  "type": "https://docs.api.video/reference/summary-already-exists",
  "title": "A summary already exists or is being created on this video.",
  "status": 409,
  "detail": "You can delete the existing summary and generate a new one.",
  "name": "videoId"
}

delete /summaries/{summaryId}

Delete video summary

Delete a summary tied to a video.

summaryId string required

The unique identifier of the summary you want to delete.

Responses

No Content

Response body Headers

This response is empty

X-RateLimit-Limit int

The request limit per minute.

X-RateLimit-Remaining int

The number of available requests left for the current time window.

X-RateLimit-Retry-After int

The number of seconds left until the current rate limit window resets.

Response examples

get /summaries/{summaryId}/source

Get summary details

Get all details for a summary

summaryId string required

The unique identifier of the summary source you want to retrieve.

Responses

Success

Response body Headers

abstract string

A short outline of the contents of the video. The length of an abstract depends on the amount of content in a video that can be transcribed. The API condenses the contents into minimum 20, maximum 300 words.

Example: "In this lecture, we discuss how complicated quantum theory is, using the famous example of Schrödingers cat. We also discuss practical applications like quantum computing."

takeaways array

A list of 3 key points from the video, in chronological order.

Example: [ "Quantum theory is complicated.", "Schrödinger's cat is neither dead, nor alive.", "Quantum computers are super cool." ]

X-RateLimit-Limit int

The request limit per minute.

X-RateLimit-Remaining int

The number of available requests left for the current time window.

X-RateLimit-Retry-After int

The number of seconds left until the current rate limit window resets.

Not Found

Response body Headers

type string

A link to the error documentation.

title string

A description of the error that occurred.

name string

The name of the parameter that caused the error.

status int

The HTTP status code.

X-RateLimit-Limit int

The request limit per minute.

X-RateLimit-Remaining int

The number of available requests left for the current time window.

X-RateLimit-Retry-After int

The number of seconds left until the current rate limit window resets.

Response examples

Success

{
  "abstract": "In this lecture, we discuss how complicated quantum theory is, using the famous example of Schrödingers cat. We also discuss practical applications like quantum computing.",
  "takeaways": [
    "Quantum theory is complicated.",
    "Schrödinger's cat is neither dead, nor alive.",
    "Quantum computers are super cool."
  ]
}

Not Found

{
  "type": "https://docs.api.video/reference/resource-not-found",
  "title": "The requested resource was not found.",
  "name": "summaryId",
  "status": 404
}

patch /summaries/{summaryId}/source

Update summary details

Update details for a summary.

abstract string

A short outline of the contents of the video.

Example: "In this lecture, we discuss how complicated quantum theory is, using the famous example of Schrödingers cat. We also discuss practical applications like quantum computing."

takeaways array

A list of 3 key points from the video, in chronological order.

Example: [ "Quantum theory is complicated.", "Schrödinger's cat is neither dead, nor alive.", "Quantum computers are super cool." ]

summaryId string required

The unique identifier of the summary source you want to update.

Responses

Created

Response body Headers

abstract string

Example: "In this lecture, we discuss how complicated quantum theory is, using the famous example of Schrödingers cat. We also discuss practical applications like quantum computing."

takeaways array

A list of 3 key points from the video, in chronological order.

Example: [ "Quantum theory is complicated.", "Schrödinger's cat is neither dead, nor alive.", "Quantum computers are super cool." ]

X-RateLimit-Limit int

The request limit per minute.

X-RateLimit-Remaining int

The number of available requests left for the current time window.

X-RateLimit-Retry-After int

The number of seconds left until the current rate limit window resets.

Conflict

Response body Headers

type string

A link to the error documentation.

title string

A description of the error that occurred.

name string

The name of the parameter that caused the error.

status int

The HTTP status code.

detail string

A solution for the error.

X-RateLimit-Limit int

The request limit per minute.

X-RateLimit-Remaining int

The number of available requests left for the current time window.

X-RateLimit-Retry-After int

The number of seconds left until the current rate limit window resets.

Request examples

{
  "abstract": "In this lecture, we discuss how complicated quantum theory is, using the famous example of Schrödingers cat. We also discuss practical applications like quantum computing.",
  "takeaways": [
    "Quantum theory is complicated.",
    "Schrödinger's cat is neither dead, nor alive.",
    "Quantum computers are super cool."
  ]
}

Response examples

Created

{
  "abstract": "In this lecture, we discuss how complicated quantum theory is, using the famous example of Schrödingers cat. We also discuss practical applications like quantum computing.",
  "takeaways": [
    "Quantum theory is complicated.",
    "Schrödinger's cat is neither dead, nor alive.",
    "Quantum computers are super cool."
  ]
}

Conflict

{
  "type": "https://docs.api.video/reference/summary-already-exists",
  "title": "A summary already exists or is being created on this video.",
  "status": 409,
  "detail": "You can delete the existing summary and generate a new one."
}