Связаться с намиПодключиться

Поиск изображений по текстовому описанию

Статья создана
Улучшена
Обновлена 12 ноября 2025 г.

Сервис Yandex Search API позволяет искать изображения по текстовым описаниям в индексе Яндекс Картинок и получать результат поиска в формате XML. Выполнять запросы можно с помощью Yandex Cloud ML SDK, REST API и gRPC API. Поисковая выдача зависит от заданных в запросе параметров.

Перед началом работы

Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:

  1. Перейдите в консоль управления, затем войдите в Yandex Cloud или зарегистрируйтесь.
  2. На странице Yandex Cloud Billing убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его и привяжите к нему облако.

Если у вас есть активный платежный аккаунт, вы можете создать или выбрать каталог, в котором будет работать ваша инфраструктура, на странице облака.

Подробнее об облаках и каталогах.

Подготовьте облако к работе

Чтобы воспользоваться примерами:

  1. Создайте сервисный аккаунт и назначьте ему роль search-api.webSearch.user.

  2. Получите и сохраните API-ключ сервисного аккаунта, указав для него область действия yc.search-api.execute.

    В примерах используется аутентификация с помощью API-ключа. Yandex Cloud ML SDK также поддерживает аутентификацию с помощью IAM-токена и OAuth-токена. Подробнее см. в разделе Аутентификация в Yandex Cloud ML SDK.

    Примечание

    Если вы используете ОС Windows, рекомендуем предварительно установить оболочку WSL и выполнять дальнейшие действия в этой оболочке.

  3. Установите Python версии 3.10 или выше.

  4. Установите библиотеку Python venv для создания изолированных виртуальных окружений в Python.

  5. Создайте и войдите в новое виртуальное окружение Python:

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

  6. С помощью менеджера пакетов pip установите библиотеку ML SDK:

    pip install yandex-cloud-ml-sdk

  1. Создайте сервисный аккаунт, от имени которого будут выполняться запросы. Вы также можете использовать аккаунт на Яндексе или федеративный аккаунт, но для автоматизации предпочтительнее использовать сервисный аккаунт.

  2. Назначьте аккаунту, от имени которого будут выполняться запросы, роль search-api.webSearch.user.

  3. Получите IAM-токен, необходимый для аутентификации.

    В приведенных примерах используется аутентификация с помощью IAM-токена. Чтобы использовать для аутентификации API-ключ сервисного аккаунта, измените в примерах запросов заголовок Authorization. Подробнее см. в разделе Аутентификация в API.

Чтобы воспользоваться примерами, также установите утилиты cURL и jq.

  1. Создайте сервисный аккаунт, от имени которого будут выполняться запросы. Вы также можете использовать аккаунт на Яндексе или федеративный аккаунт, но для автоматизации предпочтительнее использовать сервисный аккаунт.

  2. Назначьте аккаунту, от имени которого будут выполняться запросы, роль search-api.webSearch.user.

  3. Получите IAM-токен, необходимый для аутентификации.

    В приведенных примерах используется аутентификация с помощью IAM-токена. Чтобы использовать для аутентификации API-ключ сервисного аккаунта, измените в примерах запросов заголовок Authorization. Подробнее см. в разделе Аутентификация в API.

Чтобы воспользоваться примерами, также установите утилиты gRPCurl и jq.

Выполните поисковый запрос

