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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  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

    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-ответ по запросу.

См. также

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