Merge pull request #95 from apivideo/add-summary-feature-docs

Add summary feature

CHANGELOG.md

@@ -1,6 +1,9 @@
 # Changelog
 All changes to this project will be documented in this file.
 
+## [1.4.5] - 2024-10-21
+- Add summary feature
+
 ## [1.4.4] - 2024-10-08
 - Add transcript feature
 

README.md

@@ -24,6 +24,7 @@
     - [ChaptersApi](#chaptersapi)
     - [LiveStreamsApi](#livestreamsapi)
     - [PlayerThemesApi](#playerthemesapi)
+    - [SummariesApi](#summariesapi)
     - [TagsApi](#tagsapi)
     - [UploadTokensApi](#uploadtokensapi)
     - [VideosApi](#videosapi)
@@ -186,6 +187,17 @@ Method | Description | HTTP request
 [**deleteLogo()**](https://github.com/apivideo/api.video-php-client/blob/main/docs/Api/PlayerThemesApi.md#deleteLogo) | Delete logo | **DELETE** `/players/{playerId}/logo`
 
 
+#### SummariesApi
+
+Method | Description | HTTP request
+------------- | ------------- | -------------
+[**create()**](https://github.com/apivideo/api.video-php-client/blob/main/docs/Api/SummariesApi.md#create) | Generate video summary | **POST** `/summaries`
+[**update()**](https://github.com/apivideo/api.video-php-client/blob/main/docs/Api/SummariesApi.md#update) | Update summary details | **PATCH** `/summaries/{summaryId}/source`
+[**delete()**](https://github.com/apivideo/api.video-php-client/blob/main/docs/Api/SummariesApi.md#delete) | Delete video summary | **DELETE** `/summaries/{summaryId}`
+[**list()**](https://github.com/apivideo/api.video-php-client/blob/main/docs/Api/SummariesApi.md#list) | List summaries | **GET** `/summaries`
+[**getSummarySource()**](https://github.com/apivideo/api.video-php-client/blob/main/docs/Api/SummariesApi.md#getSummarySource) | Get summary details | **GET** `/summaries/{summaryId}/source`
+
+
 #### TagsApi
 
 Method | Description | HTTP request
@@ -266,6 +278,7 @@ Method | Description | HTTP request
  - [CaptionsUpdatePayload](https://github.com/apivideo/api.video-php-client/blob/main/docs/Model/CaptionsUpdatePayload.md)
  - [Chapter](https://github.com/apivideo/api.video-php-client/blob/main/docs/Model/Chapter.md)
  - [ChaptersListResponse](https://github.com/apivideo/api.video-php-client/blob/main/docs/Model/ChaptersListResponse.md)
+ - [ConflictError](https://github.com/apivideo/api.video-php-client/blob/main/docs/Model/ConflictError.md)
  - [DiscardedVideoUpdatePayload](https://github.com/apivideo/api.video-php-client/blob/main/docs/Model/DiscardedVideoUpdatePayload.md)
  - [FilterBy](https://github.com/apivideo/api.video-php-client/blob/main/docs/Model/FilterBy.md)
  - [FilterBy1](https://github.com/apivideo/api.video-php-client/blob/main/docs/Model/FilterBy1.md)
@@ -293,6 +306,11 @@ Method | Description | HTTP request
  - [RefreshTokenPayload](https://github.com/apivideo/api.video-php-client/blob/main/docs/Model/RefreshTokenPayload.md)
  - [RestreamsRequestObject](https://github.com/apivideo/api.video-php-client/blob/main/docs/Model/RestreamsRequestObject.md)
  - [RestreamsResponseObject](https://github.com/apivideo/api.video-php-client/blob/main/docs/Model/RestreamsResponseObject.md)
+ - [SummariesListResponse](https://github.com/apivideo/api.video-php-client/blob/main/docs/Model/SummariesListResponse.md)
+ - [Summary](https://github.com/apivideo/api.video-php-client/blob/main/docs/Model/Summary.md)
+ - [SummaryCreationPayload](https://github.com/apivideo/api.video-php-client/blob/main/docs/Model/SummaryCreationPayload.md)
+ - [SummarySource](https://github.com/apivideo/api.video-php-client/blob/main/docs/Model/SummarySource.md)
+ - [SummaryUpdatePayload](https://github.com/apivideo/api.video-php-client/blob/main/docs/Model/SummaryUpdatePayload.md)
  - [TokenCreationPayload](https://github.com/apivideo/api.video-php-client/blob/main/docs/Model/TokenCreationPayload.md)
  - [TokenListResponse](https://github.com/apivideo/api.video-php-client/blob/main/docs/Model/TokenListResponse.md)
  - [TooManyRequests](https://github.com/apivideo/api.video-php-client/blob/main/docs/Model/TooManyRequests.md)

docs/Api/SummariesApi.md

@@ -0,0 +1,150 @@
+# ApiVideo\Client\Api\SummariesApi
+
+All URIs are relative to https://ws.api.video.
+
+Method | Description | HTTP request
+------------- | ------------- | -------------
+[**create()**](SummariesApi.md#create) | Generate video summary | **POST** /summaries
+[**update()**](SummariesApi.md#update) | Update summary details | **PATCH** /summaries/{summaryId}/source
+[**delete()**](SummariesApi.md#delete) | Delete video summary | **DELETE** /summaries/{summaryId}
+[**list()**](SummariesApi.md#list) | List summaries | **GET** /summaries
+[**getSummarySource()**](SummariesApi.md#getSummarySource) | Get summary details | **GET** /summaries/{summaryId}/source
+
+
+## **`create()` - Generate video summary**
+
+
+
+Generate a title, abstract, and key takeaways for a video.
+
+### Arguments
+
+
+
+Name | Type | Description | Notes
+------------- | ------------- | ------------- | -------------
+ `summaryCreationPayload` | [**\ApiVideo\Client\Model\SummaryCreationPayload**](../Model/SummaryCreationPayload.md)|  |
+
+
+
+
+### Return type
+
+[**\ApiVideo\Client\Model\Summary**](../Model/Summary.md)
+
+
+
+
+
+## **`update()` - Update summary details**
+
+
+
+Update details for a summary. Note that this operation is only allowed for summary objects where `sourceStatus` is `missing`.
+
+### Arguments
+
+
+
+Name | Type | Description | Notes
+------------- | ------------- | ------------- | -------------
+ `summaryId` | **string**| The unique identifier of the summary source you want to update. |
+ `summaryUpdatePayload` | [**\ApiVideo\Client\Model\SummaryUpdatePayload**](../Model/SummaryUpdatePayload.md)|  |
+
+
+
+
+### Return type
+
+[**\ApiVideo\Client\Model\SummarySource**](../Model/SummarySource.md)
+
+
+
+
+
+## **`delete()` - Delete video summary**
+
+
+
+Delete a summary tied to a video.
+
+### Arguments
+
+
+
+Name | Type | Description | Notes
+------------- | ------------- | ------------- | -------------
+ `summaryId` | **string**| The unique identifier of the summary you want to delete. |
+
+
+
+
+### Return type
+
+void (empty response body)
+
+
+
+
+
+## **`list()` - List summaries**
+
+
+
+List all summarries for your videos in a project.
+
+### Arguments
+
+
+
+
+
+Note: `queryParams` argument is an associative array with the keys listed below.
+
+Name | Type | Description | Notes
+------------- | ------------- | ------------- | ------------- 
+ `videoId` | **string**| Use this parameter to filter for a summary that belongs to a specific video. | [optional]
+ `origin` | **string**| Use this parameter to filter for summaries based on the way they were created: automatically or manually via the API. | [optional]
+ `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. | [optional]
+ `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. | [optional]
+ `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. | [optional]
+ `currentPage` | **int**| Choose the number of search results to return per page. Minimum value: 1 | [optional] [default to 1]
+ `pageSize` | **int**| Results per page. Allowed values 1-100, default is 25. | [optional] [default to 25]
+
+
+
+
+
+
+### Return type
+
+[**\ApiVideo\Client\Model\SummariesListResponse**](../Model/SummariesListResponse.md)
+
+
+
+
+
+## **`getSummarySource()` - Get summary details**
+
+
+
+Get all details for a summary.
+
+### Arguments
+
+
+
+Name | Type | Description | Notes
+------------- | ------------- | ------------- | -------------
+ `summaryId` | **string**| The unique identifier of the summary source you want to retrieve. |
+
+
+
+
+### Return type
+
+[**\ApiVideo\Client\Model\SummarySource**](../Model/SummarySource.md)
+
+
+
+

docs/Model/ConflictError.md

@@ -0,0 +1,13 @@
+# # ConflictError
+
+## Properties
+
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**type** | **string** | A link to the error documentation. | [optional]
+**title** | **string** | A description of the error that occurred. | [optional]
+**name** | **string** | The name of the parameter that caused the error. | [optional]
+**status** | **int** | The HTTP status code. | [optional]
+**detail** | **string** | A solution for the error. | [optional]
+
+[[Back to Model list]](../../README.md#models) [[Back to API list]](../../README.md#endpoints) [[Back to README]](../../README.md)

docs/Model/NotFound.md

@@ -4,9 +4,9 @@
 
 Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
-**type** | **string** |  | [optional]
-**title** | **string** |  | [optional]
-**name** | **string** |  | [optional]
-**status** | **int** |  | [optional]
+**type** | **string** | A link to the error documentation. | [optional]
+**title** | **string** | A description of the error that occurred. | [optional]
+**name** | **string** | The name of the parameter that caused the error. | [optional]
+**status** | **int** | The HTTP status code. | [optional]
 
 [[Back to Model list]](../../README.md#models) [[Back to API list]](../../README.md#endpoints) [[Back to README]](../../README.md)

docs/Model/SummariesListResponse.md

@@ -0,0 +1,10 @@
+# # SummariesListResponse
+
+## Properties
+
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**data** | [**\ApiVideo\Client\Model\Summary[]**](Summary.md) | An array of summary objects. |
+**pagination** | [**\ApiVideo\Client\Model\Pagination**](Pagination.md) |  |
+
+[[Back to Model list]](../../README.md#models) [[Back to API list]](../../README.md#endpoints) [[Back to README]](../../README.md)

docs/Model/Summary.md

@@ -0,0 +1,14 @@
+# # Summary
+
+## Properties
+
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**summaryId** | **string** | The unique identifier of the summary object. | [optional]
+**createdAt** | [**\DateTime**](\DateTime.md) | Returns the date and time when the summary was created in ATOM date-time format. | [optional]
+**updatedAt** | [**\DateTime**](\DateTime.md) | Returns the date and time when the summary was last updated in ATOM date-time format. | [optional]
+**videoId** | **string** | The unique identifier of the video object. | [optional]
+**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. | [optional]
+**sourceStatus** | **string** | 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. | [optional]
+
+[[Back to Model list]](../../README.md#models) [[Back to API list]](../../README.md#endpoints) [[Back to README]](../../README.md)

docs/Model/SummaryCreationPayload.md

@@ -0,0 +1,10 @@
+# # SummaryCreationPayload
+
+## Properties
+
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**videoId** | **string** | Create a summary of a video using the video ID. |
+**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. | [optional]
+
+[[Back to Model list]](../../README.md#models) [[Back to API list]](../../README.md#endpoints) [[Back to README]](../../README.md)

docs/Model/SummarySource.md

@@ -0,0 +1,11 @@
+# # SummarySource
+
+## Properties
+
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**title** | **string** | A video title, based on the contents of the video. | [optional]
+**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. | [optional]
+**takeaways** | **string[]** | A list of 3 key points from the video, in chronological order. | [optional]
+
+[[Back to Model list]](../../README.md#models) [[Back to API list]](../../README.md#endpoints) [[Back to README]](../../README.md)

docs/Model/SummaryUpdatePayload.md

@@ -0,0 +1,11 @@
+# # SummaryUpdatePayload
+
+## Properties
+
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**title** | **string** | A video title, based on the contents of the video. | [optional]
+**abstract** | **string** | A short outline of the contents of the video. | [optional]
+**takeaways** | **string[]** | A list of 3 key points from the video, in chronological order. | [optional]
+
+[[Back to Model list]](../../README.md#models) [[Back to API list]](../../README.md#endpoints) [[Back to README]](../../README.md)

docs/Model/VideoCreationPayload.md

@@ -17,5 +17,6 @@ Name | Type | Description | Notes
 **watermark** | [**\ApiVideo\Client\Model\VideoWatermark**](VideoWatermark.md) |  | [optional]
 **language** | **string** | Use this parameter to set the language of the video. When this parameter is set, the API creates a transcript of the video using the language you specify. You must use the [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag) format.  `language` is a permanent attribute of the video. You can update it to another language using the [`PATCH /videos/{videoId}`](https://docs.api.video/reference/api/Videos#update-a-video-object) operation. This triggers the API to generate a new transcript using a different language. | [optional]
 **transcript** | **bool** | Use this parameter to enable transcription.   - When `true`, the API generates a transcript for the video. - The default value is `false`. - If you define a video language using the `language` parameter, the API uses that language to transcribe the video. If you do not define a language, the API detects it based on the video.  - When the API generates a transcript, it will be available as a caption for the video. | [optional]
+**transcriptSummary** | **bool** | Use this parameter to enable summarization. We recommend using this parameter together with `transcript: true`.  - When `true`, the API generates a summary for the video, based on the transcription. - The default value is `false`. - If you define a video language using the `language` parameter, the API uses that language to summarize the video. If you do not define a language, the API detects it based on the video. | [optional]
 
 [[Back to Model list]](../../README.md#models) [[Back to API list]](../../README.md#endpoints) [[Back to README]](../../README.md)

docs/Model/VideoUpdatePayload.md

@@ -14,5 +14,6 @@ Name | Type | Description | Notes
 **metadata** | [**\ApiVideo\Client\Model\Metadata[]**](Metadata.md) | A list (array) of dictionaries where each dictionary contains a key value pair that describes the video. As with tags, you must send the complete list of metadata you want as whatever you send here will overwrite the existing metadata for the video. | [optional]
 **language** | **string** | Use this parameter to set the language of the video. When this parameter is set, the API creates a transcript of the video using the language you specify. You must use the [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag) format.  `language` is a permanent attribute of the video. You can update it to another language using the [`PATCH /videos/{videoId}`](https://docs.api.video/reference/api/Videos#update-a-video-object) operation. This triggers the API to generate a new transcript using a different language. | [optional]
 **transcript** | **bool** | Use this parameter to enable transcription.   - When `true`, the API generates a transcript for the video. - The default value is `false`. - If you define a video language using the `language` parameter, the API uses that language to transcribe the video. If you do not define a language, the API detects it based on the video.  - When the API generates a transcript, it will be available as a caption for the video. | [optional]
+**transcriptSummary** | **bool** | Use this parameter to enable summarization.   - When `true`, the API generates a summary for the video, based on the transcription. - The default value is `false`. - If you define a video language using the `language` parameter, the API uses that language to summarize the video. If you do not define a language, the API detects it based on the video. | [optional]
 
 [[Back to Model list]](../../README.md#models) [[Back to API list]](../../README.md#endpoints) [[Back to README]](../../README.md)