---
title: "Analyze a Post Visually"
method: POST
path: "/api/v1/visual-analysis"
---

# Analyze a Post Visually

`POST /api/v1/visual-analysis`

## Request

- Base URL: `https://viraloutliers.com`
- URL: `https://viraloutliers.com/api/v1/visual-analysis`
- Auth: HTTP bearer

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.

Cost: 10 credits per call. Asynchronous: poll GET /api/v1/jobs/{jobRef}.

## Request body

- object
  - `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.

## Response `200`

Success

- object

## Other responses

- `401`: Invalid or revoked API key (or, on free skills, no key sent); code key_suspended means the key was suspended when its account was claimed by the email owner and can be reactivated in Settings
- `402`: Payment required. Without an API key (billable skills only) the code is payment_required and error.payment.checkoutUrl (or, when no link is configured, error.payment.pageUrl at https://viraloutliers.com/api-access) buys a key without an account; with a key it is insufficient_credits and error.payment points at create_topup_link.
- `429`: Rate limited

---

[API](https://skmtc.dev/viraloutliers/apis/viral-outliers-agent-api.md) · [All operations](https://skmtc.dev/viraloutliers/apis/viral-outliers-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/viraloutliers/apis/viral-outliers-agent-api/revisions/0099977bd629?raw)