Logo SearchApi

Yandex Images API Documentation

GET   /api/v1/search?engine=yandex_images
OpenAPI Initiative Download OpenAPI Spec

Search Yandex Images and retrieve image titles, source pages, original image URLs and dimensions, thumbnails, alternative sizes, and suggested queries as structured JSON.

API Parameters

Search Query

  • Name
    q
    Required
    Required
    Description

    The search terms used to find images on Yandex.

Localization

  • Name
    yandex_domain
    Required
    Optional
    Description

    The Yandex endpoint to request. Regional aliases may redirect to another Yandex domain, so the domain does not guarantee a country or language. Use location to select a region. See the supported Yandex domains.

  • Name
    location
    Required
    Optional
    Description

    The location ID used to localize results, such as 213 for Moscow. Results vary most between locations in Russia, the CIS, and Turkey. Set it for consistent localization across requests. See the supported Yandex locations.

Filters

  • Name
    size
    Required
    Optional
    Description

    Filter by image size: large, medium, small, or wallpaper. Combine wallpaper with aspect_ratio to choose desktop (wide) or phone (tall) wallpapers.

  • Name
    exact_size
    Required
    Optional
    Description

    Find images with exactly the specified width and height, in WIDTHxHEIGHT format, such as 800x600. Both dimensions must be integers from 1 to 100000 pixels (the API request limit). Overrides size.

  • Name
    aspect_ratio
    Required
    Optional
    Description

    Filter by aspect ratio: square, wide, or tall. Square results may have approximately equal dimensions.

  • Name
    image_type
    Required
    Optional
    Description

    Use Yandex's image classifications: photo, clipart (white background), line_drawing (drawings and illustrations), face, or demotivator.

  • Name
    color
    Required
    Optional
    Description

    Filter by color, black_and_white, red, orange, yellow, cyan, green, blue, violet, white, or black.

  • Name
    file_type
    Required
    Optional
    Description

    Filter by jpg, png, or gif. The GIF filter selects images Yandex classifies as animated. A file URL's extension may differ from its actual format.

  • Name
    site
    Required
    Optional
    Description

    Restrict source pages to a domain, such as wikipedia.org. Subdomains are included. HTTP(S) URLs are reduced to their lowercase hostname. A leading www. is removed unless the rest is a public suffix, as in www.gov.uk. Paths, queries, fragments, and ports are discarded. Use ASCII or punycode domain names of at most 253 characters.

Pagination

  • Name
    page
    Required
    Optional
    Description

    Page number from 1 to 41 for yandex.ru, ya.ru, and yandex.fr, or 1 to 2 for other domains and locations in Belarus or Kazakhstan. Higher pages return a validation error. Queries can run out of results before the limit.

Engine

  • Name
    engine
    Required
    Required
    Description

    Set to yandex_images.

API key

  • Name
    api_key
    Required
    Required
    Description

    Your SearchApi API key. Pass it in the api_key query parameter or the Authorization: Bearer YOUR_API_KEY header.

Zero Data Retention

  • Name
    zero_retention
    Enterprise Only
    Enterprise Only
    Required
    Optional
    Description

    Set to true to disable logging and persistent storage of request parameters, HTML, and JSON responses.

API Examples

Image Results

Image Results
GET
https://www.searchapi.io/api/v1/search?engine=yandex_images&q=cats
Request
import requests

url = "https://www.searchapi.io/api/v1/search"
params = {
  "engine": "yandex_images",
  "q": "cats"
}

