Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

Searching by text description

Written by
Improved by
Updated at November 27, 2025

You can use Yandex Search API to search through the Yandex Images index by text description and get search results in XML format. You can run queries using the Yandex Cloud ML SDK, REST API, and gRPC API. The search results you get depend on the parameters specified in your query.

Getting started

Sign up for Yandex Cloud and create a billing account:

  1. Navigate to the management console and log in to Yandex Cloud or create a new account.
  2. On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status. If you do not have a billing account, create one and link a cloud to it.

If you have an active billing account, you can navigate to the cloud page to create or select a folder for your infrastructure.

Learn more about clouds and folders here.

Get your cloud ready

To use the examples:

  1. Create a service account and assign the search-api.webSearch.user role to it.

  2. Get and save the service account's API key with yc.search-api.execute for its scope.

    The following examples use API key authentication. Yandex Cloud ML SDK also supports IAM token and OAuth token authentication. For more information, see Authentication in Yandex Cloud ML SDK.

    Note

    If you are using Windows, we recommend installing the WSL shell first and using it to proceed.

  3. Install Python 3.10 or higher.

  4. Install Python venv to create isolated virtual environments in Python.

  5. Create a new Python virtual environment and activate it:

    python3 -m venv new-env
source new-env/bin/activate

  6. Use the pip package manager to install the ML SDK library:

    pip install yandex-cloud-ml-sdk

  1. Create a service account you will use to send requests. You can also use a Yandex account or a federated account, but a service account is a better choice for automation purposes.

  2. Assign the search-api.webSearch.user role to the account you will use to send requests.

  3. Get an IAM token, which is required for authentication.

    The following examples use IAM token authentication. To use a service account's API key for authentication, edit the Authorization header in the query examples. For more information, see API authentication.

To use the examples, you should additionally install cURL and jq.

  1. Create a service account you will use to send requests. You can also use a Yandex account or a federated account, but a service account is a better choice for automation purposes.

  2. Assign the search-api.webSearch.user role to the account you will use to send requests.

  3. Get an IAM token, which is required for authentication.

    The following examples use IAM token authentication. To use a service account's API key for authentication, edit the Authorization header in the query examples. For more information, see API authentication.

To use the examples, you should additionally install gRPCurl and jq.

Send a search query

To run a search query:

  1. Create a file named pic-search-by-text.py and paste the following code into it:

    #!/usr/bin/env python3

from __future__ import annotations

from yandex_cloud_ml_sdk import YCloudML

from yandex_cloud_ml_sdk.search_api import (
    FamilyMode,
    FixTypoMode,
    ImageColor,
    ImageFormat,
    ImageOrientation,
    ImageSize,
    SearchType,
)

import pathlib

USER_AGENT = "Mozilla/5.0 (Linux; Android 13; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.6422.112 Mobile Safari/537.36"


def main() -> None:
    sdk = YCloudML(
        folder_id="<folder_ID>",
        auth="<API_key>",
    )
    sdk.setup_default_logging()

    # you could pass any settings when creating the Search object
    search = sdk.search_api.image(
        "RU",
        family_mode=FamilyMode.MODERATE,
        # By default object configuration property values are set to None,
        # which corresponds to the "default" value which is
        # defined at the service's backend.
        # e.g. docs_in_group=None,
    )

    # but you can also reconfigure the Search object at any time:
    search = search.configure(
        # These are enum-type settings,
        # they could be passed as strings as shown below.
        search_type="kk",
        family_mode="strict",
        fix_typo_mode="off",
        format="jpeg",
        size="LARGE",
        orientation="vertical",
        color="GRAYSCALE",
        docs_on_page=3,
        site="yandex.ru",
        user_agent=USER_AGENT,
    )

    search = search.configure(
        # any enum-like option may also be passed as an explicit enum option;
        # this might be helpful to control and understand which values there can be
        search_type=SearchType.RU,
        family_mode=FamilyMode.STRICT,
        fix_typo_mode=FixTypoMode.OFF,
        format=ImageFormat.JPEG,
        size=ImageSize.LARGE,
        orientation=ImageOrientation.VERTICAL,
        color=ImageColor.GRAYSCALE,
        docs_on_page=5,
    )

    search_query = input("Enter the search query: ")
    if not search_query.strip():
        search_query = "Yandex Cloud"

    for i in range(5):
        search_result = search.run(search_query, format="xml", page=i)

        output_filename = (
            str(pathlib.Path(__file__).parent) + "/" + "page_" + str(i) + ".xml"
        )
        file = open(output_filename, "a")
        file.write(search_result.decode("utf-8"))
        print(f"Page {i} saved to file {output_filename}")
        file.close()


