Skip to main content
POST
/
metadata
Get Metadata
curl --request POST \
  --url https://api.example.com/metadata \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "url": "<string>"
}
'
{
  "title": "Rick Astley - Never Gonna Give You Up (Official Video)",
  "duration": 213.0,
  "width": 1920,
  "height": 1080,
  "extractor": "YouTube",
  "uploader": "Rick Astley",
  "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
  "description": "The official video for Never Gonna Give You Up...",
  "view_count": 1500000000,
  "like_count": 15000000,
  "upload_date": "20091025",
  "filesize_approx": 52428800
}

​
Overview

Extract metadata (title, duration, thumbnail, etc.) from a video URL without actually downloading the video. Useful for preview, validation, or getting video information before creating a download job.

​
Header Parameters

​
x-api-key
string
required
Your API key for authentication

​
Request

​
url
string
required
The video URL to extract metadata from

​
Response

​
title
string
Video title
​
duration
number
Video duration in seconds
​
width
integer
Video width in pixels
​
height
integer
Video height in pixels
​
extractor
string
Platform name (e.g., “YouTube”, “Vimeo”)
​
uploader
string
Channel or uploader name
​
thumbnail
string
URL to the video thumbnail
​
description
string
Video description
​
view_count
integer
Number of views
​
like_count
integer
Number of likes
​
upload_date
string
Upload date in YYYYMMDD format
​
filesize_approx
integer
Approximate file size in bytes

​
Examples

curl -X POST "https://tornado.velys.software/metadata" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }'

​
Success Response

{
  "title": "Rick Astley - Never Gonna Give You Up (Official Video)",
  "duration": 213.0,
  "width": 1920,
  "height": 1080,
  "extractor": "YouTube",
  "uploader": "Rick Astley",
  "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
  "description": "The official video for Never Gonna Give You Up...",
  "view_count": 1500000000,
  "like_count": 15000000,
  "upload_date": "20091025",
  "filesize_approx": 52428800
}

​
Error Responses

{
  "error": "Failed to extract metadata",
  "details": "Video unavailable"
}

​
Use Cases

​
Preview Before Download

Get video information before creating a download job to show users what they’re about to download.

​
Validate URLs

Check if a URL is valid and supported before adding it to a batch.

​
Get Thumbnail

Extract the thumbnail URL to display in your UI without downloading the full video.

​
Estimate Storage

Use filesize_approx to estimate storage requirements before downloading.