# Video Analysis

Analyze any YouTube video with AI.

Algrow's video analyzer breaks down any YouTube video — hooks, pacing, visual storytelling, content strategy. Pairs naturally with `search_viral_videos`, `search_by_thumbnail`, and `get_youtube_video_data` for deep competitor research workflows.

### `analyze_video`

Run Algrow's video analyzer over any YouTube video. Returns a structured text breakdown against your prompt — hooks, pacing, visual storytelling, on-screen text, B-roll usage, content strategy, and more. Async job — submits, polls, returns the analysis. Repeat prompts on the same video within 2 hours reuse a cached upload automatically (faster on the backend).

**Example prompts**

"Analyze this video for the hook in the first 3 seconds: https://youtube.com/watch?v=abc123"

"Break down the pacing and on-screen text usage in this Short"

"Compare these 3 viral cooking videos — what hook patterns do they share?"

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| video_url | string | required | YouTube video URL. Accepts watch links (`youtube.com/watch?v=...`), short links (`youtu.be/...`), and Shorts URLs (`youtube.com/shorts/...`). |
| prompt | string | required | What to analyze in plain English. Examples: "Break down the hook", "Identify the pacing and energy shifts", "What visual storytelling techniques are used?". Max 4,000 characters. |
| media_resolution | string | low | Analysis fidelity: `low` (default, recommended for hook / pacing / strategy prompts) or `default` (higher visual detail — useful when fine on-screen text or subtle visual cues matter). |

**Limits.** Very long videos are not supported. Live streams, private, deleted, and age-restricted videos are rejected with clear error messages. Costs 1 credit per 4 minutes of video (minimum 1 credit; `default` resolution costs 3x). Credits are charged when the job is queued and refunded if the analysis fails.

**Caching.** Repeat prompts on the same video within a short window reuse the prior ingest automatically — faster turnaround on follow-up questions.

### `start_video_analysis`

Submit a video for AI vision analysis and return immediately with a `job_id` — do NOT wait for the analysis to finish in this call. Use when you want to run OTHER Algrow tool calls (channel data, viral search, etc.) in parallel while the analysis processes in the background. Pair with `get_video_analysis_result(job_id)` to pick up the finished analysis later. Same backend job as `analyze_video`: 1 credit per 4 minutes of video (3x at `default` resolution), max 3hr videos, 2hr YouTube cache applies.

**Example prompts**

"Kick off an analysis of this video in the background and keep working on the other tasks"

"Start analyzing https://youtube.com/watch?v=abc123 for hook patterns, I'll come back for the result"

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| video_url | string | required | Video URL — YouTube (watch / youtu.be / Shorts), TikTok, or Instagram. Public videos only. |
| prompt | string | required | What to analyze — hook, pacing, visual storytelling, content strategy, etc. |
| media_resolution | string | low | Analysis fidelity: `low` (default, ~3x cheaper) or `default` (higher visual detail). |

### `get_video_analysis_result`

Fetch the result of a video analysis job submitted via `start_video_analysis`. Blocks until the job finishes (up to several minutes) and then renders the analysis widget. Always pass `video_url` and `prompt` back in — the widget needs them to render the embedded player and the prompt header.

**Example prompts**

"Pick up the analysis result for job_id 42"

"Get the finished video analysis for that job I started earlier"

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| job_id | string | required | Job ID returned by `start_video_analysis`. |
| video_url | string |  | Original `video_url` passed to `start_video_analysis` — needed so the widget can render the player. Strongly recommended. |
| prompt | string |  | Original `prompt` passed to `start_video_analysis` — needed so the widget can render the header. Strongly recommended. |

### `download_video`

Save a YouTube video, audio track, or subtitle file to a stable URL the user can click to download. Lands the bytes in Algrow’s storage and returns a deterministic mp4/mp3/srt URL with `Content-Disposition attachment` so clicking it triggers a save. Renders the dino runner game while the upstream download is running so users have something to do during the ~60–120s cold fetch.

**Example prompts**