response = requests.get(url, params=params)
print(response.text)
Response
{
  "search_metadata": {
    "id": "search_e4Y69DMlgLWRiBOpXxN0K2Vb",
    "status": "Success",
    "created_at": "2026-10-23T18:27:50Z",
    "request_time_taken": 4.88,
    "parsing_time_taken": 0.01,
    "total_time_taken": 4.9,
    "request_url": "https://www.yandex.com/images/search?text=cats",
    "html_url": "https://www.searchapi.io/api/v1/searches/search_e4Y69DMlgLWRiBOpXxN0K2Vb.html",
    "json_url": "https://www.searchapi.io/api/v1/searches/search_e4Y69DMlgLWRiBOpXxN0K2Vb"
  },
  "search_parameters": {
    "engine": "yandex_images",
    "q": "cats",
    "yandex_domain": "yandex.com"
  },
  "search_information": {
    "query_displayed": "cats"
  },
  "suggestions": [
    {
      "title": "Котята",
      "query": "Котята",
      "link": "https://www.yandex.com/images/search?nomisspell=1&text=%D0%9A%D0%BE%D1%82%D1%8F%D1%82%D0%B0",
      "thumbnail": "https://avatars.mds.yandex.net/get-imgs-tags/18043618/t51_vq0SR5D2AYr6BaUaRpzV/horizontal"
    },
    {
      "title": "Дикие кошки",
      "query": "Дикие кошки",
      "link": "https://www.yandex.com/images/search?nomisspell=1&text=%D0%94%D0%B8%D0%BA%D0%B8%D0%B5+%D0%BA%D0%BE%D1%88%D0%BA%D0%B8",
      "thumbnail": "https://avatars.mds.yandex.net/get-imgs-tags/17689637/t51_4s8df7Om4qCIwOaVr9Y1/horizontal"
    }
  ],
  "images": [
    {
      "position": 1,
      "title": "Pinterest Cat Photo",
      "snippet": "Pinterest cat photo.",
      "source": {
        "name": "ru.pinterest.com",
        "link": "https://ru.pinterest.com/ideas/pinterest-cat-photo/910343365143/"
      },
      "original": {
        "link": "https://i.pinimg.com/474x/be/61/f9/be61f90308ce2c055419be9410269530.jpg",
        "width": 474,
        "height": 842,
        "size_in_bytes": 61978
      },
      "thumbnail": "https://avatars.mds.yandex.net/i?id=2b3e32b254eb623748a7d826cef9dd8c3ae37e7a-4600332-images-thumbs&n=13",
      "yandex_link": "https://www.yandex.com/images/search?pos=0&img_url=https%3A%2F%2Fi.pinimg.com%2Foriginals%2Fbe%2F61%2Ff9%2Fbe61f90308ce2c055419be9410269530.jpg&search_client=unknown&text=cats&rpt=simage",
      "other_sizes": [
        {
          "link": "https://avatars.dzeninfra.ru/get-zen_doc/271828/pub_6a87493df19820512443d33d_6a874c4c1f4cc43d1a45fff2/scale_1200",
          "width": 675,
          "height": 1200,
          "size_in_bytes": 130315
        },
        {
          "link": "https://i.pinimg.com/236x/be/61/f9/be61f90308ce2c055419be9410269530.jpg",
          "width": 236,
          "height": 419,
          "size_in_bytes": 20978
        }
      ]
    },
    {
      "position": 2,
      "title": "Stylish Cat Photo Ideas",
      "snippet": "Find and save ideas about stylish cat photo ideas on Pinterest.",
      "source": {
        "name": "ie.pinterest.com",
        "link": "https://ie.pinterest.com/ideas/stylish-cat-photo-ideas/948658695877/"
      },
      "original": {
        "link": "https://i.pinimg.com/474x/a3/0f/b6/a30fb6e6077e69c85243b4a629ed6212.jpg",
        "width": 474,
        "height": 869,
        "size_in_bytes": 85854
      },
      "thumbnail": "https://avatars.mds.yandex.net/i?id=91a4d18d49e2d1c3c3a1f68e28e59776b8efd4bc-8169697-images-thumbs&n=13",
      "yandex_link": "https://www.yandex.com/images/search?pos=1&img_url=https%3A%2F%2Fi.pinimg.com%2Foriginals%2Fa3%2F0f%2Fb6%2Fa30fb6e6077e69c85243b4a629ed6212.png&search_client=unknown&text=cats&rpt=simage",
      "other_sizes": [
        {
          "link": "https://i.pinimg.com/originals/a3/0f/b6/a30fb6e6077e69c85243b4a629ed6212.png?nii=t",
          "width": 768,
          "height": 1408,
          "size_in_bytes": 1849994
        },
        {
          "link": "https://sun9-6.vkuserphoto.ru/s/v1/ig2/vxfrUzLViwQ_8Ww1GsvgO9GBkhhntW_n-hkSRSy_-lQk-Yndii0i_p-gjhHONcJW8nq_sKxKl6UJfMpfPFGlfvr5.jpg?quality=95&as=32x52,48x78,72x118,108x176,160x261,240x392,360x588,480x784,540x882,640x1045,720x1176,981x1602&from=bu&cs=640x0",
          "width": 640,
          "height": 1045,
          "size_in_bytes": 269267
        }
      ]
    }
  ],
  "pagination": {
    "current": 1,
    "next": "https://www.yandex.com/images/search?text=cats&p=1"
  }
}

