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.

Search Similar Thumbnails

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):

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):

{
  "text": "WW2 Documentary"
}

Request Body (Image URL Search):

{
  "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.

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:

{
  "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

Status Code: 400 Bad Request

Description: The request was invalid or malformed.

{
  "error": {
    "code": 400,
    "message": "Invalid search parameters",
    "details": "Either text or image URL must be provided based on the selected search type"
  }
}

Status Code: 401 Unauthorized

Description: Authentication credentials are missing or invalid.

{
  "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"
  }
}

Status Code: 422 Unprocessable Entity

Description: The provided image URL could not be processed.

{
  "error": {
    "code": 422,
    "message": "Unable to process image",
    "details": "The provided image URL is not accessible or the image format is not supported"
  }
}

Status Code: 429 Too Many Requests

Description: You have exceeded your API rate limit.

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded",
    "details": "You have exceeded your API quota. Please try again later.",
    "retryAfter": 3600
  }
}

Status Code: 503 Service Unavailable

Description: The thumbnail similarity search service is temporarily unavailable.

{
  "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
  }
}