> ## Documentation Index > This page is part of the Image and Video APIs product. Fetch the complete documentation index for Image and Video APIs at: https://cloudinary.com/documentation/llms-image-and-video-apis.txt?referrer=docpage and then use it to discover all relevant pages before exploring further. > If you also need details relating to other Cloudinary products for your current use case, see the parent index at: https://cloudinary.com/documentation/llms.txt?referrer=docpage # AI Video Analysis API (Beta) > **INFO**: The AI Video Analysis API is currently in **Beta**. There may be minor changes to parameter names or other implementation details before the general access release. We invite you to try it out. We would appreciate any feedback via our [support team](https://support.cloudinary.com/hc/en-us/requests/new). ## Overview The AI Video Analysis API uses AI to generate a **visual transcription** of a video: a sequence of timestamped, natural-language descriptions of what's visible on screen. Unlike [video transcription](video_transcription), which converts spoken audio to text, a visual transcription describes the visual content itself, such as scenes, subjects, actions, and settings, even when the video has no audio. You submit a video asset that's already stored in your product environment, optionally guide the analysis with a prompt, and receive a transcript file containing one entry per scene segment. Common use cases include: * **Accessibility**: Use the descriptions as the basis for an audio description (AD) script that helps people who are blind or have low vision understand the visual content. See [using the output for accessibility](#using_the_output_for_accessibility). * **Visual search and tagging**: Feed the descriptions into a [MediaFlows](mediaflows) workflow or an LLM to map visual content to your own tags or taxonomy. * **Content understanding**: Generate scene-by-scene summaries of video content for editorial or cataloging workflows. ## How it works Analysis runs asynchronously: 1. Send a `POST` request with the asset to analyze. The response returns a `job_id` and an initial status of `pending`. 1. Poll the job using the `job_id` until the status is `completed`. 1. The completed response includes a `visual_transcription` object that points to a raw file containing the timestamped descriptions. ## Generate a visual transcription Send a `POST` request to the `ai_video_analysis` endpoint: `https://api.cloudinary.com/v2/video//ai_video_analysis` Authenticate using your API key and secret. Include the following parameters in your JSON request body: | Parameter | Type | Required | Description | |---|---|---|---| | `video_asset_id` | String | Yes | The unique identifier of the video asset to analyze. The video must already be stored in your product environment. You can retrieve an asset's ID from the upload response or by using the [Admin API](admin_api). | | `visual_transcription_prompt` | String | No | A natural-language instruction that guides the description style or focus, for example `"focus on describing colors"`. If omitted, a default prompt is used. | ### Example request ```curl curl \ -X POST \ -H "Content-Type: application/json" \ -d '{ \ "video_asset_id": "2fb8263411604d13a5d33e7623edc750" \ }' \ https://:@api.cloudinary.com/v2/video//ai_video_analysis ``` ### Example response The request returns a `201` response with a `job_id` and a status of `pending`: ```json { "request_id": "757b95f9b7e007e9bdd5f7ebcdc6799e", "data": { "job_id": "ad7f72944f344d43844717ac1fc4da8a", "status": "pending" } } ``` ## Check the analysis status To retrieve the result, send a `GET` request to the same endpoint with the `job_id` appended to the path: `https://api.cloudinary.com/v2/video//ai_video_analysis/` ### Example request ```curl curl \ https://:@api.cloudinary.com/v2/video//ai_video_analysis/ad7f72944f344d43844717ac1fc4da8a ``` While the analysis is in progress, the `status` is `pending`. Once it finishes, the `status` is `completed` and the response includes a `visual_transcription` object: ```json { "request_id": "4e4d51f6c345fc9f9c109e316c47c661", "data": { "job_id": "ad7f72944f344d43844717ac1fc4da8a", "status": "completed", "visual_transcription": { "asset_id": "e6333006ccb63c2893af37fc51dd77ee", "public_id": "samples/sea-turtle.visual.transcript", "resource_type": "raw", "delivery_type": "upload", "url": "https://res.cloudinary.com//raw/upload/v1782491923/samples/sea-turtle.visual.transcript" } } } ``` The `visual_transcription` object describes the generated transcript file, which is stored as a raw asset in your product environment: | Field | Description | |---|---| | `asset_id` | The unique identifier of the generated transcript file. | | `public_id` | The public ID of the transcript file. | | `resource_type` | The resource type of the file. Always `raw`. | | `delivery_type` | The delivery type of the file, for example `upload`. | | `url` | The URL to fetch the transcript file contents. | ## The visual transcription file Fetch the file at the returned `url` to retrieve the descriptions. The file contains a JSON array of segments, where each segment describes a portion of the video over a time range (in seconds). For example, analyzing this video: ![Sea turtle swimming underwater](https://res.cloudinary.com/demo/video/upload/samples/sea-turtle.mp4 "with_code:false, with_url:false, thumb:c_scale,w_700") produces the following transcript: ```json [ { "transcript": "A sea turtle swims through the deep blue ocean, viewed from above and behind as it glides forward.", "start_time": 0, "end_time": 4 }, { "transcript": "The camera angle shifts to a view from below, showing the turtle's underbelly as it swims closer to the camera.", "start_time": 5.033, "end_time": 8.633 }, { "transcript": "The view returns to a side and rear perspective as the turtle continues to swim away into the blue expanse.", "start_time": 8.7, "end_time": 12.7 } ] ``` | Field | Description | |---|---| | `transcript` | A natural-language description of what's visible during the segment. | | `start_time` | The start of the segment, in seconds. | | `end_time` | The end of the segment, in seconds. | ## Guiding the output with a prompt By default, the API produces a general description of each segment. Use the optional `visual_transcription_prompt` parameter to steer what the descriptions focus on or how they're phrased. For example, analyzing the same video with the prompt `"focus on describing colors"`: ```curl curl \ -X POST \ -H "Content-Type: application/json" \ -d '{ \ "video_asset_id": "2fb8263411604d13a5d33e7623edc750", \ "visual_transcription_prompt": "focus on describing colors" \ }' \ https://:@api.cloudinary.com/v2/video//ai_video_analysis ``` produces color-rich descriptions: ```json [ { "transcript": "A sea turtle with a dark brown shell and patterned flippers swims through the deep blue water, moving towards the camera.", "start_time": 0, "end_time": 4 }, { "transcript": "The turtle, now closer, reveals its pale yellow underside and patterned head as it glides upwards through the sunlit blue water.", "start_time": 4.5, "end_time": 8.5 }, { "transcript": "The turtle swims past, showing the reddish-brown tint on the back of its shell before moving away into the vast blue ocean.", "start_time": 8.5, "end_time": 12.5 } ] ``` You might instead focus the model on actions, settings, or on-screen objects, depending on your use case. ## Using the output for accessibility A visual transcription provides the raw material for an [audio description](accessible_media_video_audio#audio_descriptions) (AD) script, which conveys important visual information to people who are blind or have low vision. Because each segment is timestamped, you can present the descriptions as a time-aligned text track or as text alongside the video for screen readers. For example, the color-focused turtle transcription above maps directly onto a [WebVTT](https://developer.mozilla.org/en-US/docs/Web/API/WebVTT_API) file, with each segment's `start_time` and `end_time` becoming a cue: ``` WEBVTT 00:00:00.000 --> 00:00:04.000 A sea turtle with a dark brown shell and patterned flippers swims through the deep blue water, moving towards the camera. 00:00:04.500 --> 00:00:08.500 The turtle, now closer, reveals its pale yellow underside and patterned head as it glides upwards through the sunlit blue water. 00:00:08.500 --> 00:00:12.500 The turtle swims past, showing the reddish-brown tint on the back of its shell before moving away into the vast blue ocean. ``` Upload this file to your product environment and supply it as a `descriptions` text track in the Cloudinary Video Player, as shown in [Audio descriptions as captions](accessible_media_video_audio#audio_descriptions_as_captions). Review and edit the generated text before publishing, so that the descriptions are accurate and fit within the available gaps in any existing audio. > **NOTE**: The API produces descriptive text, not a synthesized audio track. To deliver the descriptions as spoken audio, pair the text with a text-to-speech step in your own workflow. ## Error handling If a request can't be processed, the response includes an `error` object with a `message`. For example, an invalid asset identifier returns: ```json { "request_id": "39e5a202d35cf1dfb4ec3efa47be1caa", "error": { "message": "bad request: video asset id is invalid" } } ``` ## Beta limitations During Beta, the API returns the visual transcription file only. Additional outputs, such as a summary, title, or tags derived from the analysis, are planned for a future phase. ## Related topics > **READING**: > > * [Video and audio accessibility](accessible_media_video_audio) > * [Video transcription](video_transcription) > * [Automate media workflows with MediaFlows](mediaflows)