The images array contains the ranked results. Each result includes its source page, the original image file from that page, a thumbnail URL, and a yandex_link to the image in the Yandex Images viewer. Animated results include is_gif. other_sizes lists other copies of the same picture, largest first. A copy can be larger than original and hosted on another website. suggestions contains refined queries, and related_searches contains related queries when Yandex shows them. Suggestions may be in Russian regardless of the selected domain. pagination.next and pagination.previous link to the adjacent Yandex results pages. Use the API's page parameter to retrieve a page as JSON. yandex.ru, ya.ru, and yandex.fr support pages 1 to 41. Every other domain, including the default yandex.com, supports pages 1 to 2. Locations in Belarus and Kazakhstan are served by yandex.by and yandex.kz, so they also support pages 1 to 2. pagination.next is omitted at the supported page limit and when Yandex returns fewer than 30 images. A full page can still be the final page, so following pagination.next may return an empty result set. Keep the same domain, query, filters, and explicit location when paging. Results may overlap or change between requests, so deduplicate by original.link when collecting multiple pages.

An empty result set returns HTTP 200 with error: "Yandex Images didn't return any results." in place of results.

Exact Image Dimensions

Exact Image Dimensions
GET
https://www.searchapi.io/api/v1/search?engine=yandex_images&exact_size=800x600&q=cats
Request
import requests

url = "https://www.searchapi.io/api/v1/search"
params = {
  "engine": "yandex_images",
  "q": "cats",
  "exact_size": "800x600"
}

