--- title: "Similar Thumbnails API" description: "Find YouTube videos with visually similar thumbnails using text or image-based search." source: "https://dashboard.nexlev.io/docs/api/similar-thumbnails" --- # Similar Thumbnails API Find YouTube videos with visually similar thumbnails using text or image-based search. **Base URL**: `https://prod.dashboard.nexlev.io` — see [Authentication](/docs/api/authentication). ## Search Similar Thumbnails ```http POST /api/external/similar-thumbnails/search ``` **Description**: Find YouTube videos with visually similar thumbnails based on text descriptions or image analysis. Use this endpoint to identify thumbnail trends, discover content opportunities, and analyze successful thumbnail patterns. **cURL Example (Text Search)**: ```bash curl -X POST https://prod.dashboard.nexlev.io/api/external/similar-thumbnails/search \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text": "WW2 Documentary"}' ``` **Request Body (Text Search)**: ```json { "text": "WW2 Documentary" } ``` **Request Body (Image URL Search)**: ```json { "image_url": "https://i.ytimg.com/vi/bsL7ZnKIAhs/maxresdefault.jpg" } ``` **Body Parameters**: `text` (conditional) or `image_url` (conditional) - Provide either text description or image URL **Note**: Provide either `text` OR `image_url`, not both. > **Warning** > > 🥞 **Quota Cost: 10 quota per request** — see [Rate Limits & > Quota](/docs/api/rate-limits). **Status Code**: `200 OK` **Description**: Returns a list of videos with thumbnails similar to your search query, ranked by visual similarity score. Each result includes video information, channel data, thumbnail URLs, and a similarity score indicating how closely the thumbnail matches your search. **Response Body**: ```json { "data": [ { "similarity": 0.8542, "id": "xK7mN9pQ2rT", "filename": "xK7mN9pQ2rT.jpg", "path": "/tmp/batch_123_abc456/xK7mN9pQ2rT.jpg", "metadata": { "title": "Epic Space Adventure: Journey to the Red Planet", "videoViews": null, "categories": [], "videoType": "unknown" }, "youtubeThumbnailUrl": "https://img.youtube.com/vi/xK7mN9pQ2rT/hqdefault.jpg", "youtubeMaxResUrl": "https://img.youtube.com/vi/xK7mN9pQ2rT/maxresdefault.jpg", "youtubeVideoUrl": "https://www.youtube.com/watch?v=xK7mN9pQ2rT", "fullLocalPath": "//tmp/batch_123_abc456/xK7mN9pQ2rT.jpg", "videoData": { "viewCount": 2847563, "lengthSeconds": "1842", "description": "Join us on an incredible journey through space as we explore the mysteries of Mars. This documentary takes you through the latest discoveries and future missions planned for the Red Planet.", "thumbnail": [ { "url": "https://i.ytimg.com/vi/xK7mN9pQ2rT/hqdefault.jpg", "width": 168, "height": 94 }, { "url": "https://i.ytimg.com/vi/xK7mN9pQ2rT/hqdefault.jpg", "width": 196, "height": 110 }, { "url": "https://i.ytimg.com/vi/xK7mN9pQ2rT/hqdefault.jpg", "width": 246, "height": 138 }, { "url": "https://i.ytimg.com/vi/xK7mN9pQ2rT/hqdefault.jpg", "width": 336, "height": 188 }, { "url": "https://i.ytimg.com/vi_webp/xK7mN9pQ2rT/maxresdefault.webp", "width": 1920, "height": 1080 } ], "keywords": [ "space", "mars", "documentary", "science", "exploration", "nasa", "astronomy", "planets" ], "channelTitle": "Space Explorers", "channelId": "UCxYz1234AbCdEfGhIjKlMnO", "category": "Science & Technology", "publishDate": "2025-01-15T14:30:00-08:00", "uploadDate": "2025-01-15T14:30:00-08:00", "isFamilySafe": true, "isPrivate": false, "isLiveContent": false, "availableCountries": ["US", "GB", "CA", "AU", "DE", "FR", "JP"] }, "channelData": { "channelId": "UCxYz1234AbCdEfGhIjKlMnO", "title": "Space Explorers", "description": "Your gateway to the cosmos. We create stunning documentaries about space exploration, astronomy, and the future of humanity among the stars.", "subscriberCount": 3250000, "videosCount": 342, "viewCount": 485672341, "channelHandle": "@spaceexplorers", "country": "United States", "joinedDate": "2016-08-12", "avatar": [ { "url": "https://yt3.googleusercontent.com/example-avatar-url/s160-c-k-c0x00ffffff-no-rj", "width": 160, "height": 160 } ], "isFamilySafe": true }, "calculatedData": { "outlierScore": 3.45, "averageViewsPerVideo": 1420678.23, "isOutlier": true, "outlierThreshold": 2 } }, { "similarity": 0.7823, "id": "aB3cD4eF5gH", "filename": "aB3cD4eF5gH.jpg", "path": "/tmp/batch_123_abc456/aB3cD4eF5gH.jpg", "metadata": { "title": "Pets in Space: The Ultimate Adventure", "videoViews": null, "categories": [], "videoType": "unknown" }, "youtubeThumbnailUrl": "https://img.youtube.com/vi/aB3cD4eF5gH/hqdefault.jpg", "youtubeMaxResUrl": "https://img.youtube.com/vi/aB3cD4eF5gH/maxresdefault.jpg", "youtubeVideoUrl": "https://www.youtube.com/watch?v=aB3cD4eF5gH", "fullLocalPath": "//tmp/batch_123_abc456/aB3cD4eF5gH.jpg", "videoData": { "viewCount": 1523847, "lengthSeconds": "925", "description": "What if our furry friends could explore the final frontier? This fun animated short imagines a world where pets become astronauts!", "thumbnail": [ { "url": "https://i.ytimg.com/vi/aB3cD4eF5gH/hqdefault.jpg", "width": 336, "height": 188 }, { "url": "https://i.ytimg.com/vi_webp/aB3cD4eF5gH/maxresdefault.webp", "width": 1920, "height": 1080 } ], "keywords": [ "pets", "space", "animation", "fun", "kids", "adventure", "animals" ], "channelTitle": "Creative Animations", "channelId": "UCpQr5678StUvWxYzAbCdEf", "category": "Entertainment", "publishDate": "2025-02-20T10:00:00-08:00", "uploadDate": "2025-02-20T10:00:00-08:00", "isFamilySafe": true, "isPrivate": false, "isLiveContent": false, "availableCountries": ["US", "GB", "CA", "AU"] }, "channelData": { "channelId": "UCpQr5678StUvWxYzAbCdEf", "title": "Creative Animations", "description": "Bringing imagination to life through stunning animations and creative storytelling.", "subscriberCount": 890000, "videosCount": 156, "viewCount": 124567890, "channelHandle": "@creativeanimations", "country": "Canada", "joinedDate": "2019-03-22", "avatar": [ { "url": "https://yt3.googleusercontent.com/example-avatar-url-2/s160-c-k-c0x00ffffff-no-rj", "width": 160, "height": 160 } ], "isFamilySafe": true }, "calculatedData": { "outlierScore": 1.87, "averageViewsPerVideo": 798512.75, "isOutlier": false, "outlierThreshold": 2 } }, { "similarity": 0.6547, "id": "iJ6kL7mN8oP", "filename": "iJ6kL7mN8oP.jpg", "path": "/tmp/batch_123_abc456/iJ6kL7mN8oP.jpg", "metadata": { "title": "Mars Colony 2050: Humanity's Next Home", "videoViews": null, "categories": [], "videoType": "unknown" }, "youtubeThumbnailUrl": "https://img.youtube.com/vi/iJ6kL7mN8oP/hqdefault.jpg", "youtubeMaxResUrl": "https://img.youtube.com/vi/iJ6kL7mN8oP/maxresdefault.jpg", "youtubeVideoUrl": "https://www.youtube.com/watch?v=iJ6kL7mN8oP", "fullLocalPath": "//tmp/batch_123_abc456/iJ6kL7mN8oP.jpg", "videoData": { "viewCount": 956234, "lengthSeconds": "2156", "description": "An in-depth look at the plans and technology needed to establish a permanent human colony on Mars by 2050.", "thumbnail": [ { "url": "https://i.ytimg.com/vi/iJ6kL7mN8oP/hqdefault.jpg", "width": 336, "height": 188 }, { "url": "https://i.ytimg.com/vi_webp/iJ6kL7mN8oP/maxresdefault.webp", "width": 1920, "height": 1080 } ], "keywords": [ "mars", "colony", "future", "space", "technology", "science", "humanity" ], "channelTitle": "Future Tech Today", "channelId": "UCqRs9012TuVwXyZaBcDeFg", "category": "Science & Technology", "publishDate": "2025-03-01T16:45:00-08:00", "uploadDate": "2025-03-01T16:45:00-08:00", "isFamilySafe": true, "isPrivate": false, "isLiveContent": false, "availableCountries": ["US", "GB", "CA", "AU", "DE", "FR"] }, "channelData": { "channelId": "UCqRs9012TuVwXyZaBcDeFg", "title": "Future Tech Today", "description": "Exploring the cutting-edge technologies that will shape our tomorrow.", "subscriberCount": 1450000, "videosCount": 289, "viewCount": 267834521, "channelHandle": "@futuretechtoday", "country": "Germany", "joinedDate": "2017-11-05", "avatar": [ { "url": "https://yt3.googleusercontent.com/example-avatar-url-3/s160-c-k-c0x00ffffff-no-rj", "width": 160, "height": 160 } ], "isFamilySafe": true }, "calculatedData": { "outlierScore": 1.12, "averageViewsPerVideo": 926762.34, "isOutlier": false, "outlierThreshold": 2 } } ] } ``` **Response Fields**: - `data` - Array of similar thumbnail result objects - `similarity` - Visual similarity score (0-1), higher indicates greater similarity - `id` - YouTube video ID - `filename` - Filename of the processed thumbnail - `path` - Temporary path where the thumbnail was processed - `metadata` - Basic video metadata - `title` - Title of the video - `videoViews` - View count (may be null) - `categories` - Video categories - `videoType` - Type of video content - `youtubeThumbnailUrl` - URL to the standard quality thumbnail - `youtubeMaxResUrl` - URL to the maximum resolution thumbnail - `youtubeVideoUrl` - Direct URL to the YouTube video - `fullLocalPath` - Full local path of the processed thumbnail - `videoData` - Comprehensive video information - `viewCount` - Total view count of the video - `lengthSeconds` - Video duration in seconds - `description` - Video description - `thumbnail` - Array of thumbnail objects at different resolutions - `keywords` - Video keywords/tags - `channelTitle` - Name of the channel - `channelId` - Unique channel identifier - `category` - Video category - `publishDate` - ISO 8601 date when the video was published - `uploadDate` - ISO 8601 date when the video was uploaded - `isFamilySafe` - Whether the video is marked as family-safe - `isPrivate` - Whether the video is private - `isLiveContent` - Whether the video is live content - `availableCountries` - List of country codes where the video is available - `channelData` - Channel information - `channelId` - Unique channel identifier - `title` - Channel name - `description` - Channel description - `subscriberCount` - Number of subscribers - `videosCount` - Total number of videos on the channel - `viewCount` - Total channel view count - `channelHandle` - YouTube handle (e.g., @channelname) - `country` - Country where the channel is based - `joinedDate` - Date when the channel was created - `avatar` - Array of channel avatar images - `isFamilySafe` - Whether the channel is family-safe - `calculatedData` - Calculated performance metrics - `outlierScore` - Score indicating how much the video outperforms the average - `averageViewsPerVideo` - Average views per video for the channel - `isOutlier` - Whether the video is considered an outlier - `outlierThreshold` - Threshold used to determine outlier status ## Error Responses ### Bad Request **Status Code**: `400 Bad Request` **Description**: The request was invalid or malformed. ```json { "error": { "code": 400, "message": "Invalid search parameters", "details": "Either text or image URL must be provided based on the selected search type" } } ``` ### Unauthorized **Status Code**: `401 Unauthorized` **Description**: Authentication credentials are missing or invalid. ```json { "error": { "code": 401, "message": "Unauthorized", "details": "Invalid API key or credentials not provided. Create your API key at https://dashboard.nexlev.io/nexlev-api/create-api-key" } } ``` ### Unprocessable Entity **Status Code**: `422 Unprocessable Entity` **Description**: The provided image URL could not be processed. ```json { "error": { "code": 422, "message": "Unable to process image", "details": "The provided image URL is not accessible or the image format is not supported" } } ``` ### Rate Limit **Status Code**: `429 Too Many Requests` **Description**: You have exceeded your API rate limit. ```json { "error": { "code": 429, "message": "Rate limit exceeded", "details": "You have exceeded your API quota. Please try again later.", "retryAfter": 3600 } } ``` ### Service Unavailable **Status Code**: `503 Service Unavailable` **Description**: The thumbnail similarity search service is temporarily unavailable. ```json { "error": { "code": 503, "message": "Thumbnail search service unavailable", "details": "The visual similarity service is temporarily unavailable. Please try again in a few minutes.", "retryAfter": 300 } } ```