Add new webhooks and update guides

apivideo · Nov 13, 2024 · 176e414 · 176e414
1 parent 7a6e4ec
commit 176e414
Show file tree

Hide file tree

Showing 4 changed files with 23 additions and 8 deletions.
diff --git a/reference/create-and-manage-webhooks.md b/reference/create-and-manage-webhooks.md
@@ -16,12 +16,14 @@ Here’s how the webhook flow looks like, using `video.encoding` as an example:
 
 These are the available webhook events:
 
-| Event                              | Triggers when...                                                                                                                                                                                                        |
-| :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`live-stream.broadcast.started`](/reference/api/Webhooks#live-stream-started)    | A live stream broadcast has started.                                                                                                                                                     |
-| [`live-stream.broadcast.ended`](/reference/api/Webhooks#live-stream-ended)      | A live stream broadcast has ended.                                                                                                                                                       |
-| [`video.source.recorded`](/reference/api/Webhooks#video-source-recorded)            | A live stream has been completed and the recording of the live stream is ready to be transcoded. This means that the video in queue for transcoding. |
+| Event                                                                          | Triggers when...                                                                                                                                     |
+|-:------------------------------------------------------------------------------|-:----------------------------------------------------------------------------------------------------------------------------------------------------|
+| [`live-stream.broadcast.started`](/reference/api/Webhooks#live-stream-started) | A live stream broadcast has started.                                                                                                                 |
+| [`live-stream.broadcast.ended`](/reference/api/Webhooks#live-stream-ended)     | A live stream broadcast has ended.                                                                                                                   |
+| [`video.source.recorded`](/reference/api/Webhooks#video-source-recorded)       | A live stream has been completed and the recording of the live stream is ready to be transcoded. This means that the video in queue for transcoding. |
 | [`video.encoding.quality.completed`](/reference/api/Webhooks#video-encoding-completed) | A set quality version of encoding is complete for a video that you uploaded.<br /><br />For each video, the MP4 asset is transcoded only once, hence you only receive one webhook notification for the MP4 asset, with the final source quality. The HLS asset's webhook notification triggers multiple times with each quality from the lowest 240p to the highest, up to 4k, based on the source you uploaded.<br /><br />For example, if you upload a video in 720p quality, you receive 5 webhooks in total:<br /><br />- **1 webhook** with 720p quality for the MP4 encoding<br />- **4 webhooks** for 240p, 360p, 480p, and 720p for the HLS encoding.                          |
+| [`video.caption.generated`](/reference/api/Webhooks#video-caption-generated)   | An automatic caption has been generated.                                                                                                             |
+| [`video.summary.generated`](/reference/api/Webhooks#video-summary-generated)   | An automatic summary has been generated.                                                                                                             |
 
 Check out the [API reference](/reference/api/Webhooks) for detailed descriptions of each webhook event's request headers and payloads.
 

diff --git a/vod/add-captions.md b/vod/add-captions.md
@@ -18,6 +18,12 @@ The captions are uploaded per language. You can upload different captions for ea
 | language | String | A valid language identifier using IETF language tags. You can use primary subtags like `en` (English), extended subtags like `fr-CA` (French, Canada), or region subtags like `zh-Hans-CN` (Simplified Chinese used in the PRC). <br></br>- This parameter **only accepts dashes for separators**, for example `fr-CA`. If you use a different separator in your request, the API returns an error. <br></br>- When the value in your request does not match any covered language, the API returns an error. <br></br>- You can find the list of supported language tags [here](#supported-caption-language-tags). |
 | file     | File   | The video text track in VTT format only.                                                   |
 
+## Generate captions automatically
+
+api.video's AI-driven [transcript generation](/vod/generate-transcripts.md) enables you to automatically create captions for your videos. Your audience will be able to select the generated captions during video playback.
+
+Subscribe to the [`video.caption.generated`](/reference/api/Webhooks#video-caption-generated) webhook to get a notification when an automatically generated caption is complete.
+
 ## Supported caption file formats
 
 Currently only **VTT** file format is supported.

diff --git a/vod/create-summaries.md b/vod/create-summaries.md
@@ -88,6 +88,11 @@ When you define the video `language`, the API creates a summary of the video usi
 
 You can also trigger automatic summarization for already uploaded videos. Use the same parameters in your `PATCH` request to the [Update video object](/reference/api/Videos#update-a-video-object) endpoint.
 
+<Callout pad="2" type="info">
+
+You can subscribe to the [`video.summary.generated`](/reference/api/Webhooks#video-summary-generated) webhook to get a notification when an automatically generated summary is complete.
+</Callout>
+
 ### Manual summarization
 
 This method enables you to control every step of the summary creation. We recommend that you use this method in scenarios where you want to manually create, update, or edit the generated summary.
@@ -121,7 +126,7 @@ The `summary` object returns the status of summary generation in the `sourceStat
 - `missing`: the source for a summary is not present.
 - `waiting` : the source video is being processed and a summary will be generated.
 - `failed`: a technical issue prevented summary generation.
-- `completed`: the summary is generated.
+- `completed`: the summary is generated. Subscribe to the [`video.summary.generated`](/reference/api/Webhooks#video-summary-generated) webhook to get a notification when this happes.
 - `unprocessable`: the source video is unsuitable for summary generation. An example for this is a source video that has no audio, or has less than 50 words.
 
 ## Supported languages

diff --git a/vod/generate-transcripts.md b/vod/generate-transcripts.md
@@ -24,7 +24,7 @@ To enable transcription, set these **optional** parameters when you create a vid
 | `transcript` | `boolean` | When `true`, the API generates a transcript for the video. The default value is `false`.                                                                                                           |
 | `language`   | `string`  | A valid language identifier using [IETF language tags](https://en.wikipedia.org/wiki/IETF_language_tag). You can use primary subtags like `en` or `fr`.<br/><br/>When the value in your request does not match any covered language, the API returns an error. |
 
-The API generates transcripts using the `transcript` parameter. You can define the video `language`, and the API creates a transcript of the video using the language you specify. If you do not specify a language for the video, the API will detect it automatically. 
+The API generates transcripts using the `transcript` parameter. You can define the video `language`, and the API creates a transcript of the video using the language you specify. If you do not specify a language for the video, the API will detect it automatically.
 
 <Callout pad="2" type="info">
 
@@ -43,7 +43,9 @@ When you set the `language` parameter, make sure that it matches the actual lang
 
 `language` is a permanent attribute of a video object. You can update it to another language using the [`PATCH /videos/{videoId}`](/reference/api/Videos#update-a-video-object) operation. This triggers the API to generate a new transcript using a different language.
 
-When the API generates a transcript, it will be available as a caption for your video. Your audience will be able to select during video playback. You can interact with captions generated through transcription using the [Captions endpoints](/reference/api/Captions).
+When the API generates a transcript, it will be available as a caption for your video. Your audience will be able to select it during video playback. You can interact with captions generated through transcription using the [Captions endpoints](/reference/api/Captions). 
+
+Subscribe to the [`video.caption.generated`](/reference/api/Webhooks#video-caption-generated) webhook to get a notification when an automatically generated caption is complete.
 
 ## Examples