response = requests.get(url, params=params)
print(response.text)
Response
{
  "search_metadata": {
    "id": "search_OxE2l6wMgOJVS0mp9PbYq4Kv",
    "status": "Success",
    "created_at": "2026-10-23T18:27:55Z",
    "request_time_taken": 3.76,
    "parsing_time_taken": 0.0,
    "total_time_taken": 3.77,
    "request_url": "https://www.yandex.com/images/search?text=cats&isize=eq&iw=800&ih=600",
    "html_url": "https://www.searchapi.io/api/v1/searches/search_OxE2l6wMgOJVS0mp9PbYq4Kv.html",
    "json_url": "https://www.searchapi.io/api/v1/searches/search_OxE2l6wMgOJVS0mp9PbYq4Kv"
  },
  "search_parameters": {
    "engine": "yandex_images",
    "q": "cats",
    "yandex_domain": "yandex.com",
    "exact_size": "800x600"
  },
  "search_information": {
    "query_displayed": "cats"
  },
  "suggestions": [
    {
      "title": "Котята",
      "query": "Котята",
      "link": "https://www.yandex.com/images/search?isize=eq&iw=800&ih=600&nomisspell=1&text=%D0%9A%D0%BE%D1%82%D1%8F%D1%82%D0%B0",
      "thumbnail": "https://avatars.mds.yandex.net/get-imgs-tags/18043618/t51_vq0SR5D2AYr6BaUaRpzV/horizontal"
    },
    {
      "title": "Дикие кошки",
      "query": "Дикие кошки",
      "link": "https://www.yandex.com/images/search?isize=eq&iw=800&ih=600&nomisspell=1&text=%D0%94%D0%B8%D0%BA%D0%B8%D0%B5+%D0%BA%D0%BE%D1%88%D0%BA%D0%B8",
      "thumbnail": "https://avatars.mds.yandex.net/get-imgs-tags/17689637/t51_4s8df7Om4qCIwOaVr9Y1/horizontal"
    }
  ],
  "images": [
    {
      "position": 1,
      "title": "Кошки - Мой питомец - сайт любителей собак, кошек и не только",
      "source": {
        "name": "mepet.ru",
        "link": "https://mepet.ru/breed/cats.html?liter=%D0%91"
      },
      "original": {
        "link": "https://mepet.ru/photo/breed/158512641310.jpg",
        "width": 800,
        "height": 600,
        "size_in_bytes": 96574
      },
      "thumbnail": "https://avatars.mds.yandex.net/i?id=46aa3688c63dab5494ff6acd7d1d5a0fe509dd4e-8486579-images-thumbs&n=13",
      "yandex_link": "https://www.yandex.com/images/search?ih=600&iw=800&search_client=unknown&text=cats&pos=0&isize=eq&rpt=simage&img_url=https%3A%2F%2Fimages.pexels.com%2Fphotos%2F357141%2Fpexels-photo-357141.jpeg%3Fauto%3Dcompress%26amp%3Bcs%3Dtinysrgb%26amp%3Bh%3D627%26amp%3Bfit%3Dcrop%26amp%3Bw%3D1200"
    },
    {
      "position": 2,
      "title": "Описание породы кошек - Шантильи-тиффани",
      "snippet": "Шантильи-тиффани .",
      "source": {
        "name": "mepet.ru",
        "link": "https://mepet.ru/breed/cats/shantili-tiffani.html"
      },
      "original": {
        "link": "https://mepet.ru/photo/breed/158547141091.jpg",
        "width": 800,
        "height": 600,
        "size_in_bytes": 47197
      },
      "thumbnail": "https://avatars.mds.yandex.net/i?id=f23c3116507fff2e89ef7f4f5e13b09eca3283d7-5232562-images-thumbs&n=13",
      "yandex_link": "https://www.yandex.com/images/search?ih=600&iw=800&search_client=unknown&text=cats&pos=1&isize=eq&rpt=simage&img_url=https%3A%2F%2Fstatic.wikia.nocookie.net%2Fwarriors-shattered%2Fimages%2F9%2F92%2FShadelight.temporary.jpeg%2Frevision%2Flatest%3Fcb%3D20210607184056"
    }
  ],
  "pagination": {
    "current": 1,
    "next": "https://www.yandex.com/images/search?ih=600&isize=eq&iw=800&text=cats&p=1"
  }
}

Wallpapers

Wallpapers
GET
https://www.searchapi.io/api/v1/search?aspect_ratio=tall&engine=yandex_images&q=cats&size=wallpaper
Request
import requests

url = "https://www.searchapi.io/api/v1/search"
params = {
  "engine": "yandex_images",
  "q": "cats",
  "size": "wallpaper",
  "aspect_ratio": "tall"
}

