YouTube Video API

#What this API solves

The youtube/video module turns a single YouTube video ID (or URL) into the practical signals you need: core metadata, engagement metrics, restrictions & status, comments, SEO surfaces (tags, hashtags, links), playlists featuring the video, and AI-powered audits. Use results to choose thumbnails/titles, estimate watch-time, detect country blocks, or group videos into mixes.

#Endpoints & when to use them

#POST /v1/youtube/video/information — Basic Information

• Best for: Canonical data for cards, editors, and QA. Category & channel IDs for routing.
• Output: video{ id, title, description, duration (ISO), publishedAt, categoryId + categoryName, channelId, channelTitle, statistics, thumbnails }.
• Tip: Store id, channelId, categoryId as foreign keys; render duration as mm:ss.

#POST /v1/youtube/video/engagement-rate — Engagement Rate

• Best for: Quick quality bar across uploads; ranking candidates for playlists.
• Output: engagement{ views, likes, comments, rate } where rate = (likes+comments)/views.
• Tip: Use buckets: <0.01 (weak), 0.01–0.03 (solid), >0.03 (hot) — tune per niche.

#POST /v1/youtube/video/comments — Top Comments

• Best for: Social proof, snippets for landing pages, moderation/QA workflows.
• Output: Flat list of top-level comments (optionally with replies).
• Tip: For moderation UIs, request order="time"; for marketing, use relevance (default).

#POST /v1/youtube/video/restricted — Restrictions

• Best for: Detecting geo blocks, age restrictions, and embeddability issues before publishing.
• Output: restrictions{ geoBlocked, ageRestricted, blocked[], allowed[], embeddable, madeForKids, license, privacyStatus }.
• Tip: If geoBlocked=true show “Unavailable in your region” and pick alternates for that market.

#POST /v1/youtube/video/settings — Settings / Status

• Best for: Editorial checks: privacy, license, Made for Kids, projection, recordingDate, language/region.
• Output: settings{ privacyStatus, license, embeddable, publicStatsViewable, disableComments, madeForKids, ageRestricted, projection, recordingDate, locationDescription, categoryId+Name, language, region }.
• Tip: Use language/region to prefill translation tasks and subtitles pipelines.

#POST /v1/youtube/video/statistics — Statistics

• Best for: Snapshot cards and simple leaderboards.
• Output: statistics{ views, likes, comments, favourites } (point-in-time).

#POST /v1/youtube/video/tags — Video Tags

• Best for: SEO diffing, tag normalization, clustering similar videos.
• Output: tags[] or empty if unavailable.

#POST /v1/youtube/video/extract-hashtags — Extract Hashtags

• Best for: Pulling visible #hashtags from title/description for social cross-posting.
• Output: { cnt_hashtags, hashtags[] }.

#POST /v1/youtube/video/extract-links — Extract Links

• Best for: Affiliate checks, out-link audits, or building a “Links” panel on video pages.
• Output: { cnt_links, links[] }.

#POST /v1/youtube/video/thumbnail — Thumbnail URLs

• Best for: Rendering cards without re-deriving thumb URLs.
• Output: thumbnails{ default, medium, high, standard, maxres }.

#POST /v1/youtube/video/search-playlists — Playlists Featuring This Video

• Best for: Discoverability & social proof (“featured in 12 playlists”).
• Output: { cnt_playlists, playlists[{ id, title, url, found }] }.

#POST /v1/youtube/video/trending — Trending Check

• Best for: Pinning “Now Trending in GB” badges and ordering on homepages.
• Output: trending{ country, categoryId, categoryName, isTrending, position }.

#POST /v1/youtube/video/watchtime-estimate — Watch-Time Estimate

• Best for: Forecasting watch-hours for mixes or promo decisions.
• Output: watchtime{ views, durationSec, avgRetention, perViewSec, seconds, watchHours }.
• Tip: Override avgRetention (0–1) if you know your niche average; otherwise we fallback by category.

#POST /v1/youtube/video/audit — AI-Powered Audit

