API Яндекс.Фоток. Руководство разработчика: Загрузка изображения

Авторизация
Способы загрузки изображения
Загрузка изображений в формате multipart/form-data
Загрузка изображения простым POST-запросом
Альтернативный метод загрузки изображения
Возможные ошибки

Авторизация

Требуется. Данную операцию может выполнить только владелец коллекции фотографий.

Способы загрузки изображения

Для загрузки изображения на Яндекс.Фотки нужно методом POST передать серверу графический файл. Загружать можно изображения в следующих форматах: JPEG, PNG, GIF и BMP.

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

POST-запрос выполняется по адресу общей коллекции фотографий.: Изображение добавляется в альбом по умолчанию. Его можно добавить и в определенный альбом. Для этого нужно передать поле запроса album (см. список полей запроса). Доступные форматы запроса: простой POST и multipart/form-data.
POST-запрос выполняется по адресу коллекции фотографий альбома.: Изображение добавляется в соответствующий альбом. Доступные форматы запроса: простой POST и multipart/form-data.

Загрузка изображений в формате multipart/form-data

При загрузке изображения в полях запроса необходимо передать файл изображения (см. формат multipart/form-data). Также можно указать свойства изображения (см. список полей запроса).

В случае успеха сервер возвращает 201 Created и Atom Entry фотографии. Также можно запросить представление фотографии и в формате JSON (см. Форматы обмена данными).

Запрос выглядит следующим образом:

POST http://api-fotki.yandex.ru/api/users/alekna/photos/  HTTP/1.1
Host: api-fotki.yandex.ru
Content-Length:  442422
Content-Type: multipart/form-data;  boundary=frekgh738gGHUehfui33qqQ
Authorization: OAuth eb1c5...

--frekgh738gGHUehfui33qqQ
Content-Disposition: form-data;  name="image"; filename="moon"
Content-Type: image/jpeg

{содержимое файла "moon.jpg" в бинарном виде}
--frekgh738gGHUehfui33qqQ
Content-Disposition: form-data; name="title"

Луна
--frekgh738gGHUehfui33qqQ
Content-Disposition: form-data; name="description"

Полнолуние 19 марта
--frekgh738gGHUehfui33qqQ
Content-Disposition: form-data; name="tags"

космос
--frekgh738gGHUehfui33qqQ
Content-Disposition: form-data; name="tags"

небо
--frekgh738gGHUehfui33qqQ
Content-Disposition: form-data; name="album"

urn:yandex:fotki:alekna:album:168628

Ответ сервера:

HTTP/1.1 201 CREATED
Content-Type: application/atom+xml; type=entry
Location: http://api-fotki.yandex.ru/api/users/alekna/photo/453323/
Content-Location: http://fotki.yandex.ru/users/alekna/view/453323/

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:app="http://www.w3.org/2007/app" xmlns:f="yandex:fotki">
  <id>urn:yandex:fotki:alekna:photo:453323</id>
  <author>
    <name>alekna</name>
  </author>
  <title>Луна</title>
  <link href="http://api-fotki.yandex.ru/api/users/alekna/photo/453323/" rel="self" />
  <link href="http://api-fotki.yandex.ru/api/users/alekna/photo/453323/" rel="edit" />
  <link href="http://fotki.yandex.ru/users/alekna/view/453323/" rel="alternate" />
  <link href="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_orig" rel="edit-media" />
  <link href="http://api-fotki.yandex.ru/api/users/alekna/album/168628/" rel="album" />
  <published>2011-05-23T10:40:13Z</published>
  <app:edited>2011-05-23T10:40:13Z</app:edited>
  <updated>2011-05-23T10:40:13Z</updated>
  <f:access value="private" />
  <f:xxx value="false" />
  <f:hide_original value="false" />
  <f:disable_comments value="false" />
  <f:img height="75" href="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_XXS" size="XXS" width="75" />
  <f:img height="453" href="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_XL" size="XL" width="604" />
  <f:img height="225" href="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_M" size="M" width="300" />
  <f:img height="375" href="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_L" size="L" width="500" />
  <f:img height="50" href="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_XXXS" size="XXXS" width="50" />
  <f:img height="113" href="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_S" size="S" width="150" />
  <f:img height="75" href="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_XS" size="XS" width="100" />
  <f:img height="453" href="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_orig" size="orig" width="604" />
  <content src="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_orig" type="image/*" />
</entry>

Список полей запроса

Обязательные:

image
Файл картинки (с именем и mime-типом).

Опциональные:

title
Название фотографии. Не может быть пустой строкой.
summary (description)
Описание фотографии.
album
Идентификатор Atom Entry альбома. Альбом должен существовать.
При отправке запроса по адресу коллекции фотографий альбома значение поля album должно соответствовать номеру этого альбома на Яндекс.Фотках.
storage_private
Флаг, закрывающий доступ к фотографии по URL со страниц вне домена Яндекс.Фоток.

Значение по умолчанию: false.
hide_original (hide_orig)
Флаг запрета публичного доступа к оригиналу фотографии.
Значение по умолчанию: false.
xxx
Флаг «только для взрослых» (можно только установить, снять нельзя).

Значение по умолчанию: false.
disable_comments
Флаг запрета комментариев.

Значение по умолчанию: false.
access (access_type)
Уровень доступа к фотографии. Допустимые значения:
- public - для всех;
- friends - для друзей;
- private (по умолчанию) - для себя.
tags (tag)
Список тегов фотографии. Теги разделяются знаком "," или ";". Поле можно указывать несколько раз. В этом случае теги склеиваются в единый список.

