Queues a structured visual analysis for a post: for a video, a scene-by-scene breakdown (per-scene timing, scene type, on-screen text, visual elements and a recreation note) plus an overall-style summary (color palette, text style, editing pace); for an image slideshow, per-slide text and visual descriptions. Accepts a public post URL or an internal post id. Asynchronous: returns a job reference to poll with get_job_status; once complete the analysis is attached to get_post responses (includeVisualAnalysis). Credits are charged on queueing and automatically refunded if the job fails. This is the visual twin of request_transcript.
Queue an AI visual analysis for any tracked post and get back a structured, scene-by-scene breakdown of how the video is built: the shots, their timing, the on-screen text, the editing pace, and a per-scene note on how to recreate each beat in your own niche. For image slideshows it returns the text and visual description of every slide instead. Hand it a public post URL or an internal post id; it runs asynchronously and attaches the finished analysis to get_post. Built for content-research agents that need to understand the structure behind a viral video, not just its caption. Each analysis costs 10 credits (1 credit = $0.01) and is refunded automatically if the job fails.
POST /api/v1/visual-analysis. Authenticate with your API key. Same call in three languages:
cURL
curl -X POST "https://viraloutliers.com/api/v1/visual-analysis" \
-H "Authorization: Bearer so_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"example","postId":"example"}'Python (requests)
import requests
r = requests.post(
"https://viraloutliers.com/api/v1/visual-analysis",
headers={"Authorization": "Bearer so_live_YOUR_KEY"},
json={"url":"example","postId":"example"},
)
print(r.json())JavaScript (fetch)
const res = await fetch("https://viraloutliers.com/api/v1/visual-analysis", {
method: "POST",
headers: { "Authorization": "Bearer so_live_YOUR_KEY", "Content-Type": "application/json" },
body: JSON.stringify({"url":"example","postId":"example"}),
});
const data = await res.json();
console.log(data);| Name | Type | Description |
|---|---|---|
url | string | Public post URL (e.g. a TikTok/Reel/Short link). The easy path when you have a link. |
postId | string | Internal post id (from search results). Provide this or url. |
The call itself returns a job reference immediately: visual analysis is asynchronous, not a blocking request. You poll that reference with get_job_status (free) until it reports completed, at which point the analysis is attached to the post and comes back on every subsequent get_post call (includeVisualAnalysis, default true) at no extra cost.
For a video, analysis_result contains a scenes array: each scene has start_seconds and end_seconds, a scene_type (talking_head, b_roll, text_screen, product_demo, transition, animation), a visual_description, the on_screen_text shown during it, a list of visual_elements, and a recreation_note telling you how to remake that beat for a different audience. You also get text_segments (on-screen text with timestamps) and an overall_visual_style summary (color_palette, text_style, editing_pace, recurring_elements). For an image slideshow the shape switches to a per-slide slides array with text and visual descriptions plus the same style summary.
You submit either a url (the easy path when a user hands you a link) or a postId from search results. The service fetches the post's media if it is not already stored, runs it through a multimodal AI model that watches the video (or reads the slides), and writes the structured result back onto the post record. Credits are charged when the job is queued and refunded automatically to your balance if the job ultimately fails, so you are never billed for an analysis you did not receive.
The job runs on a deferred queue, so submitting many at once does not block; each returns its own reference to poll. Because the analysis is cached on the post, analysing the same post again is unnecessary: get_post will already carry it, and remix_post reuses it rather than regenerating. To protect the flat price, very long TikTok and Instagram videos are capped (YouTube of any length is fine); an over-cap request is rejected with no charge.
Recreation briefs are the headline use: analyse a winning video, then walk its scenes in order and rewrite each recreation_note for your own brand, turning a proven format into a shot list your team (or a video-generation pipeline) can execute. Format studies pull the overall_visual_style and editing_pace across the top outliers in a niche to learn what the winning look actually is: fast cuts, talking-head, heavy text overlays. Accessibility and search pipelines use the on-screen text and scene descriptions to make silent, text-on-screen videos queryable.
Because the analysis lives on the post next to its stats and (if present) its transcript, one get_post gives an agent the numbers, the words and the visual structure together, everything needed to explain why a post worked and how to remake it.
Doing this yourself means downloading the media (proxies, expiring CDN links, HEIC and animated-cover quirks), feeding it to a multimodal model, and designing a prompt that returns a consistent, machine-readable scene breakdown rather than a paragraph of prose, then storing it joined to the post. Every one of those is a moving part that fails on its own schedule.
request_visual_analysis folds all of it into one call at a flat credit price, with automatic refunds on failure and the result cached on a post record that already carries stats, outlier scores and (optionally) a transcript. Compared with a generic vision API you would still have to feed frames into, this one starts from a post id, handles the media fetch and the video-vs-slideshow distinction, and returns a structure purpose-built for content recreation.
10 credits ($0.10) per call in prepaid credits (1 credit = $0.01). For example, 10 calls per dollar. Subscriptions include monthly credits; top-up packs start at $15. Failed asynchronous jobs are refunded automatically, and calls stop at a zero balance, never a surprise bill. See the full pricing table.
POST the post id or URL to the visual-analysis endpoint (or call the request_visual_analysis MCP tool). It costs 10 credits, runs asynchronously, and the finished breakdown, scenes with timing, on-screen text, visual elements and a recreation note, is returned by get_post, usually within a few minutes.
request_transcript returns the words: spoken audio, or on-screen text for a slideshow. request_visual_analysis returns the structure: how the video is shot scene by scene, the editing pace and overall visual style, and a per-scene note on how to recreate it. They are complementary, and both attach to the same post so get_post can return them together.
The job is retried automatically; if it ultimately fails your credits are refunded to your balance without any action on your side. Very long TikTok/Instagram videos are rejected up front with no charge (YouTube of any length is fine).
Also available as an MCP tool.
Related topics: video scene detection API · on-screen text extraction · shot list generation for short video · visual style analysis · content recreation automation