Type Value: YOUTUBE_VIDEO
Status: PRODUCTION

A YOUTUBE_VIDEO link type corresponds to a YouTube video URL. Beyond the common attributes (title, description, image), YOUTUBE_VIDEO links include additional metadata like the video’s duration, view counts, and user (channel) information. This helps you display detailed previews that highlight a video’s popularity, relevance, and origin.

​
What It Includes

When type is YOUTUBE_VIDEO, the response includes a youtubeVideo object with fields like:

  • videoId: The unique YouTube video identifier.
  • user: Information about the channel or user who uploaded the video.
  • publishedAt: The date and time when the video was published.
  • duration: Video length in seconds.
  • viewsCount, likesCount, dislikesCount, commentsCount: Engagement metrics that reflect the video’s popularity and user interaction.
  • rating: A computed rating value.
  • thumbnail: A responsive image object with various resolutions, ideal for displaying a suitable thumbnail size in your UI.

By accessing these attributes, you can create rich video previews that show users how popular or recent a video is, who created it, and what they can expect from its content.

​
Example Request

curl -X POST "https://api.peekalink.io/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"link": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

​
Example Response

{
    "id": 586,
    "ok": true,
    "url": "https://www.youtube.com/watch?v=kJQP7kiw5Fk",
    "domain": "youtube.com",
    "type": "YOUTUBE_VIDEO",
    "status": 200,
    "updatedAt": "2024-12-15T18:53:04.785Z",
    "size": 2006570,
    "redirected": false,
    "title": "Luis Fonsi - Despacito ft. Daddy Yankee",
    "description": "“Despacito” disponible ya en todas las plataformas digitales: https://UMLE.lnk.to/DOoUzFp “Imposible” disponible ya en todas las plataformas digitales: https...",
    "icon": {
        "url": "https://cdn.peekalink.io/qsxqq2sx49x34ua8ckndaqy9/1381/favicon_32x32.png",
        "width": 32,
        "height": 32,
        "backgroundColor": "#FFFFFF"
    },
    "image": {
        "thumbnail": {
            "width": 320,
            "height": 180,
            "url": "https://cdn.peekalink.io/zyi35nc35rwxfn1cc1jpfz0z/1382/maxresdefault_thumbnail.jpeg"
        },
        "medium": {
            "width": 640,
            "height": 360,
            "url": "https://cdn.peekalink.io/zyi35nc35rwxfn1cc1jpfz0z/1382/maxresdefault_medium.jpeg"
        },
        "large": {
            "width": 1280,
            "height": 720,
            "url": "https://cdn.peekalink.io/zyi35nc35rwxfn1cc1jpfz0z/1382/maxresdefault_large.jpeg"
        },
        "original": {
            "width": 1280,
            "height": 720,
            "url": "https://cdn.peekalink.io/zyi35nc35rwxfn1cc1jpfz0z/1382/maxresdefault_original.jpeg"
        }
    },
    "youtubeVideo": {
        "id": 3,
        "videoId": "kJQP7kiw5Fk",
        "publishedAt": "2022-04-09T22:01:59.443Z",
        "title": "Luis Fonsi - Despacito ft. Daddy Yankee",
        "description": "“Despacito” disponible ya en todas las plataformas digitales: https://UMLE.lnk.to/DOoUzFp \n“Imposible” disponible ya en todas las plataformas digitales: https://UMLE.lnk.to/IMPOSIBLEFp\n“Calypso” disponible ya en todas las plataformas digitales: https://UMLE.lnk.to/CLYPSFp\nEchame La Culpa disponible ya en todas las plataformas digitales: https://UMLE.lnk.to/ELCFp\n\n\nBest of Luis Fonsi / Lo mejor Luis Fonsi: https://goo.gl/KLWPSa \nSubscribe here: https://goo.gl/nkhcGc\nSigue a Luis Fonsi: \nOfficial Site: http://www.luisfonsi.com/ \nFacebook:   / luisfonsi   \nTwitter:   / luisfonsi   \nInstagram:   / luisfonsi  \n\n#LuisFonsi #Despacito #Imposible #Calypso #EchamelaCulpa #NadaEsImposible #NothingisImpossible #LF\n\n\nMusic video by Luis Fonsi performing Despacito. (C) 2017 Universal Music Latino",
        "duration": 282,
        "viewsCount": 8610457367,
        "likesCount": 54222103,
        "dislikesCount": 6007104,
        "thumbnail": {
            "thumbnail": {
                "width": 320,
                "height": 180,
                "url": "https://cdn.peekalink.io/zyi35nc35rwxfn1cc1jpfz0z/1382/maxresdefault_thumbnail.jpeg"
            },
            "medium": {
                "width": 640,
                "height": 360,
                "url": "https://cdn.peekalink.io/zyi35nc35rwxfn1cc1jpfz0z/1382/maxresdefault_medium.jpeg"
            },
            "large": {
                "width": 1280,
                "height": 720,
                "url": "https://cdn.peekalink.io/zyi35nc35rwxfn1cc1jpfz0z/1382/maxresdefault_large.jpeg"
            },
            "original": {
                "width": 1280,
                "height": 720,
                "url": "https://cdn.peekalink.io/zyi35nc35rwxfn1cc1jpfz0z/1382/maxresdefault_original.jpeg"
            }
        },
        "user": {
            "id": 5,
            "username": "UCxoq-PAQeAdk_zyg8YS0JqA",
            "name": "Luis Fonsi",
            "description": "Hola amigos! Soy Luis Fonsi y este es mi canal de YouTube en donde compartiré con ustedes algunas de mis presentaciones en vivo, backstages, anécdotas, entre otras cosas. Suscríbanse para recibir todas las novedades!\n\nSaludos!\n\nAdministrador del Canal: Farolatino y @torrecilla90",
            "subscribersCount": 32000000,
            "videosCount": 368,
            "verified": false,
            "visibility": "PUBLIC",
            "isFamilySafe": true,
            "avatar": {
                "thumbnail": {
                    "width": 240,
                    "height": 240,
                    "url": "https://cdn.peekalink.io/av5g930spd7hh75jgy2nzhb1/1112/c-TEErg6GIyeUaD_BM5Xm9P1PI7lHV1XvnmGyK-Cc_fEwDUT-p3TfIsy64xtg392U2dAP11IfQ=s900-c-k-c0x00ffffff-no-rj_thumbnail.jpeg"
                },
                "medium": {
                    "width": 480,
                    "height": 480,
                    "url": "https://cdn.peekalink.io/av5g930spd7hh75jgy2nzhb1/1112/c-TEErg6GIyeUaD_BM5Xm9P1PI7lHV1XvnmGyK-Cc_fEwDUT-p3TfIsy64xtg392U2dAP11IfQ=s900-c-k-c0x00ffffff-no-rj_medium.jpeg"
                },
                "large": {
                    "width": 900,
                    "height": 900,
                    "url": "https://cdn.peekalink.io/av5g930spd7hh75jgy2nzhb1/1112/c-TEErg6GIyeUaD_BM5Xm9P1PI7lHV1XvnmGyK-Cc_fEwDUT-p3TfIsy64xtg392U2dAP11IfQ=s900-c-k-c0x00ffffff-no-rj_large.jpeg"
                },
                "original": {
                    "width": 900,
                    "height": 900,
                    "url": "https://cdn.peekalink.io/av5g930spd7hh75jgy2nzhb1/1112/c-TEErg6GIyeUaD_BM5Xm9P1PI7lHV1XvnmGyK-Cc_fEwDUT-p3TfIsy64xtg392U2dAP11IfQ=s900-c-k-c0x00ffffff-no-rj_original.jpeg"
                }
            },
            "banner": {
                "thumbnail": {
                    "width": 320,
                    "height": 53,
                    "url": "https://cdn.peekalink.io/vj950vndfobz8np2fbmdbi4f/1114/IdfO8PMyTHDkqCHUa_bJZJ3BjYZ9tFgkClcNLUWw8X57EqVTlOVXRRUTIPmjOpYFWowM0_uyU8c=w1707-fcrop64=1,00005a57ffffa5a8-k-c0xffffffff-no-nd-rj_thumbnail.jpeg"
                },
                "medium": {
                    "width": 640,
                    "height": 106,
                    "url": "https://cdn.peekalink.io/vj950vndfobz8np2fbmdbi4f/1114/IdfO8PMyTHDkqCHUa_bJZJ3BjYZ9tFgkClcNLUWw8X57EqVTlOVXRRUTIPmjOpYFWowM0_uyU8c=w1707-fcrop64=1,00005a57ffffa5a8-k-c0xffffffff-no-nd-rj_medium.jpeg"
                },
                "large": {
                    "width": 1280,
                    "height": 211,
                    "url": "https://cdn.peekalink.io/vj950vndfobz8np2fbmdbi4f/1114/IdfO8PMyTHDkqCHUa_bJZJ3BjYZ9tFgkClcNLUWw8X57EqVTlOVXRRUTIPmjOpYFWowM0_uyU8c=w1707-fcrop64=1,00005a57ffffa5a8-k-c0xffffffff-no-nd-rj_large.jpeg"
                },
                "original": {
                    "width": 1707,
                    "height": 282,
                    "url": "https://cdn.peekalink.io/vj950vndfobz8np2fbmdbi4f/1114/IdfO8PMyTHDkqCHUa_bJZJ3BjYZ9tFgkClcNLUWw8X57EqVTlOVXRRUTIPmjOpYFWowM0_uyU8c=w1707-fcrop64=1,00005a57ffffa5a8-k-c0xffffffff-no-nd-rj_original.jpeg"
                }
            }
        }
    },
    "requestId": "cm4pysx3x0001daadms6qew7d"
}

​
Special Notes

  • Fallback Strategies: If certain metadata is missing, Peekalink attempts to infer title, description, or image to maintain a consistent preview experience.
  • Engagement Metrics: Views, likes, and comments data allow you to highlight a video’s popularity or credibility.
  • Channel Integration: The user field connects the video to its creator’s channel details, which can be leveraged to display subscriber counts or channel branding.

​
Schema reference

For a full technical breakdown of all fields and validation rules, including detailed JSON schemas, please refer to the API Reference.