• Best for: Fast SEO/CTR feedback on title/description/tags vs channel baseline.
• Output: audit{ videoId, views, likes, comments, engagementRate, channelMedianViews, isAboveMedian, aiRecommendations }.
• Tip: Tune sample (10–100) to match channel cadence for meaningful medians.

#Quick start

# Basic info
curl -X POST "https://api.yeb.to/v1/youtube/video/information" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{ "video":"dQw4w9WgXcQ" }'

# Engagement rate
curl -X POST "https://api.yeb.to/v1/youtube/video/engagement-rate" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{ "video":"dQw4w9WgXcQ" }'

# Comments (latest 25, include replies)
curl -X POST "https://api.yeb.to/v1/youtube/video/comments" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{ "video":"dQw4w9WgXcQ", "limit":25, "order":"time", "repliesOn":true }'

# AI audit (use 50 last uploads as baseline)
curl -X POST "https://api.yeb.to/v1/youtube/video/audit" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{ "video":"dQw4w9WgXcQ", "sample":50 }'

#Parameters that actually matter

#Reading & acting on responses

#Information — interpretation

{
  "video": {
    "id":"dQw4w9WgXcQ",
    "title":"Rick Astley – Never Gonna Give You Up",
    "duration":"PT3M32S",
    "publishedAt":"1987-10-25T00:00:00Z",
    "categoryId":"10",
    "categoryName":"Music",
    "channelId":"UCuAXFkgsw1L7xaCfnd5JJOw",
    "channelTitle":"Official Rick Astley"
  }
}

• id — Video ID → watch URL, embeds, thumbnail derivation.
• channelId — Use for deep links and channel-level rollups.
• duration — ISO-8601; convert to mm:ss for chips (helpful in grid UIs).

#Engagement — interpretation

{ "engagement": { "views":1580000000, "likes":15400000, "comments":1120000, "rate":0.011 } }

• Use case: Sort candidates for playlists by rate, then sanity-check with comments volume.

#Comments — interpretation

{
  "cnt_comments": 25,
  "comments": [
    { "id":"Ugz…", "author":"Alice", "text":"Still a banger!", "likes":42, "published":"2025-06-01T12:34:00Z",
      "replies": { "cnt":2, "items":[{"id":"Ugy…","author":"Bob","text":"100%","likes":3,"published":"…"}] } }
  ]
}

• Surface: Show the first one or two “relevance” comments as social proof; switch to time for live streams.

#Restrictions — interpretation

{
  "restrictions": {
    "geoBlocked":false, "ageRestricted":false,
    "embeddable":true,  "privacyStatus":"public"
  }
}

• Action: If embeddable=false, fallback to channel link instead of inline player.

#Trending check — interpretation

{ "trending": { "country":"GB", "isTrending":true, "position":17 } }

• Action: Add “Trending #17 in GB” badge; bump in country-specific rails.

#Watch-time estimate — interpretation

{
  "watchtime": {
    "views":739, "durationSec":1733,
    "avgRetention":0.30, "perViewSec":520,
    "seconds":384206, "watchHours":106.7
  }
}

• Use case: Forecast weekly watch-hours; if below target, delay posting the next mix.

#Practical recipes

• Playlist curation: Rank by engagement.rate, filter restrictions.embeddable=true, and ensure categoryId=10 for music.
• SEO diff: Compare tags + hashtags against your top performers; feed weak items into /audit.
• Compliance: Check restricted prior to embedding; show geo messages when geoBlocked.
• Mix timing: Use watchtime.watchHours to decide whether to release or wait for the current video to peak.

#YouTube IDs you’ll work with

#Common YouTube Category IDs

#Errors & troubleshooting

• 400 "Missing "action" parameter" — Provide one of the supported actions (see sections above).
• 400 "Missing "video" parameter" — Supply ID or URL for video-based actions.
• 404 "Video not found" — Invalid/removed/private video.
• 403 "Comments disabled" — Respect channel/video settings; hide comment UI.
• 429 "Quota exceeded" — Backoff and reduce polling; cache responses.

#API Changelog (youtube/video)

Use the API Playgrounds below each section in this page to test requests with your own video IDs.