if __name__ == "__main__":
    main()

    Where:

    You can set the search parameters in the relevant search_api.image class object properties or the .configure method properties:

    Description of object properties

    • search_type: Search type. The possible values are:

      • ru: For the Russian search type.
      • tr: For the Turkish search type.
      • com: For the International search type.
      • kk: For the Kazakh search type.
      • be: For the Belarusian search type.
      • uz: For the Uzbek search type.

    • family_mode: Results filtering. This is an optional parameter. The possible values are:

      • moderate: Moderate filter (default). Adult category documents are excluded from search results unless the query explicitly targets resources of this category.
      • none: Filtering is off. Search results include any documents regardless of their contents.
      • strict: Family filter. Regardless of the search query, Adult category documents and documents containing profanity are excluded from search results.

    • fix_typo_mode: Search query typo correction setting. This is an optional parameter. The possible values are:

      • on: Typo correction enabled (default). Search query typos are corrected automatically.
      • off: Typo correction disabled. Search query typos are not corrected. The search is performed strictly as per the query.

    • format: Searching for images of specified format. This is an optional parameter. If not set, the search includes images of all formats. The possible values are:

    • size: Searching for images of specified size. This is an optional parameter. If not set, the search includes images of all sizes. The possible values are:

      • enormous: Very large images (over 1600 × 1200 in pixels).
      • large: Large images (from 800 × 600 to 1600 × 1200 in pixels).
      • medium: Medium images (from 150 × 150 to 800 × 600 in pixels).
      • small: Small images (from 32 × 32 to 150 × 150 in pixels).
      • tiny: Icons (up to 32 × 32 in pixels).
      • wallpaper: Wallpaper images.

    • orientation: Searching for images of specified orientation. This is an optional parameter. If not set, the search includes images of any orientation. The possible values are:

      • vertical: Vertical images.
      • horizontal: Horizontal images.
      • square: Square aspect ratio images.

    • color: Searching for images with specified color parameters. This is an optional parameter. If not set, the search includes images with any color parameters. The possible values are:

      • color: Colored images.
      • grayscale: Grayscale images.
      • red: Images with red as the main color.
      • orange: Images with orange as the main color.
      • yellow: Images with yellow as the main color.
      • green: Images with green as the main color.
      • cyan: Images with cyan as the main color.
      • blue: Images with blue as the main color.
      • violet: Images with violet as the main color.
      • white: Images with white as the main color.
      • black: Images with black as the main color.

    • docs_on_page: Number of result groups displayed per search result page. You can specify values between 1 and 60. This is an optional parameter. The default value is 20.

    • site: Searching for images only on specified website, e.g., yandex.cloud. This is an optional parameter. If not set, the search includes all websites in the search base.

    • user_agent: String containing the User-Agent header. Use this parameter to have your search results optimized for a specific device and browser, including mobile search results. This is an optional parameter. If not specified, you will get the default output.

  2. Run the file you created:

    python3 pic-search-by-text.py

    During the execution, the code will prompt you to enter the search query text and, as a result, will save the first five pages of search results for the specified query in XML format in the current directory:

    Page 0 saved to file /Users/MyUser/Desktop/page_0.xml
