Skip to main content
POST
Is Short

Overview

Classify a YouTube URL as a Short (vertical) or a regular video by inspecting the actual video dimensions. No download is performed. This is more reliable than checking the URL pattern: a URL of the form youtube.com/watch?v=... can still be a Short in disguise (and vice versa). Only the real video dimensions tell the truth.

How the classification works

  • is_short = height > width on the best available video format
  • video_type is "live" when the URL is a live stream, otherwise "short" when vertical, otherwise "video"
  • duration_seconds is returned for context but does not affect the decision
The native extractor reads classification metadata before checking whether playback is available. A confirmed live stream can return video_type: "live" even before it starts. When dimensions are unavailable for that live, dimension fields are null and is_short is false. If the lightweight extraction cannot classify the video, the API tries the full native extractor with a new proxy session. An ordinary video whose dimensions remain unknown returns 502 instead of a guessed classification.

Header Parameters

string
required
Your API key for authentication

Request

string
required
The YouTube URL to classify. Accepts every YouTube URL form: watch?v=, youtu.be/, /shorts/, /embed/. URLs from other platforms return 400.

Response

boolean
true when the video is vertical (height greater than width).
string
One of "short", "video", or "live".
integer
Width in pixels of the best available video format. May be null for a confirmed live stream with no available video format.
integer
Height in pixels of the best available video format. May be null for a confirmed live stream with no available video format.
number
height / width. Values greater than 1.0 mean vertical. May be null when dimensions are missing.
integer
Total video duration in seconds. Informational only — not used in the classification.

Examples

Success Response

Error Responses

The 400 response covers two cases: the URL is not a recognised YouTube URL, or classification metadata is unavailable and the full native extractor confirms a content restriction (private, deleted, region-blocked, channel terminated). A refusal from the lightweight client alone triggers a fallback. The 401 response covers two cases: no x-api-key header was sent, or the key is invalid / revoked. The 502 response means the extractor could not establish a classification (proxy issue, YouTube error, timeout, or missing dimensions). Retry after a short delay.

Use Cases

Conditional routing

Pick a different quality preset, container, or storage folder based on whether the video is a Short.

Pre-filtering a batch

When ingesting a creator’s catalog, separate Shorts from full videos before queueing downloads.

UI hints

Show a different player or thumbnail aspect ratio in your front-end as soon as the URL is pasted.

Notes

  • Extraction budgets: up to 6 seconds for lightweight extraction and 20 seconds for the full native fallback when needed.
  • No server-side cache: if you call the endpoint repeatedly for the same URL, consider caching the response on your side.
  • No download: only video information is fetched; storage and bandwidth are not charged for this call.