API.Video Summaries API

openapi: 3.2.0
info:
  title: api.video Summaries API
  description: api.video is an API that encodes on the go to facilitate immediate playback, enhancing viewer streaming experiences across multiple devices and platforms. You can stream live or on-demand online videos within minutes.
  version: '1'
servers:
- url: https://ws.api.video
  description: Production server
- url: https://sandbox.api.video
  description: Test server `all videos are watermarked, and deleted after 24 hours.
tags:
- name: Summaries
paths:
  /summaries:
    post:
      tags:
      - Summaries
      summary: Generate video summary
      description: Generate an abstract and key takeaways for a video.
      x-client-action: create
      x-client-description:
        default: Generate an abstract and key takeaways for a video.
      operationId: POST_summaries
      security:
      - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/summary-creation-payload'
      responses:
        '201':
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: The request limit per minute.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of available requests left for the current time window.
            X-RateLimit-Retry-After:
              schema:
                type: integer
              description: The number of seconds left until the current rate limit window resets.
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/summary'
              examples:
                Summary created:
                  value:
                    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
        '409':
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: The request limit per minute.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of available requests left for the current time window.
            X-RateLimit-Retry-After:
              schema:
                type: integer
              description: The number of seconds left until the current rate limit window resets.
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conflict-error'
              examples:
                Summary already exists:
                  value:
                    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
    get:
      tags:
      - Summaries
      summary: List summaries
      description: List all summarries for your videos in a project.
      x-client-action: list
      x-client-description:
        default: List all summarries for your videos in a project.
      operationId: GET_summaries
      parameters:
      - name: videoId
        in: query
        required: false
        description: Use this parameter to filter for a summary that belongs to a specific video.
        schema:
          type: string
        example: vilkR8K3N7yrRcxcMt91234
      - name: origin
        in: query
        required: false
        description: 'Use this parameter to filter for summaries based on the way they were created: automatically or manually via the API.'
        schema:
          type: string
          enum:
          - auto
          - api
        example: auto
      - name: sourceStatus
        in: query
        required: false
        description: '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.

          '
        schema:
          type: string
          enum:
          - missing
          - waiting
          - failed
          - completed
          - unprocessable
        example: auto
      - name: sortBy
        in: query
        description: '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.

          '
        required: false
        style: form
        explode: true
        schema:
          type: string
          enum:
          - createdAt
          - updatedAt
          - videoId
        example: createdAt
      - name: sortOrder
        in: query
        description: Use this parameter to sort results. `asc` is ascending and sorts from A to Z. `desc` is descending and sorts from Z to A.
        required: false
        style: form
        explode: true
        schema:
          type: string
          enum:
          - asc
          - desc
        example: asc
      - $ref: '#/components/parameters/current-page'
      - $ref: '#/components/parameters/page-size'
      x-group-parameters: true
      x-client-paginated: true
      responses:
        '200':
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: The request limit per minute.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of available requests left for the current time window.
            X-RateLimit-Retry-After:
              schema:
                type: integer
              description: The number of seconds left until the current rate limit window resets.
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/summaries-list-response'
              examples:
                List all summaries:
                  value:
                    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
  /summaries/{summaryId}:
    delete:
      tags:
      - Summaries
      summary: Delete video summary
      description: Delete a summary tied to a video.
      x-client-action: delete
      x-client-description:
        default: Delete a summary tied to a video.
      operationId: DELETE_summaries-summaryId
      security:
      - apiKey: []
      parameters:
      - name: summaryId
        in: path
        description: The unique identifier of the summary you want to delete.
        required: true
        style: simple
        explode: false
        schema:
          type: string
        example: summary_1CGHWuXjhxmeH4WiZ51234
      responses:
        '204':
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: The request limit per minute.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of available requests left for the current time window.
            X-RateLimit-Retry-After:
              schema:
                type: integer
              description: The number of seconds left until the current rate limit window resets.
          description: No Content
  /summaries/{summaryId}/source:
    get:
      tags:
      - Summaries
      summary: Get summary details
      description: Get all details for a summary
      x-client-action: getSummarySource
      x-client-description:
        default: Get all details for a summary.
      operationId: GET_summaries-summaryId-source
      security:
      - apiKey: []
      parameters:
      - name: summaryId
        in: path
        description: The unique identifier of the summary source you want to retrieve.
        required: true
        style: simple
        explode: false
        schema:
          type: string
        example: summary_1CGHWuXjhxmeH4WiZ51234
      responses:
        '200':
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: The request limit per minute.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of available requests left for the current time window.
            X-RateLimit-Retry-After:
              schema:
                type: integer
              description: The number of seconds left until the current rate limit window resets.
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/summary-source'
        '404':
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: The request limit per minute.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of available requests left for the current time window.
            X-RateLimit-Retry-After:
              schema:
                type: integer
              description: The number of seconds left until the current rate limit window resets.
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/not-found'
              examples:
                response:
                  value:
                    type: https://docs.api.video/reference/resource-not-found
                    title: The requested resource was not found.
                    name: summaryId
                    status: 404
    patch:
      tags:
      - Summaries
      summary: Update summary details
      description: Update details for a summary.
      x-client-action: update
      x-client-description:
        default: Update details for a summary.
      operationId: PATCH_summaries-summaryId-source
      parameters:
      - name: summaryId
        in: path
        description: The unique identifier of the summary source you want to update.
        required: true
        style: simple
        explode: false
        schema:
          type: string
        example: summary_1CGHWuXjhxmeH4WiZ51234
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/summary-update-payload'
      responses:
        '201':
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: The request limit per minute.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of available requests left for the current time window.
            X-RateLimit-Retry-After:
              schema:
                type: integer
              description: The number of seconds left until the current rate limit window resets.
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/summary-source'
        '409':
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: The request limit per minute.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of available requests left for the current time window.
            X-RateLimit-Retry-After:
              schema:
                type: integer
              description: The number of seconds left until the current rate limit window resets.
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conflict-error'
              examples:
                Summary generation still in progress:
                  value:
                    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.
components:
  parameters:
    current-page:
      name: currentPage
      in: query
      description: 'Choose the number of search results to return per page. Minimum value: 1'
      required: false
      style: form
      explode: true
      schema:
        type: integer
        default: 1
      example: 2
    page-size:
      name: pageSize
      in: query
      description: Results per page. Allowed values 1-100, default is 25.
      required: false
      style: form
      explode: true
      schema:
        type: integer
        default: 25
      example: 30
  schemas:
    summary-source:
      type: object
      properties:
        abstract:
          type: string
          description: 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:
          type: array
          description: A list of 3 key points from the video, in chronological order.
          maxItems: 3
          items:
            type: string
          example:
          - Quantum theory is complicated.
          - Schrödinger's cat is neither dead, nor alive.
          - Quantum computers are super cool.
    conflict-error:
      type: object
      properties:
        type:
          description: A link to the error documentation.
          type: string
        title:
          description: A description of the error that occurred.
          type: string
        name:
          description: The name of the parameter that caused the error.
          type: string
        status:
          description: The HTTP status code.
          type: integer
        detail:
          description: A solution for the error.
          type: string
    summary-creation-payload:
      required:
      - videoId
      type: object
      properties:
        videoId:
          type: string
          description: Create a summary of a video using the video ID.
          example: vi4k0jvEUuaTdRAEjQ4Jfrgz
        origin:
          type: string
          enum:
          - auto
          description: '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.'
          example: auto
        attributes:
          description: 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`.
          type: array
          items:
            type: string
            enum:
            - abstract
            - takeaways
    pagination-link:
      title: PaginationLink
      type: object
      properties:
        rel:
          type: string
        uri:
          type: string
          format: uri
    summary:
      type: object
      properties:
        summaryId:
          type: string
          description: The unique identifier of the summary object.
          example: summary_1CGHWuXjhxmeH4WiZ51234
        createdAt:
          description: Returns the date and time when the summary was created in ATOM date-time format.
          type: string
          format: date-time
          example: '2024-05-28T11:15:07+00:00'
        updatedAt:
          description: Returns the date and time when the summary was last updated in ATOM date-time format.
          type: string
          format: date-time
          example: '2024-05-28T11:15:07+00:00'
        videoId:
          type: string
          description: The unique identifier of the video object.
          example: vi4k0jvEUuaTdRAEjQ4Prklg
        origin:
          type: string
          enum:
          - api
          - auto
          description: '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.'
        sourceStatus:
          type: string
          description: 'Returns the current status of summary generation.


            `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
    summaries-list-response:
      type: object
      title: Summaries
      properties:
        data:
          type: array
          description: An array of summary objects.
          items:
            $ref: '#/components/schemas/summary'
        pagination:
          $ref: '#/components/schemas/pagination'
      required:
      - data
      - pagination
    pagination:
      title: Pagination
      required:
      - links
      type: object
      properties:
        itemsTotal:
          type: integer
          description: Total number of items that exist.
          readOnly: true
        pagesTotal:
          type: integer
          description: Number of items listed in the current page.
          readOnly: true
        pageSize:
          type: integer
          description: Maximum number of item per page.
          readOnly: true
        currentPage:
          type: integer
          description: The current page index.
          readOnly: true
        currentPageItems:
          type: integer
          description: The number of items on the current page.
          readOnly: true
        links:
          type: array
          items:
            $ref: '#/components/schemas/pagination-link'
      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
    not-found:
      title: NotFound
      type: object
      properties:
        type:
          description: A link to the error documentation.
          type: string
        title:
          description: A description of the error that occurred.
          type: string
        name:
          description: The name of the parameter that caused the error.
          type: string
        status:
          description: The HTTP status code.
          type: integer
    summary-update-payload:
      type: object
      properties:
        abstract:
          type: string
          description: 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:
          type: array
          description: A list of 3 key points from the video, in chronological order.
          maxItems: 3
          items:
            type: string
          example:
          - Quantum theory is complicated.
          - Schrödinger's cat is neither dead, nor alive.
          - Quantum computers are super cool.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKey:
      type: http
      scheme: basic
x-stoplight:
  id: ybzk39fiws46g
x-client-base-paths:
  production: https://ws.api.video
  sandbox: https://sandbox.api.video
x-doctave:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true
  samples-languages:
  - curl
  - go
  - node
  - php
  - python
x-provenance:
  method: harvested
  publisher: API.Video
  source: https://docs.api.video/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)