...
Page 4 saved to file /Users/MyUser/Desktop/page_4.xml

  1. Send a query and get a Base64-encoded result:

    1. Create a file with the request body, e.g., body.json:

      body.json

      {
  "query": {
    "searchType": "<search_type>",
    "queryText": "<search_query_text>",
    "familyMode": "<result_filter_setting_value>",
    "page": "<page_number>",
    "fixTypoMode": "<typo_correction_mode_setting_value>"
  },
  "imageSpec": {
    "format": "<image_format>",
    "size": "<image_size>",
    "orientation": "<image_orientation>",
    "color": "<image_color>"
  },
  "site": "<website_domain_name>",
  "docsOnPage": "<results_per_page>",
  "folderId": "<folder_ID>",
  "userAgent": "<User-Agent_header>"
}
      Description of fields

      • searchType: Search type. The possible values are:

        • SEARCH_TYPE_RU: For the Russian search type.
        • SEARCH_TYPE_TR: For the Turkish search type.
        • SEARCH_TYPE_COM: For the International search type.
        • SEARCH_TYPE_KK: For the Kazakh search type.
        • SEARCH_TYPE_BE: For the Belarusian search type.
        • SEARCH_TYPE_UZ: For the Uzbek search type.

      • queryText: Search query text. The maximum length is 400 characters.

      • familyMode: Results filtering. This is an optional parameter. The possible values are:

        • FAMILY_MODE_MODERATE: Moderate filter (default). Adult category documents are excluded from search results unless the query explicitly targets resources of this category.
        • FAMILY_MODE_NONE: Filtering is off. Search results include any documents regardless of their contents.
        • FAMILY_MODE_STRICT: Family filter. Regardless of the search query, Adult category documents and documents containing profanity are excluded from search results.

      • page: Requested page number. This is an optional parameter. By default, the first page with search results is returned. Page numbering starts from zero (0 stands for page one).

      • fixTypoMode: Search query typo correction setting. This is an optional parameter. The possible values are:

        • FIX_TYPO_MODE_ON: Typo correction enabled (default). Search query typos are corrected automatically.
        • FIX_TYPO_MODE_OFF: Typo correction disabled. Search query typos are not corrected. The search is performed strictly as per the query.

      • format: Searching for images of specified format. This is an optional parameter. If not set, the search includes images of all formats. The possible values are:

        • IMAGE_FORMAT_JPEG: JPG
        • IMAGE_FORMAT_GIF: GIF
        • IMAGE_FORMAT_PNG: PNG

      • size: Searching for images of specified size. This is an optional parameter. If not set, the search includes images of all sizes. The possible values are:

        • IMAGE_SIZE_ENORMOUS: Very large images (over 1600 × 1200 in pixels).
        • IMAGE_SIZE_LARGE: Large images (from 800 × 600 to 1600 × 1200 in pixels).
        • IMAGE_SIZE_MEDIUM: Medium images (from 150 × 150 to 800 × 600 in pixels).
        • IMAGE_SIZE_SMALL: Small images (from 32 × 32 to 150 × 150 in pixels).
        • IMAGE_SIZE_TINY: Icons (up to 32 × 32 in pixels).
        • IMAGE_SIZE_WALLPAPER: Wallpaper images.

      • orientation: Searching for images of specified orientation. This is an optional parameter. If not set, the search includes images of any orientation. The possible values are:

        • IMAGE_ORIENTATION_VERTICAL: Vertical images.
        • IMAGE_ORIENTATION_HORIZONTAL: Horizontal images.
        • IMAGE_ORIENTATION_SQUARE: Square aspect ratio images.

      • color: Searching for images with specified color parameters. This is an optional parameter. If not set, the search includes images with any color parameters. The possible values are:

        • IMAGE_COLOR_COLOR: Colored images.
        • IMAGE_COLOR_GRAYSCALE: Grayscale images.
        • IMAGE_COLOR_RED: Images with red as the main color.
        • IMAGE_COLOR_ORANGE: Images with orange as the main color.
        • IMAGE_COLOR_YELLOW: Images with yellow as the main color.
        • IMAGE_COLOR_GREEN: Images with green as the main color.
        • IMAGE_COLOR_CYAN: Images with cyan as the main color.
        • IMAGE_COLOR_BLUE: Images with blue as the main color.
        • IMAGE_COLOR_VIOLET: Images with violet as the main color.
        • IMAGE_COLOR_WHITE: Images with white as the main color.
        • IMAGE_COLOR_BLACK: Images with black as the main color.

      • site: Searching for images only on specified website, e.g., yandex.cloud. This is an optional parameter. If not set, the search includes all websites in the search base.

      • docsOnPage: Number of result groups displayed per search result page. You can specify values between 1 and 60. This is an optional parameter. The default value is 20.

      • folderId: Folder ID of the user or service account you will use for queries.

      • userAgent: String containing the User-Agent header. Use this parameter to have your search results optimized for a specific device and browser, including mobile search results. This is an optional parameter. If not specified, you will get the default output.

      Request body example

      body.json

      {
  "query": {
    "searchType": "SEARCH_TYPE_RU",
    "queryText": "cats"
  },
  "folderId": "b1gt6g8ht345********"
}

    2. Send an HTTP request specifying the IAM token you got earlier and a path to the request body file:

      curl \
  --request POST \
  --header "Authorization: Bearer <IAM_token>" \
  --data "@body.json" \
  "https://searchapi.api.cloud.yandex.net/v2/image/search" \
  > result.json

      The search query result will be saved to a file named result.json with a Base64-encoded XML response in the rawData field.

  2. Decode the result from Base64:

    echo "$(< result.json)" | \
  jq -r .rawData | \
  base64 --decode > result.xml

    The XML response to the query will be saved to a file named result.xml.

  1. Send a query and get a Base64-encoded result:

    1. Create a file with the request body, e.g., body.json:

      body.json

      {
  "query": {
    "search_type": "<search_type>",
    "query_text": "<search_query_text>",
    "family_mode": "<result_filter_setting_value>",
    "page": "<page_number>",
    "fix_typo_mode": "<typo_correction_mode_setting_value>"
  },
  "image_spec": {
    "format": "<image_format>",
    "size": "<image_size>",
    "orientation": "<image_orientation>",
    "color": "<image_color>"
  },
  "site": "<website_domain_name>",
  "docs_on_page": "<results_per_page>",
  "folder_id": "<folder_ID>",
  "user_agent": "<User-Agent_header>"
}
      Description of fields

      • search_type: Search type. The possible values are:

        • SEARCH_TYPE_RU: For the Russian search type.
        • SEARCH_TYPE_TR: For the Turkish search type.
        • SEARCH_TYPE_COM: For the International search type.
        • SEARCH_TYPE_KK: For the Kazakh search type.
        • SEARCH_TYPE_BE: For the Belarusian search type.
        • SEARCH_TYPE_UZ: For the Uzbek search type.

      • query_text: Search query text. The maximum length is 400 characters.

      • family_mode: Results filtering. This is an optional parameter. The possible values are:

        • FAMILY_MODE_MODERATE: Moderate filter (default). Adult category documents are excluded from search results unless the query explicitly targets resources of this category.
        • FAMILY_MODE_NONE: Filtering is off. Search results include any documents regardless of their contents.
        • FAMILY_MODE_STRICT: Family filter. Regardless of the search query, Adult category documents and documents containing profanity are excluded from search results.

      • page: Requested page number. This is an optional parameter. By default, the first page with search results is returned. Page numbering starts from zero (0 stands for page one).

      • fix_typo_mode: Search query typo correction setting. This is an optional parameter. The possible values are:

        • FIX_TYPO_MODE_ON: Typo correction enabled (default). Search query typos are corrected automatically.
        • FIX_TYPO_MODE_OFF: Typo correction disabled. Search query typos are not corrected. The search is performed strictly as per the query.

      • format: Searching for images of specified format. This is an optional parameter. If not set, the search includes images of all formats. The possible values are:

        • IMAGE_FORMAT_JPEG: JPG
        • IMAGE_FORMAT_GIF: GIF
        • IMAGE_FORMAT_PNG: PNG

      • size: Searching for images of specified size. This is an optional parameter. If not set, the search includes images of all sizes. The possible values are:

        • IMAGE_SIZE_ENORMOUS: Very large images (over 1600 × 1200 in pixels).
        • IMAGE_SIZE_LARGE: Large images (from 800 × 600 to 1600 × 1200 in pixels).
        • IMAGE_SIZE_MEDIUM: Medium images (from 150 × 150 to 800 × 600 in pixels).
        • IMAGE_SIZE_SMALL: Small images (from 32 × 32 to 150 × 150 in pixels).
        • IMAGE_SIZE_TINY: Icons (up to 32 × 32 in pixels).
        • IMAGE_SIZE_WALLPAPER: Wallpaper images.

      • orientation: Searching for images of specified orientation. This is an optional parameter. If not set, the search includes images of any orientation. The possible values are:

        • IMAGE_ORIENTATION_VERTICAL: Vertical images.
        • IMAGE_ORIENTATION_HORIZONTAL: Horizontal images.
        • IMAGE_ORIENTATION_SQUARE: Square aspect ratio images.

      • color: Searching for images with specified color parameters. This is an optional parameter. If not set, the search includes images with any color parameters. The possible values are:

        • IMAGE_COLOR_COLOR: Colored images.
        • IMAGE_COLOR_GRAYSCALE: Grayscale images.
        • IMAGE_COLOR_RED: Images with red as the main color.
        • IMAGE_COLOR_ORANGE: Images with orange as the main color.
        • IMAGE_COLOR_YELLOW: Images with yellow as the main color.
        • IMAGE_COLOR_GREEN: Images with green as the main color.
        • IMAGE_COLOR_CYAN: Images with cyan as the main color.
        • IMAGE_COLOR_BLUE: Images with blue as the main color.
        • IMAGE_COLOR_VIOLET: Images with violet as the main color.
        • IMAGE_COLOR_WHITE: Images with white as the main color.
        • IMAGE_COLOR_BLACK: Images with black as the main color.

      • site: Searching for images only on specified website, e.g., yandex.cloud. This is an optional parameter. If not set, the search includes all websites in the search base.

      • docs_on_page: Number of result groups displayed per search result page. You can specify values between 1 and 60. This is an optional parameter. The default value is 20.

      • folder_id: Folder ID of the user or service account you will use for queries.

      • user_agent: String containing the User-Agent header. Use this parameter to have your search results optimized for a specific device and browser, including mobile search results. This is an optional parameter. If not specified, you will get the default output.

      Request body example

      body.json

      {
  "query": {
    "search_type": "SEARCH_TYPE_RU",
    "query_text": "cats"
  },
  "folder_id": "b1gt6g8ht345********"
}

    2. Run a gRPC call specifying the IAM token you got earlier and a path to the request body file:

      grpcurl \
  -rpc-header "Authorization: Bearer <IAM_token>" \
  -d @ < body.json \
  searchapi.api.cloud.yandex.net:443 yandex.cloud.searchapi.v2.ImageSearchService/Search \
  > result.json

      The search query result will be saved to a file named result.json with a Base64-encoded XML response in the rawData field.

  2. Decode the result from Base64:

    echo "$(< result.json)" | \
  jq -r .rawData | \
  base64 --decode > result.xml

    The XML response to the query will be saved to a file named result.xml.

See also

Previous
Text search in deferred mode
Next
Searching by image