Two modes in one endpoint. Send text to search images: each result has the original image URL, its size in pixels and bytes, the thumbnail, the source site and page, and other sizes of the same picture. Filter by orientation, size, file_type and site; an image that breaks a filter is never returned. Page 2 and later come from the Russian index, so they can differ from page 1. Send url instead of text to search by image: the response has the detected objects, tags, other sizes, visually similar images and the sites that show the picture. The url must be a public image address; a picture Yandex cannot read answers 502 and is not charged. A reverse search takes the url only. Filters such as recent, type and color are not supported and answer 422. Each successful request costs 1 credit.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
This endpoint has no required query parameters.
8 optional filters available.
string
Optional
Search text. Send text or url, not both. Alias: q.
cat
string
Optional
Public http or https image address for reverse image search.
https://example.com/product
string
Optional
Yandex site to search. Web and videos: com (default), ru, kz, by or com.tr. Images: com (default), ru, kz or by. Each site has its own index.
example
integer
Optional
1-based page number, 1 to 20. Defaults to 1.
1
string
Optional
Only images from pages of this site, for example wikipedia.org.
example
string
Optional
horizontal, vertical or square.
vertical
string
Optional
large, medium or small.
example
string
Optional
jpg, png or gif.
example
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
meta
success
pagination
images_results
related_searches
search_information
Common images_results fields
title
is_gif
source
original
{
"meta": {
"billable": true,
"duration_ms": 2400,
"upstream_calls": 2
},
"success": true,
"pagination": {
"page": 1,
"has_next_page": true
},
"images_results": [
{
"title": "Pinterest Cat Photo",
"is_gif": false,
"source": "ru.pinterest.com",
"original": "https://i.pinimg.com/474x/be/61/f9/be61f90308ce2c055419be9410269530.jpg",
"position": 1,
"thumbnail": "https://avatars.mds.yandex.net/i?id=2b3e32b254eb623748a7d826cef9dd8c3ae37e7a-4600332-images-thumbs&n=13",
"other_sizes": [
{
"url": "https://i.pinimg.com/236x/be/61/f9/be61f90308ce2c055419be9410269530.jpg",
"width": 236,
"height": 419,
"file_size_bytes": 20978
}
],
"source_page": "https://ru.pinterest.com/ideas/pinterest-cat-photo/910343365143/",
"original_width": 474,
"file_size_bytes": 61978,
"original_height": 842,
"thumbnail_width": 474,
"thumbnail_height": 842
}
],
"related_searches": [],
"search_information": {
"page": 1,
"query": "cat",
"yandex_domain": "com"
}
}Errors
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
Returned when a required parameter is missing, a value is out of range or a parameter is not supported. No credits are charged.
Service Unavailable
Returned when Yandex could not be read after several attempts. Failed requests are not charged. Try again.
Unexpected Response
Returned when Yandex answers with a page this API cannot read, or an image cannot be read. Failed requests are not charged.
Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.