"Download this video: https://youtube.com/watch?v=abc123"

"Save the audio track of that video as mp3"

"Grab the subtitles for the last video we analyzed"

"Save just the 1:30 to 2:00 section of this video in 1080p"

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| video_url | string | required | YouTube video URL. Accepts watch links (`youtube.com/watch?v=...`), short links (`youtu.be/...`), and Shorts URLs (`youtube.com/shorts/...`). |
| format | string | video | What to produce: `video` (mp4, default), `audio` (mp3), or `subtitles` (srt). |
| quality | string | 720p | Video height: `360p`, `480p`, `720p` (default), or `1080p`. Ignored for audio and subtitles. |
| start | string | null | Clip start timestamp. Accepts `"1:30"`, `"00:01:30"`, `"90"`, `"90s"`, or a raw number. Omit for start of video. |
| end | string | null | Clip end timestamp. Same formats as `start`. Omit for end of video. |

**Formats.** `video` returns mp4 at the requested `quality` (360p / 480p / 720p default / 1080p). `audio` returns mp3 (~10× smaller than video). `subtitles` returns SRT — tries human-authored first, then auto-generated English.

**Timestamps.** `start` and `end` accept `"1:30"`, `"00:01:30"`, `"90"`, `"90s"`, or a raw number. Clipped downloads of long videos are dramatically faster — a 30s slice of an hour-long video typically lands in ~15s vs ~60s for the full file. `subtitles` ignores the range and returns the full transcript.

**Caching.** Each unique (video, format, quality, range) tuple is cached for ~30 days in R2 + Redis. Repeat downloads within that window are instant. The returned URL is stable and safe to share or embed for the lifetime of the cache.

**Limits.** Capped at 3-hour source duration and 500 MB output. YouTube only — TikTok / Instagram aren’t supported here (their platforms reject the same infrastructure). Live, private, age-restricted, and region-blocked videos are rejected with specific error messages.

**Hourly cap by plan.** Per user (shared across all of your API keys): **Starter 10/hr, Professional 100/hr, Ultimate unlimited**. Cached repeats count; failed downloads don’t. When the cap is reached the tool returns an error widget with the wait time and a link to [Subscription settings](https://algrow.online/settings/subscription) to upgrade.

The tool is most powerful when chained with other Algrow tools. Common patterns:

Outlier Autopsy

Use `search_viral_videos` with `sort_by=outlier_score` and `min_outlier_score=3` to surface videos beating their channel's average by 3×+. Run `analyze_video` on each, asking "What does this do in the first 5 seconds, and how is it different from the channel's typical opener?". Algrow knows **which** videos overperformed; the analysis tells you **why**.

Niche Hook Pattern Extraction

Pair with `search_viral_videos` filtered by your niche and `uploaded_within_days=7`, top 10 by views. Run the same hook-focused `analyze_video` prompt across all 10. Claude synthesizes the cross-video patterns — cold-opens vs. question hooks vs. shock cuts, average length, on-screen text usage — into a single research memo.

Thumbnail-to-Hook Bridge

Use `search_by_thumbnail` to find videos with visually similar thumbnails to a draft or competitor cover. Then `analyze_video` on the top results with the prompt "How does the opening 3 seconds pay off the thumbnail promise?" — surfaces the gap between thumbnail bait and actual hook delivery.

Transcript + Vision Triangulation

Run `get_youtube_video_data` with `include_comments=true`, then `analyze_video` on the same URL. Claude reasons across visual analysis, public metadata, and audience reactions.

Competitor Folder Watch

For channels in a saved folder (`get_folder`), spot any with elevated `views_24h`, find the spiking upload via `get_channel_videos`, and `analyze_video` it with "What's the hook, format, and pacing — anything new vs. their previous style?". Pairs perfectly with a recurring weekly briefing.

Hook-to-Voiceover Pipeline

End-to-end content R&D in one chat: `analyze_video` on a top performer, ask Claude to draft 3 alternative hook scripts in the same style, then `generate_tts` on each so you can A/B-test voiceovers in your own video.