# Yandex Images API Documentation

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.

- **Documentation:** [https://scrappa.co/docs/yandex-api/yandex_images](https://scrappa.co/docs/yandex-api/yandex_images)
- **API group:** Yandex API
- **Endpoint:** `GET https://scrappa.co/api/yandex/images`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | string | No | Search text. Send text or url, not both. Alias: q. |
| `url` | string | No | Public http or https image address for reverse image search. |
| `yandex_domain` | string | No | 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. |
| `page` | integer | No | 1-based page number, 1 to 20. Defaults to 1. |
| `site` | string | No | Only images from pages of this site, for example wikipedia.org. |
| `orientation` | string | No | horizontal, vertical or square. |
| `size` | string | No | large, medium or small. |
| `file_type` | string | No | jpg, png or gif. |

## Example response

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

| Status | Error | Description |
| --- | --- | --- |
| 422 | 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. |
| 503 | Service Unavailable | Returned when Yandex could not be read after several attempts. Failed requests are not charged. Try again. |
| 502 | Unexpected Response | Returned when Yandex answers with a page this API cannot read, or an image cannot be read. Failed requests are not charged. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)