Изображения в ответе навыка

Ваш навык может отвечать пользователю картинками. Устраивайте экскурсии по музеям, показывая произведения великих мастеров. Рассказывайте о кулинарных рецептах, сопровождая текст изображениями блюд. Загружайте фотографии вашего города — и ваш навык станет гидом для пользователей.

Чтобы показать изображение в ответе навыка:

  1. Подготовьте изображение, чтобы оно корректно отображалось в навыке (например, чтобы не обрезались края).
  2. Загрузите изображение на Яндекс.Диалоги: в консоли разработчика или через HTTP API.
  3. Добавьте ссылку на загруженное изображение в ответ навыка. При необходимости, можно показать галерею из нескольких изображений. Подробнее см. в разделе Протокол работы.
Внимание. Ограничения на загрузку изображений:
  • Для одного аккаунта Яндекса можно загрузить не больше 100 МБ изображений.
  • Каждый файл должен быть размером не менее 1 КБ и не более 1 МБ.
  • Поддерживаются форматы: PNG, JPEG, GIF, BMP, TIFF, WEBP.

При превышении лимита запросов на удаление или на загрузку будет возвращен ответ со статусом 429.

Подготовка изображения

Чтобы картинка корректно отображалась в навыке (например, чтобы не обрезались ее края), картинку следует предварительно обработать. Рекомендации по обработке изображений приведены ниже.

Загрузка изображения через консоль разработчика

  1. Зайдите в консоль разработчика и откройте страницу навыка.
  2. Перейдите в раздел Ресурсы. В разделе показан список всех ресурсов, загруженных для навыка (картинки, звуки). Ресурсы, которые загружались через HTTP API, также будут отображаться в этом разделе.
  3. Откройте вкладку Изображения и переместите в окошко нужный файл с вашего компьютера. Когда изображение будет загружено на Диалоги, оно появится на этой странице.
  4. Чтобы показать изображение в навыке, сформируйте ответ согласно протоколу.

Загрузка изображения через HTTP API

Авторизация

Загружать картинки для навыка можно только от имени пользователя, создавшего навык. Для этого нужно получить OAuth-токен для Диалогов. Полученный токен необходимо указывать в каждом запросе к Диалогам, в заголовке Authorization:

Authorization: OAuth ARAAAAAB5vpbAAQ7o9abBlrUn0nshvcHZE4Irhw

Проверить занятое место

Для каждого аккаунта Яндекса на Диалоги можно загрузить не больше 100 МБ картинок. Чтобы узнать, сколько места уже занято, отправьте следующий запрос:

GET /api/v1/status

Host: https://dialogs.yandex.net
Authorization: OAuth <OAuth-токен>
curl
curl \
  -H 'Authorization: OAuth <OAuth-токен>' \
  'https://dialogs.yandex.net/api/v1/status'
Скопировано

Диалоги пришлют доступный объем для картинок и аудиофайлов, а также занятый объем. Значения указаны в байтах.

{
    "images": {
        "quota": {
            "total": 104857600,
            "used": 875963
        }
    },
    "sounds": {
        "quota": {
            "total": 1073741824,
            "used": 1593859
        }
    }
}
Примечание. Лимиты на загрузку картинок и аудиофайлов считаются отдельно.

Загрузить изображение из интернета

Чтобы загрузить картинку для навыка из интернета, передайте URL картинки в запросе:

POST /api/v1/skills/<идентификатор навыка>/images

Host: https://dialogs.yandex.net
Authorization: OAuth <OAuth-токен>
Content-Type: application/json

{ "url": "<адрес изображения>" }
curl
curl \
  -H 'Authorization: OAuth <OAuth-токен>' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{ "url": "<адрес изображения>" }' \
  'https://dialogs.yandex.net/api/v1/skills/<идентификатор навыка>/images'
Скопировано
Примечание. Идентификатор навыка можно посмотреть в консоли разработчика — зайдите на страницу навыка, откройте вкладку Общие сведения и пролистайте вниз.

Если изображение удалось загрузить на Диалоги, в ответ придет информация об этом изображении:

{
  "image": {
    "id": <идентификатор изображения>,
    "origUrl": <URL изображения>,
    "size": <размер изображения>,
    "createdAt": <дата загрузки>
  }
}

Как показать изображение в ответе навыка

Загрузить файл изображения

Чтобы загрузить файл, отправьте запрос:

POST /api/v1/skills/<идентификатор навыка>/images

Host: https://dialogs.yandex.net
Authorization: OAuth <OAuth-токен>
Content-Type: multipart/form-data

<содержимое файла>
curl
curl \
  -H 'Authorization: OAuth <OAuth-токен>' \
  -H 'Content-Type: multipart/form-data' \
  -X POST \
  -F file=@<путь к файлу> \
  'https://dialogs.yandex.net/api/v1/skills/<идентификатор навыка>/images'
Скопировано

Если Диалоги успешно получили картинку, в ответе придет информация об изображении:

{
  "image": {
    "id": <идентификатор изображения>,
    "origUrl": <URL изображения>,
    "size": <размер изображения>,
    "createdAt": <дата загрузки>
  }
}

Как показать изображение в ответе навыка

Получить список загруженных изображений

Список изображений, загруженных для навыка, можно получить следующим запросом:

GET /api/v1/skills/<идентификатор навыка>/images

Host: https://dialogs.yandex.net
Authorization: OAuth <OAuth-токен>
curl
curl \
  -H 'Authorization: OAuth <OAuth-токен>' \
  'https://dialogs.yandex.net/api/v1/skills/<идентификатор навыка>/images'
Скопировано

Диалоги возвращают список изображений, загруженных для навыка:

{
  "images": [
    {
      "id": <идентификатор изображения>,
      "origUrl": <URL изображения>,
      "size": <размер изображения>,
      "createdAt": <дата загрузки>
    },
    ...
  ],
  "total": <количество загруженных изображений>
} 

Удалить изображение

Чтобы удалить загруженное изображение, отправьте его идентификатор в запросе DELETE:

DELETE /api/v1/skills/<идентификатор навыка>/images/<идентификатор изображения>

Host: https://dialogs.yandex.net
Authorization: OAuth <OAuth-токен>
curl
curl \
  -H 'Authorization: OAuth <OAuth-токен>' \
  -X DELETE \
  'https://dialogs.yandex.net/api/v1/skills/<идентификатор навыка>/images/<идентификатор изображения>'
Скопировано

Если изображение указано верно и успешно удалено, Диалоги возвращают ответ:

{
  "result": "ok"
}