Рекомендуемые:

pub_channel
Имя-идентификатор клиентского приложения.
app_platform
Информация о платформе клиентского приложения.
app_version
Версия клиентского приложения.

Загрузка изображения простым POST-запросом

В теле простого POST-запроса серверу передается только содержимое графического файла в бинарном виде.

В случае успеха сервер возвращает 201 Created и представление фотографии в формате Atom Entry или JSON.

POST /api/users/alekna/album/168628/photos/ HTTP/1.1
Host: api-fotki.yandex.ru
Content-Type: image/jpeg
Content-Length: 442422
Authorization: OAuth eb1c5...
 
{содержимое файла "sun.jpg" в бинарном виде}

Ответ сервера:

HTTP/1.1 201 CREATED
Content-Type: application/atom+xml; type=entry
Location: http://api-fotki.yandex.ru/api/users/alekna/photo/453323/
Content-Location: http://fotki.yandex.ru/users/alekna/view/453323/

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:app="http://www.w3.org/2007/app" xmlns:f="yandex:fotki">
  <id>urn:yandex:fotki:alekna:photo:453323</id>
  <author>
    <name>alekna</name>
  </author>
  <title>Фотка</title>
  <link href="http://api-fotki.yandex.ru/api/users/alekna/photo/453323/" rel="self" />
  <link href="http://api-fotki.yandex.ru/api/users/alekna/photo/453323/" rel="edit" />
  <link href="http://fotki.yandex.ru/users/alekna/view/453323/" rel="alternate" />
  <link href="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_orig" rel="edit-media" />
  <link href="http://api-fotki.yandex.ru/api/users/alekna/album/168628/" rel="album" />
  <published>2011-05-23T10:40:13Z</published>
  <app:edited>2011-05-23T10:40:13Z</app:edited>
  <updated>2011-05-23T10:40:13Z</updated>
  <f:access value="private" />
  <f:xxx value="false" />
  <f:hide_original value="false" />
  <f:disable_comments value="false" />
  <f:img height="75" href="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_XXS" size="XXS" width="75" />
  <f:img height="453" href="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_XL" size="XL" width="604" />
  <f:img height="225" href="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_M" size="M" width="300" />
  <f:img height="375" href="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_L" size="L" width="500" />
  <f:img height="50" href="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_XXXS" size="XXXS" width="50" />
  <f:img height="113" href="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_S" size="S" width="150" />
  <f:img height="75" href="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_XS" size="XS" width="100" />
  <f:img height="453" href="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_orig" size="orig" width="604" />
  <content src="http://img-fotki.yandex.ru/get/5408/alekna.1/0_6eacb_f7c350c7_orig" type="image/*" />
</entry>

По умолчанию атрибуты Atom Entry будут иметь значения:

title
Название фотографии. Значение по умолчанию "Фотка".
f:access
Уровень доступа к фотографии. Значение по умолчанию private.
f:xxx
Флаг «только для взрослых». Значение по умолчанию false.
f:hide_original
Флаг запрета публичного доступа к оригиналу фотографии. Значение по умолчанию false.
f:disable_comments
Флаг запрета комментариев. Значение по умолчанию false.

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

Альтернативный метод загрузки изображения

Метод не следует стандарту AtomPub: в случае успешной загрузки сервер возвращает другой статус и другой контент.

POST-запрос нужно выполнять по адресу http://api-fotki.yandex.ru/post/. Поддерживается только формат multipart/form-data (см. список полей запроса).

В данном методе загрузки если не передавать поле access_type, то по умолчанию атрибут f:access принимает значение public.

Если изображение загружается в определенный альбом, то в поле album указывается номер альбома на Яндекс.Фотках (а не идентификатор Atom Entry альбома).

Также доступно дополнительное поле:

yaru (опциональное)
Флаг публикации фотографии на странице пользователя на Я.ру. Допустимые значения:
- «1» - опубликовать (по умолчанию);
- «0» - не опубликовывать.

Запрос выглядит следующим образом:

POST http://api-fotki.yandex.ru/post/  HTTP/1.1
Host: api-fotki.yandex.ru
Content-Length:  442422
Content-Type: multipart/form-data;  boundary=frekgh738gGHUehfui33qqQ
Authorization: OAuth eb1c5...

--frekgh738gGHUehfui33qqQ
Content-Disposition: form-data;  name="image"; filename="moon"
Content-Type: image/jpeg

{содержимое файла "moon.jpg" в бинарном виде}
--frekgh738gGHUehfui33qqQ
Content-Disposition: form-data; name="title"

Луна
--frekgh738gGHUehfui33qqQ
Content-Disposition: form-data; name="album"

618465

В случае успеха сервер возвращает:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

image_id=526574&post_id=23

image_id - идентификатор фотографии;
post_id - идентификатор поста на Я.ру.
Если поле yaru принимает значение 0, то данный параметр не возвращается.

Возможные ошибки

401 Unauthorized, 403 Forbidden
Ошибки авторизации.
400 Bad Request
Загружаемый файл не является изображением или имеет недопустимый формат, либо не передано поле image. В теле ответа отдается:

Not an image or unsupported image type.
404 Not found
Такого пользователя или альбома не существует. В теле ответа отдается:

User {login} not found или Album {album_id} not found.

API Фоток:

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