Чтобы выполнить поисковый запрос:

  1. Создайте файл pic-search-by-text.py и добавьте в него следующий код:

    #!/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="<идентификатор_каталога>",
        auth="<API-ключ>",
    )
    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()

    Где:

    Параметры поиска вы можете задать в свойствах соответствующего объекта класса search_api.image или в свойствах метода .configure:

    Описание свойств объекта

    • search_type — тип поиска. Возможные значения:

      • ru — для типа поиска Русский.
      • tr — для типа поиска Турецкий.
      • com — для типа поиска Международный.
      • kk — для типа поиска Казахский.
      • be – для типа поиска Белорусский.
      • uz — для типа поиска Узбекский.

    • family_mode — фильтрация результатов. Необязательный параметр. Возможные значения:

      • moderate — умеренный фильтр (значение по умолчанию). Из выдачи исключаются документы, относящиеся к категории «для взрослых», если запрос явно не направлен на поиск подобных ресурсов.
      • none — фильтрация отключена. В выдачу включаются любые документы, вне зависимости от содержимого.
      • strict — семейный фильтр. Вне зависимости от поискового запроса из выдачи исключаются документы, относящиеся к категории «для взрослых», а также содержащие ненормативную лексику.

    • fix_typo_mode — значение настройки режима исправления опечаток в поисковом запросе. Необязательный параметр. Возможные значения:

      • on — исправление опечаток включено (значение по умолчанию). Опечатки в тексте поискового запроса автоматически исправляются.
      • off — исправление опечаток отключено. Опечатки в тексте поискового запроса не исправляются, поиск выполняется в полном соответствии с переданным запросом.

    • format — поиск изображений указанного формата. Необязательный параметр. Если параметр не задан, выполняется поиск по изображениям всех форматов. Возможные значения:

      • jpeg — формат JPG.
      • gif — формат GIF.
      • png — формат PNG.

    • size — поиск изображений указанного размера. Необязательный параметр. Если параметр не задан, выполняется поиск по изображениям всех размеров. Возможные значения:

      • enormous — изображения очень большого размера (более 1600 × 1200 в пикселях).
      • large — изображения большого размера (от 800 × 600 до 1600 × 1200 в пикселях).
      • medium — изображения среднего размера (от 150 × 150 до 800 × 600 в пикселях).
      • small — изображения маленького размера (от 32 × 32 до 150 × 150 в пикселях).
      • tiny — иконки (не более 32 × 32 в пикселях).
      • wallpaper — обои для рабочего стола.

    • orientation — поиск изображений с указанной ориентацией. Необязательный параметр. Если параметр не задан, выполняется поиск по изображениям с любой ориентацией. Возможные значения:

      • vertical — изображения с вертикальной ориентацией.
      • horizontal — изображения с горизонтальной ориентацией.
      • square — изображения с равными сторонами (квадрат).

    • color — поиск изображений с заданными параметрами цвета. Необязательный параметр. Если параметр не задан, выполняется поиск по изображениям с любыми цветовыми параметрами. Возможные значения:

      • color — цветные изображения.
      • grayscale — черно-белые изображения.
      • red — изображения, в которых основной цвет — красный.
      • orange — изображения, в которых основной цвет — оранжевый.
      • yellow — изображения, в которых основной цвет — желтый.
      • green — изображения, в которых основной цвет — зеленый.
      • cyan — изображения, в которых основной цвет — голубой.
      • blue — изображения, в которых основной цвет — синий.
      • violet — изображения, в которых основной цвет — фиолетовый.
      • white — изображения, в которых основной цвет — белый.
      • black — изображения, в которых основной цвет — черный.

    • docs_on_page — количество групп результатов, которое выводится на одной странице с результатами поиска. Возможные значения — от 1 до 60. Необязательный параметр. Значение по умолчанию — 20.

    • site — поиск изображений только на указанном сайте. Например: yandex.cloud. Необязательный параметр. Если параметр не задан, поиск выполняется по всем сайтам поисковой базы.

    • user_agent — строка, содержащая заголовок User-Agent. Параметр позволяет получить поисковую выдачу, ориентированную на конкретное устройство и браузер, в том числе мобильную выдачу. Необязательный параметр. Если параметр не задан, сервис возвращает стандартную выдачу по умолчанию.

  2. Выполните созданный файл:

    python3 pic-search-by-text.py

    В процессе выполнения код запросит у вас текст поискового запроса и в результате выполнения сохранит в текущей директории первые пять страниц с результатами поиска по указанному запросу в XML-формате:

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

  1. Отправьте запрос и получите результат в кодировке Base64:

    1. Создайте файл с телом запроса (например, body.json):

      body.json

      {
  "query": {
    "searchType": "<тип_поиска>",
    "queryText": "<текст_поискового_запроса>",
    "familyMode": "<значение_настройки_фильтрации_результатов>",
    "page": "<номер_страницы>",
    "fixTypoMode": "<значение_настройки_режима_исправления_опечаток>"
  },
  "imageSpec": {
    "format": "<формат_изображения>",
    "size": "<размер_изображения>",
    "orientation": "<тип_ориентации_изображения>",
    "color": "<цвет_изображения>"
  },
  "site": "<доменное_имя_сайта>",
  "docsOnPage": "<количество_результатов_на_странице>",
  "folderId": "<идентификатор_каталога>",
  "userAgent": "<заголовок_User-Agent>"
}
      Описание полей

      • searchType — тип поиска. Возможные значения:

        • SEARCH_TYPE_RU — для типа поиска Русский.
        • SEARCH_TYPE_TR — для типа поиска Турецкий.
        • SEARCH_TYPE_COM — для типа поиска Международный.
        • SEARCH_TYPE_KK — для типа поиска Казахский.
        • SEARCH_TYPE_BE – для типа поиска Белорусский.
        • SEARCH_TYPE_UZ — для типа поиска Узбекский.

      • queryText — текст поискового запроса. Максимальная длина запроса — 400 символов.

      • familyMode — фильтрация результатов. Необязательный параметр. Возможные значения:

        • FAMILY_MODE_MODERATE — умеренный фильтр (значение по умолчанию). Из выдачи исключаются документы, относящиеся к категории «для взрослых», если запрос явно не направлен на поиск подобных ресурсов.
        • FAMILY_MODE_NONE — фильтрация отключена. В выдачу включаются любые документы вне зависимости от содержимого.
        • FAMILY_MODE_STRICT — семейный фильтр. Вне зависимости от поискового запроса из выдачи исключаются документы, относящиеся к категории «для взрослых», а также содержащие ненормативную лексику.

      • page — номер запрашиваемой страницы. Необязательный параметр. По умолчанию возвращается первая страница поисковой выдачи. Нумерация страниц начинается с нуля (первой странице соответствует значение 0).

      • fixTypoMode — значение настройки режима исправления опечаток в поисковом запросе. Необязательный параметр. Возможные значения:

        • FIX_TYPO_MODE_ON — исправление опечаток включено (значение по умолчанию). Опечатки в тексте поискового запроса автоматически исправляются.
        • FIX_TYPO_MODE_OFF — исправление опечаток отключено. Опечатки в тексте поискового запроса не исправляются, поиск выполняется в полном соответствии с переданным запросом.

      • format — поиск изображений указанного формата. Необязательный параметр. Если параметр не задан, выполняется поиск по изображениям всех форматов. Возможные значения:

        • IMAGE_FORMAT_JPEG — формат JPG.
        • IMAGE_FORMAT_GIF — формат GIF.
        • IMAGE_FORMAT_PNG — формат PNG.

      • size — поиск изображений указанного размера. Необязательный параметр. Если параметр не задан, выполняется поиск по изображениям всех размеров. Возможные значения:

        • IMAGE_SIZE_ENORMOUS — изображения очень большого размера (более 1600 × 1200 в пикселях).
        • IMAGE_SIZE_LARGE — изображения большого размера (от 800 × 600 до 1600 × 1200 в пикселях).
        • IMAGE_SIZE_MEDIUM — изображения среднего размера (от 150 × 150 до 800 × 600 в пикселях).
        • IMAGE_SIZE_SMALL — изображения маленького размера (от 32 × 32 до 150 × 150 в пикселях).
        • IMAGE_SIZE_TINY — иконки (не более 32 × 32 в пикселях).
        • IMAGE_SIZE_WALLPAPER — обои для рабочего стола.

      • orientation — поиск изображений с указанной ориентацией. Необязательный параметр. Если параметр не задан, выполняется поиск по изображениям с любой ориентацией. Возможные значения:

        • IMAGE_ORIENTATION_VERTICAL — изображения с вертикальной ориентацией.
        • IMAGE_ORIENTATION_HORIZONTAL — изображения с горизонтальной ориентацией.
        • IMAGE_ORIENTATION_SQUARE — изображения с равными сторонами (квадрат).

      • color — поиск изображений с заданными параметрами цвета. Необязательный параметр. Если параметр не задан, выполняется поиск по изображениям с любыми цветовыми параметрами. Возможные значения:

        • IMAGE_COLOR_COLOR — цветные изображения.
        • IMAGE_COLOR_GRAYSCALE — черно-белые изображения.
        • IMAGE_COLOR_RED — изображения, в которых основной цвет — красный.
        • IMAGE_COLOR_ORANGE — изображения, в которых основной цвет — оранжевый.
        • IMAGE_COLOR_YELLOW — изображения, в которых основной цвет — желтый.
        • IMAGE_COLOR_GREEN — изображения, в которых основной цвет — зеленый.
        • IMAGE_COLOR_CYAN — изображения, в которых основной цвет — голубой.
        • IMAGE_COLOR_BLUE — изображения, в которых основной цвет — синий.
        • IMAGE_COLOR_VIOLET — изображения, в которых основной цвет — фиолетовый.
        • IMAGE_COLOR_WHITE — изображения, в которых основной цвет — белый.
        • IMAGE_COLOR_BLACK — изображения, в которых основной цвет — черный.

      • site — поиск изображений только на указанном сайте. Например: yandex.cloud. Необязательный параметр. Если параметр не задан, поиск выполняется по всем сайтам поисковой базы.

      • docsOnPage — количество групп результатов, которое выводится на одной странице с результатами поиска. Возможные значения — от 1 до 60. Необязательный параметр. Значение по умолчанию — 20.

      • folderId — идентификатор каталога пользователя или сервисного аккаунта, от имени которого вы будете выполнять запросы.

      • userAgent — строка, содержащая заголовок User-Agent. Параметр позволяет получить поисковую выдачу, ориентированную на конкретное устройство и браузер, в том числе мобильную выдачу. Необязательный параметр. Если параметр не задан, сервис возвращает стандартную выдачу по умолчанию.

      Пример тела запроса

      body.json

      {
  "query": {
    "searchType": "SEARCH_TYPE_RU",
    "queryText": "котики"
  },
  "folderId": "b1gt6g8ht345********"
}

    2. Выполните HTTP-запрос, указав полученный ранее IAM-токен и путь к файлу с телом запроса:

      curl \
  --request POST \
  --header "Authorization: Bearer <IAM-токен>" \
  --data "@body.json" \
  "https://searchapi.api.yandexcloud.kz/v2/image/search" \
  > result.json

      В файл result.json будет сохранен результат выполнения поискового запроса, поле rawData содержит XML-ответ в кодировке Base64.

  2. Декодируйте результат из формата Base64:

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

    В результате в файл result.xml будет сохранен XML-ответ по запросу.

  1. Отправьте запрос и получите результат в кодировке Base64:

    1. Создайте файл с телом запроса (например, body.json):

      body.json

      {
  "query": {
    "search_type": "<тип_поиска>",
    "query_text": "<текст_поискового_запроса>",
    "family_mode": "<значение_настройки_фильтрации_результатов>",
    "page": "<номер_страницы>",
    "fix_typo_mode": "<значение_настройки_режима_исправления_опечаток>"
  },
  "image_spec": {
    "format": "<формат_изображения>",
    "size": "<размер_изображения>",
    "orientation": "<тип_ориентации_изображения>",
    "color": "<цвет_изображения>"
  },
  "site": "<доменное_имя_сайта>",
  "docs_on_page": "<количество_результатов_на_странице>",
  "folder_id": "<идентификатор_каталога>",
  "user_agent": "<заголовок_User-Agent>"
}
      Описание полей

      • search_type — тип поиска. Возможные значения:

        • SEARCH_TYPE_RU — для типа поиска Русский.
        • SEARCH_TYPE_TR — для типа поиска Турецкий.
        • SEARCH_TYPE_COM — для типа поиска Международный.
        • SEARCH_TYPE_KK — для типа поиска Казахский.
        • SEARCH_TYPE_BE – для типа поиска Белорусский.
        • SEARCH_TYPE_UZ — для типа поиска Узбекский.

      • query_text — текст поискового запроса. Максимальная длина запроса — 400 символов.

      • family_mode — фильтрация результатов. Необязательный параметр. Возможные значения:

        • FAMILY_MODE_MODERATE — умеренный фильтр (значение по умолчанию). Из выдачи исключаются документы, относящиеся к категории «для взрослых», если запрос явно не направлен на поиск подобных ресурсов.
        • FAMILY_MODE_NONE — фильтрация отключена. В выдачу включаются любые документы вне зависимости от содержимого.
        • FAMILY_MODE_STRICT — семейный фильтр. Вне зависимости от поискового запроса из выдачи исключаются документы, относящиеся к категории «для взрослых», а также содержащие ненормативную лексику.

      • page — номер запрашиваемой страницы. Необязательный параметр. По умолчанию возвращается первая страница поисковой выдачи. Нумерация страниц начинается с нуля, первой странице соответствует значение 0.

      • fix_typo_mode — значение настройки режима исправления опечаток в поисковом запросе. Необязательный параметр. Возможные значения:

        • FIX_TYPO_MODE_ON — исправление опечаток включено (значение по умолчанию). Опечатки в тексте поискового запроса автоматически исправляются.
        • FIX_TYPO_MODE_OFF — исправление опечаток отключено. Опечатки в тексте поискового запроса не исправляются, поиск выполняется в полном соответствии с переданным запросом.

      • format — поиск изображений указанного формата. Необязательный параметр. Если параметр не задан, выполняется поиск по изображениям всех форматов. Возможные значения:

        • IMAGE_FORMAT_JPEG — формат JPG.
        • IMAGE_FORMAT_GIF — формат GIF.
        • IMAGE_FORMAT_PNG — формат PNG.

      • size — поиск изображений указанного размера. Необязательный параметр. Если параметр не задан, выполняется поиск по изображениям всех размеров. Возможные значения:

        • IMAGE_SIZE_ENORMOUS — изображения очень большого размера (более 1600 × 1200 в пикселях).
        • IMAGE_SIZE_LARGE — изображения большого размера (от 800 × 600 до 1600 × 1200 в пикселях).
        • IMAGE_SIZE_MEDIUM — изображения среднего размера (от 150 × 150 до 800 × 600 в пикселях).
        • IMAGE_SIZE_SMALL — изображения маленького размера (от 32 × 32 до 150 × 150 в пикселях).
        • IMAGE_SIZE_TINY — иконки (не более 32 × 32 в пикселях).
        • IMAGE_SIZE_WALLPAPER — обои для рабочего стола.

      • orientation — поиск изображений с указанной ориентацией. Необязательный параметр. Если параметр не задан, выполняется поиск по изображениям с любой ориентацией. Возможные значения:

        • IMAGE_ORIENTATION_VERTICAL — изображения с вертикальной ориентацией.
        • IMAGE_ORIENTATION_HORIZONTAL — изображения с горизонтальной ориентацией.
        • IMAGE_ORIENTATION_SQUARE — изображения с равными сторонами (квадрат).

      • color — поиск изображений с заданными параметрами цвета. Необязательный параметр. Если параметр не задан, выполняется поиск по изображениям с любыми цветовыми параметрами. Возможные значения:

        • IMAGE_COLOR_COLOR — цветные изображения.
        • IMAGE_COLOR_GRAYSCALE — черно-белые изображения.
        • IMAGE_COLOR_RED — изображения, в которых основной цвет — красный.
        • IMAGE_COLOR_ORANGE — изображения, в которых основной цвет — оранжевый.
        • IMAGE_COLOR_YELLOW — изображения, в которых основной цвет — желтый.
        • IMAGE_COLOR_GREEN — изображения, в которых основной цвет — зеленый.
        • IMAGE_COLOR_CYAN — изображения, в которых основной цвет — голубой.
        • IMAGE_COLOR_BLUE — изображения, в которых основной цвет — синий.
        • IMAGE_COLOR_VIOLET — изображения, в которых основной цвет — фиолетовый.
        • IMAGE_COLOR_WHITE — изображения, в которых основной цвет — белый.
        • IMAGE_COLOR_BLACK — изображения, в которых основной цвет — черный.

      • site — поиск изображений только на указанном сайте. Например: yandex.cloud. Необязательный параметр. Если параметр не задан, поиск выполняется по всем сайтам поисковой базы.

      • docs_on_page — количество групп результатов, которое выводится на одной странице с результатами поиска. Возможные значения — от 1 до 60. Необязательный параметр. Значение по умолчанию — 20.

      • folder_id — идентификатор каталога пользователя или сервисного аккаунта, от имени которого вы будете выполнять запросы.

      • user_agent — строка, содержащая заголовок User-Agent. Параметр позволяет получить поисковую выдачу, ориентированную на конкретное устройство и браузер, в том числе мобильную выдачу. Необязательный параметр. Если параметр не задан, сервис возвращает стандартную выдачу по умолчанию.

      Пример тела запроса

      body.json

      {
  "query": {
    "search_type": "SEARCH_TYPE_RU",
    "query_text": "котики"
  },
  "folder_id": "b1gt6g8ht345********"
}

    2. Выполните gRPC-вызов, указав полученный ранее IAM-токен и путь к файлу с телом запроса:

      grpcurl \
  -rpc-header "Authorization: Bearer <IAM-токен>" \
  -d @ < body.json \
  searchapi.api.yandexcloud.kz:443 yandex.cloud.searchapi.v2.ImageSearchService/Search \
  > result.json

      В файл result.json будет сохранен результат выполнения поискового запроса, поле rawData содержит XML-ответ в кодировке Base64.

  2. Декодируйте результат из формата Base64:

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

    В результате в файл result.xml будет сохранен XML-ответ по запросу.

См. также

Предыдущая
Текстовый поиск в отложенном режиме
Следующая
Поиск изображений по изображению