Merge pull request #129 from apivideo/ai-summary-updates

Update Summary endpoints

CHANGELOG.md

@@ -1,6 +1,9 @@
 # Changelog
 All changes to this project will be documented in this file.
 
+## [1.6.7] - 2024-11-06
+- AI summary updates
+
 ## [1.6.6] - 2024-11-04
 - Analytics updates (ccv, views, ...)
 

README.md

@@ -72,7 +72,7 @@ Add this dependency to your project's POM:
 <dependency>
   <groupId>video.api</groupId>
   <artifactId>android-api-client</artifactId>
-  <version>1.6.6</version>
+  <version>1.6.7</version>
   <scope>compile</scope>
 </dependency>
 ```
@@ -82,7 +82,7 @@ Add this dependency to your project's POM:
 Add this dependency to your project's build file:
 
 ```groovy
-implementation "video.api:android-api-client:1.6.6"
+implementation "video.api:android-api-client:1.6.7"
 ```
 
 #### Others
@@ -95,7 +95,7 @@ mvn clean package
 
 Then manually install the following JARs:
 
-* `target/android-api-client-1.6.6.jar`
+* `target/android-api-client-1.6.7.jar`
 * `target/lib/*.jar`
 
 ### Code sample

api/openapi.yaml

@@ -1339,7 +1339,7 @@ paths:
       x-client-paginated: true
       x-accepts: application/json
     post:
-      description: Generate a title, abstract, and key takeaways for a video.
+      description: Generate an abstract and key takeaways for a video.
       operationId: POST_summaries
       requestBody:
         content:
@@ -1427,7 +1427,7 @@ paths:
       - Summaries
       x-client-action: create
       x-client-description:
-        default: Generate a title, abstract, and key takeaways for a video.
+        default: Generate an abstract and key takeaways for a video.
       x-contentType: application/json
       x-accepts: application/json
   /summaries/{summaryId}:
@@ -1563,8 +1563,7 @@ paths:
         default: Get all details for a summary.
       x-accepts: application/json
     patch:
-      description: Update details for a summary. Note that this operation is only
-        allowed for summary objects where `sourceStatus` is `missing`.
+      description: Update details for a summary.
       operationId: PATCH_summaries-summaryId-source
       parameters:
       - description: The unique identifier of the summary source you want to update.
@@ -1614,7 +1613,7 @@ paths:
           content:
             application/json:
               examples:
-                Summary already exists:
+                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.
@@ -1650,8 +1649,7 @@ paths:
       - Summaries
       x-client-action: update
       x-client-description:
-        default: Update details for a summary. Note that this operation is only allowed
-          for summary objects where `sourceStatus` is `missing`.
+        default: Update details for a summary.
       x-contentType: application/json
       x-accepts: application/json
   /videos/{videoId}/source:
@@ -16648,6 +16646,10 @@ components:
         playerId: pl45KFKdlddgk654dspkze
         language: en
         transcript: true
+        transcriptSummary: true
+        transcriptSummaryAttributes:
+        - abstract
+        - takeaways
         tags:
         - maths
         - string theory
@@ -16776,6 +16778,16 @@ components:
             - 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.
           type: boolean
+        transcriptSummaryAttributes:
+          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.
+          items:
+            enum:
+            - abstract
+            - takeaways
+            type: string
+          type: array
       required:
       - title
       title: VideoCreationPayload
@@ -16797,15 +16809,21 @@ components:
           - auto
           example: auto
           type: string
+        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.
+          items:
+            enum:
+            - abstract
+            - takeaways
+            type: string
+          type: array
       required:
       - videoId
       type: object
     summary-update-payload:
       properties:
-        title:
-          description: A video title, based on the contents of the video.
-          example: A short lecture on quantum theory
-          type: string
         abstract:
           description: A short outline of the contents of the video.
           example: In this lecture, we discuss how complicated quantum theory is,
@@ -16850,12 +16868,7 @@ components:
         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.
-        title: A short lecture on quantum theory
       properties:
-        title:
-          description: A video title, based on the contents of the video.
-          example: A short lecture on quantum theory
-          type: string
         abstract:
           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
@@ -17028,6 +17041,9 @@ components:
         language: en
         transcript: true
         transcriptSummary: true
+        transcriptSummaryAttributes:
+        - abstract
+        - takeaways
         panoramic: false
         mp4Support: true
         tags:
@@ -17140,6 +17156,16 @@ components:
             \ video. If you do not define a language, the API detects it based on\
             \ the video."
           type: boolean
+        transcriptSummaryAttributes:
+          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.
+          items:
+            enum:
+            - abstract
+            - takeaways
+            type: string
+          type: array
       title: VideoUpdatePayload
       type: object
     discarded-video-update-payload:

build.gradle

@@ -5,7 +5,7 @@ apply plugin: 'maven-publish'
 apply plugin: 'kotlin-android'
 
 group = 'video.api'
-version = '1.6.6'
+version = '1.6.7'
 
 buildscript {
     repositories {

docs/SummariesApi.md

@@ -19,7 +19,7 @@ Method | HTTP request | Description
 
 Generate video summary
 
-Generate a title, abstract, and key takeaways for a video.
+Generate an abstract and key takeaways for a video.
 
 ### Example
 ```java
@@ -45,6 +45,7 @@ public class Example {
 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.
+    summaryCreationPayload.setAttributes(); // 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.
 
 
     try {
@@ -95,7 +96,7 @@ Name | Type | Description  | Notes
 
 Update summary details
 
-Update details for a summary. Note that this operation is only allowed for summary objects where `sourceStatus` is `missing`.
+Update details for a summary.
 
 ### Example
 ```java
@@ -116,7 +117,6 @@ public class Example {
 
     String summaryId = "summary_1CGHWuXjhxmeH4WiZ51234"; // The unique identifier of the summary source you want to update.
     SummaryUpdatePayload summaryUpdatePayload = new SummaryUpdatePayload(); // 
-    summaryUpdatePayload.setTitle("A short lecture on quantum theory"); // A video title, based on the contents of the video.
     summaryUpdatePayload.setAbstract("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."); // A short outline of the contents of the video.
     summaryUpdatePayload.setTakeaways(Arrays.asList("Quantum theory is complicated.","Schrödinger's cat is neither dead, nor alive.","Quantum computers are super cool.")); // A list of 3 key points from the video, in chronological order.
 

docs/SummaryCreationPayload.md

@@ -8,6 +8,7 @@ Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
 **videoId** | **String** | Create a summary of a video using the video ID. | 
 **origin** | [**OriginEnum**](#OriginEnum) | 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]
+**attributes** | [**List<AttributesEnum>**](#List<AttributesEnum>) | 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. |  [optional]
 
 
 
@@ -18,6 +19,15 @@ Name | Value
 AUTO | "auto"
 
 
+
+## Enum: List<AttributesEnum>
+
+Name | Value
+---- | -----
+ABSTRACT | "abstract"
+TAKEAWAYS | "takeaways"
+
+
 ## Implemented Interfaces
 
 * Serializable

docs/SummarySource.md

@@ -6,7 +6,6 @@
 
 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** | **List<String>** | A list of 3 key points from the video, in chronological order. |  [optional]
 

docs/SummaryUpdatePayload.md

@@ -6,7 +6,6 @@
 
 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** | **List<String>** | A list of 3 key points from the video, in chronological order. |  [optional]
 

docs/VideoCreationPayload.md

@@ -20,6 +20,7 @@ Name | Type | Description | Notes
 **language** | [**LanguageEnum**](#LanguageEnum) | 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** | **Boolean** | 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** | **Boolean** | 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]
+**transcriptSummaryAttributes** | [**List<TranscriptSummaryAttributesEnum>**](#List<TranscriptSummaryAttributesEnum>) | 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. |  [optional]
 
 
 
@@ -62,6 +63,15 @@ VI | "vi"
 ZH | "zh"
 
 
+
+## Enum: List<TranscriptSummaryAttributesEnum>
+
+Name | Value
+---- | -----
+ABSTRACT | "abstract"
+TAKEAWAYS | "takeaways"
+
+
 ## Implemented Interfaces
 
 * Serializable

docs/VideoUpdatePayload.md

@@ -17,6 +17,7 @@ Name | Type | Description | Notes
 **language** | [**LanguageEnum**](#LanguageEnum) | 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** | **Boolean** | 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** | **Boolean** | 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]
+**transcriptSummaryAttributes** | [**List<TranscriptSummaryAttributesEnum>**](#List<TranscriptSummaryAttributesEnum>) | 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. |  [optional]
 
 
 
@@ -59,6 +60,15 @@ VI | "vi"
 ZH | "zh"
 
 
+
+## Enum: List<TranscriptSummaryAttributesEnum>
+
+Name | Value
+---- | -----
+ABSTRACT | "abstract"
+TAKEAWAYS | "takeaways"
+
+
 ## Implemented Interfaces
 
 * Serializable

docs/VideosApi.md

@@ -72,6 +72,7 @@ public class Example {
 - 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.
+    videoCreationPayload.setTranscriptSummaryAttributes(); // 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.
 
 
     try {
@@ -458,6 +459,7 @@ public class Example {
 - 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.
+    videoUpdatePayload.setTranscriptSummaryAttributes(); // 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.
 
 
     try {

maven-push.gradle

@@ -18,7 +18,7 @@ apply plugin: 'maven-publish'
 apply plugin: 'signing'
 
 def isReleaseBuild() {
-    return !"1.6.6".contains("SNAPSHOT")
+    return !"1.6.7".contains("SNAPSHOT")
 }
 
 def getReleaseRepositoryUrl() {
@@ -57,7 +57,7 @@ afterEvaluate {
 
                 groupId = "video.api"
                 artifactId = "android-api-client"
-                version = "1.6.6"
+                version = "1.6.7"
 
                 pom {
                     name = "video.api:android-api-client"

pom.xml

@@ -5,7 +5,7 @@
     <artifactId>android-api-client</artifactId>
     <packaging>jar</packaging>
     <name>${project.groupId}:${project.artifactId}</name>
-    <version>1.6.6</version>
+    <version>1.6.7</version>
     <url>https://github.com/apivideo/api.video-android-client</url>
     <description>The official Android api.video client</description>
     <scm>

src/main/java/video/api/client/api/ApiClient.java

@@ -120,7 +120,7 @@ private OkHttpClient initHttpClient(List<Interceptor> interceptors) {
     private void init() {
         verifyingSsl = true;
         json = new JSON();
-        addDefaultHeader("AV-Origin-Client", "android:1.6.6");
+        addDefaultHeader("AV-Origin-Client", "android:1.6.7");
     }
 
     private boolean isValid(String regex, String field) {