response = requests.get(url, params=params)
print(response.text)
Response
{
  "search_metadata": {
    "id": "search_AxENYzjKgR4Pcmk3D0M4GJbe",
    "status": "Success",
    "created_at": "2026-10-23T18:27:59Z",
    "request_time_taken": 2.2,
    "parsing_time_taken": 0.01,
    "total_time_taken": 2.21,
    "request_url": "https://www.yandex.com/images/search?text=cats&isize=wallpaper&iorient=vertical",
    "html_url": "https://www.searchapi.io/api/v1/searches/search_AxENYzjKgR4Pcmk3D0M4GJbe.html",
    "json_url": "https://www.searchapi.io/api/v1/searches/search_AxENYzjKgR4Pcmk3D0M4GJbe"
  },
  "search_parameters": {
    "engine": "yandex_images",
    "q": "cats",
    "yandex_domain": "yandex.com",
    "size": "wallpaper",
    "aspect_ratio": "tall"
  },
  "search_information": {
    "query_displayed": "cats"
  },
  "suggestions": [
    {
      "title": "Котята",
      "query": "Котята",
      "link": "https://www.yandex.com/images/search?isize=wallpaper&iorient=vertical&nomisspell=1&text=%D0%9A%D0%BE%D1%82%D1%8F%D1%82%D0%B0",
      "thumbnail": "https://avatars.mds.yandex.net/get-imgs-tags/18043618/t51_vq0SR5D2AYr6BaUaRpzV/horizontal"
    },
    {
      "title": "Дикие кошки",
      "query": "Дикие кошки",
      "link": "https://www.yandex.com/images/search?isize=wallpaper&iorient=vertical&nomisspell=1&text=%D0%94%D0%B8%D0%BA%D0%B8%D0%B5+%D0%BA%D0%BE%D1%88%D0%BA%D0%B8",
      "thumbnail": "https://avatars.mds.yandex.net/get-imgs-tags/17689637/t51_4s8df7Om4qCIwOaVr9Y1/horizontal"
    }
  ],
  "images": [
    {
      "position": 1,
      "title": "200 Cat photoes ideas cats, cat breeds, cute cat",
      "snippet": "Cat House.",
      "source": {
        "name": "pinterest.com",
        "link": "https://www.pinterest.com/petzgram/cat-photoes/"
      },
      "original": {
        "link": "https://i.pinimg.com/videos/thumbnails/originals/b9/bf/f5/b9bff5554633902c36c12cb1c3090276.0000000.jpg",
        "width": 720,
        "height": 1280,
        "size_in_bytes": 72986
      },
      "thumbnail": "https://avatars.mds.yandex.net/i?id=8922c071f7c841b4b8594eb36bef88ce0f9e56d8-12927189-images-thumbs&n=13",
      "yandex_link": "https://www.yandex.com/images/search?search_client=unknown&text=cats&pos=0&isize=wallpaper&rpt=simage&img_url=https%3A%2F%2Fi.pinimg.com%2Fvideos%2Fthumbnails%2Foriginals%2Fb9%2Fbf%2Ff5%2Fb9bff5554633902c36c12cb1c3090276.0000000.jpg&iorient=vertical",
      "other_sizes": [
        {
          "link": "https://is.zobj.net/image-server/v1/images?r=lnL-50NBPGGyH4d-NZRvFodSgQ5PpcYeMJwDIZglWNOS3Bn_GNDoJjLJmfhZfSPcJQHzfiOVAripMPCSmFqdroIjGzXfkMxt8A4XXb-dud1IHguYw1rvw07n0BJCqa5CPxcRcBlgBmqWgmoDAwFBQu4un4sMhOYW7n3YoE7riiVt5qEsgTrSmoBAlGnXdzB9khD8sYjoaD_b59tiz9jAciVsI0ZZLs_MLzpHjKALTQIl8u6ZI55tekXW5Mo",
          "width": 674,
          "height": 1198,
          "size_in_bytes": 46928
        }
      ]
    },
    {
      "position": 2,
      "title": "870 Cats ideas in 2025 cats, crazy cats, cute cats",
      "snippet": "Cool Cats.",
      "source": {
        "name": "au.pinterest.com",
        "link": "https://au.pinterest.com/catonaroof/cats/"
      },
      "original": {
        "link": "https://i.pinimg.com/videos/thumbnails/originals/80/b4/e8/80b4e89377b601db9570184725c07f5a.0000000.jpg",
        "width": 720,
        "height": 1280,
        "size_in_bytes": 55022
      },
      "thumbnail": "https://avatars.mds.yandex.net/i?id=fcf7aed27775714f5c4ace635e3a1e4f1604379d-5888854-images-thumbs&n=13",
      "yandex_link": "https://www.yandex.com/images/search?search_client=unknown&text=cats&pos=1&isize=wallpaper&rpt=simage&img_url=https%3A%2F%2Fi.pinimg.com%2Fvideos%2Fthumbnails%2Foriginals%2F18%2Fdd%2F95%2F18dd951d0b1882e4007dd46933f4420e.0000000.jpg&iorient=vertical"
    }
  ],
  "pagination": {
    "current": 1,
    "next": "https://www.yandex.com/images/search?iorient=vertical&isize=wallpaper&text=cats&p=1"
  }
}