Content Publishing API

Вы можете использовать Content Publishing API, чтобы размещать публикации с одним изображением, с одним видео или с одним видео Reels (т. е. публикации с одним медиафайлом) либо публикации, содержащие несколько изображений или видео (кольцевые галереи), в профессиональных аккаунтах Instagram.

C 1 июля 2023 г. все публикации с одним видео, размещенные через Content Publishing API для Instagram, будут публиковаться как видео Reels.

Требования

Маркеры доступа

В каждом запросе должен быть указан маркер доступа пользователя приложения.

Разрешения

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

Если приложением будут пользоваться люди, не имеющие роли в нем или в компании, которой оно принадлежит, то все разрешения, используемые в этом приложении, должны быть одобрены в ходе проверки.

Общедоступный сервер

Мы создаем cURL медиаобъекта, используемого при попытках публикации, поэтому в момент публикации медиафайлы должны быть размещены на общедоступном сервере.

Авторизация для публикации на Странице

Если профессиональный аккаунт Instagram подключен к Странице, которая требует авторизации для публикаций на Странице, необходимо сначала пройти ее.

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

Ограничения

Изображения могут иметь только формат .jpeg. Расширенные форматы .jpeg, такие как .mpo и .jps, не поддерживаются.
Метки товаров не поддерживаются.
Метки брендированного контента не поддерживаются.
Фильтры не поддерживаются.
Публикация в Instagram TV не поддерживается.

Дополнительные ограничения см. в справке по каждой конечной точке.

Ограничение числа обращений

Для аккаунтов Instagram действует ограничение количества публикаций через API: не более 50 публикаций в течение 24 часов. Кольцевые галереи считаются одной публикацией. Это ограничение применяется при публикации контейнеров медиаобъектов через конечную точку POST /{ig-user-id}/media_publish. Желательно, чтобы ваше приложение также ограничивало количество публикаций, особенно если оно позволяет пользователям планировать их размещение в будущем.

Чтобы проверить состояние ограничения в профессиональном аккаунте Instagram, выполните запрос к конечной точке GET /{ig-user-id}/content_publishing_limit.

Конечные точки

Этот API включает в себя перечисленные ниже конечные точки. Информацию о требованиях для использования каждой из них см. в соответствующей документации.

POST /{ig-user-id}/media — загрузка медиаобъектов и создание их контейнеров.
POST /{ig-user-id}/media_publish — публикация загруженных медиаобъектов с помощью их контейнеров.
GET /{ig-container-id}?fields=status_code — проверка возможности и состояния публикации контейнера медиаобъекта.
GET /{ig-user-id}/content_publishing_limit — проверка текущего состояния ограничения числа обращений к публикации для пользователя приложения.

Публикации с одним медиаобъектом

Публикация с одним изображением, видео, историей или Reels происходит в два этапа:

Использование конечной точки POST /{ig-user-id}/media для создания контейнера из изображения или видео, размещенного на вашем общедоступном сервере.
Использование конечной точки POST /{ig-user-id}/media_publish для публикации контейнера.

Этап 1 из 2. Создание контейнера

Предположим, у вас есть изображение

https://www.example.com/images/bronz-fonz.jpg

...которое вы хотите опубликовать с хэштегом #BronzFonz в качестве подписи. Отправьте запрос к конечной точке POST /{ig-user-id}/media.

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

POST https://graph.facebook.com/v21.0/17841400008460056/media
  ?image_url=https://www.example.com/images/bronz-fonz.jpg
  &caption=#BronzFonz

Он возвращает ID для изображения.

Пример ответа

{
  "id": "17889455560051444"  // IG Container ID
}

Этап 2 из 2. Публикация контейнера

Используйте конечную точку POST /{ig-user-id}/media_publish для публикации ID контейнера, возвращенного в предыдущем шаге.

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

POST https://graph.facebook.com/v21.0/17841400008460056/media_publish ?creation_id=17889455560051444

Пример ответа

{
  "id": "17920238422030506" // IG Media ID
}

Публикации с кольцевыми галереями

Вы можете публиковать до 10 изображений или видео либо сочетания этих двух типов файлов в одной публикации (публикации с кольцевыми галереями). Публикация кольцевых галерей происходит в три этапа:

Использование конечной точки POST /{ig-user-id}/media для создания отдельных контейнеров объектов для каждого изображения или видео, которые появятся в кольцевой галерее.
Повторное использование конечной точки POST /{ig-user-id}/media для создания отдельного контейнера кольцевой галереи для объектов.
Использование конечной точки POST /{ig-user-id}/media_publish для публикации контейнера кольцевой галереи.

При учете ограничения числа обращений публикации кольцевых галерей считаются одной публикацией.

Ограничения

Кольцевые галереи нельзя продвигать.
В кольцевых галереях может быть до 10 изображений и видео.
Все изображения в кольцевых галереях обрезаются в соответствии с первым изображением в ней, а по умолчанию используется соотношение сторон 1:1.

Этап 1 из 3. Создание контейнера объекта

Используйте конечную точку POST /{ig-user-id}/media, чтобы создать контейнер объекта для изображения или видео, которое появится в кольцевой галерее. В кольцевых галереях может быть до 10 изображений и видео.

POST /{ig-user-id}/media

Параметры

Следующие параметры являются обязательными. Информацию о дополнительных поддерживаемых параметрах см. в справке по конечной точке POST /{ig-user-id}/media.

is_carousel_item — задать значение true. Задает изображение или видео, которое появится в кольцевой галерее.
image_url — (только изображения) путь к изображению. Мы создаем cURL изображения на основе переданного URL, поэтому он должен указывать на общедоступный сервер.
media_type — (только видео) задать значение VIDEO. Указывает, что медиаобъект — это видео.
video_url — (только видео) путь к видео. Мы создаем cURL видео на основе переданного URL, поэтому он должен указывать на общедоступный сервер.

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

Повторите этот процесс для каждого изображения или видео, которое должно появиться в кольцевой галерее.

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

curl -i -X POST \

"https://graph.facebook.com/v21.0/90010177253934/media?image_url=https%3A%2F%2Fsol...&is_carousel_item=true&access_token=EAAOc..."

Пример ответа

{
  "id": "17899506308402767"
}

Этап 2 из 3. Создание контейнера кольцевой галереи

Используйте конечную точку POST /{ig-user-id}/media, чтобы создать контейнер кольцевой галереи.

POST /{ig-user-id}/media

Параметры

media_type — задать значение CAROUSEL. Указывает контейнер для кольцевой галереи.
children — массив не более чем из 10 ID контейнеров каждого изображения и видео, которые должны появиться в публикуемой кольцевой галерее. В кольцевых галереях может быть до 10 изображений и видео.

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

curl -i -X POST \

"https://graph.facebook.com/v21.0/90010177253934/media?caption=Fruit%20candies&media_type=CAROUSEL&children=17899506308402767%2C18193870522147812%2C17853844403701904&access_token=EAAOc..."

Пример ответа

{
  "id": "18000748627392977"
}

Этап 3 из 3. Публикация контейнера кольцевой галереи

Используйте конечную точку POST /{ig-user-id}/media_publish, чтобы опубликовать контейнер кольцевой галереи (публикация кольцевой галереи). В аккаунтах можно разместить не более 50 публикаций за каждые 24 часа. Публикация кольцевой галереи считается одной публикацией.

POST /{ig-user-id}/media_publish

Параметры

Следующие параметры являются обязательными.

creation_id — ID контейнера кольцевой галереи.

Если операция выполнена успешно, API предоставит ID IG Media альбома кольцевой галереи.

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

curl -i -X POST \

"https://graph.facebook.com/v21.0/90010177253934/media_publish?creation_id=18000748627392977&access_token=EAAOc..."

Пример ответа

{
  "id": "90010778390276"
}

Публикации видео Reels

Reels — это короткие видео, которые могут появляться на вкладке Reels в приложении Instagram, если они соответствуют определенным спецификациям и выбраны нашим алгоритмом. Чтобы опубликовать видео Reels, выполните те же действия, что и для размещения публикации с одним медиаобъектом, и добавьте параметр media_type=REELS вместе с указанием пути к видео, используя параметр video_url.

Reels — это не новый тип медиафайлов, хотя при публикации видео Reels вы и указываете параметр media_type=REELS. Если вы опубликуете видео Reels, а затем запросите его поле media_type, будет возвращено значение VIDEO. Чтобы определить, был ли опубликованный видеоролик обозначен как видео Reels, запросите его поле media_product_type.

Чтобы узнать, как публиковать видео Reels в Instagram, воспользуйтесь примером кода на GitHub (insta_reels_publishing_api_sample).

Для удобства разработчиков мы опубликовали полный список вызовов Graph API для видео Reels в Instagram на платформе Postman API. Подробнее см. в статье Подборки Postman для видео Reels на Facebook и в Instagram.

Подробнее о Reels см. в документации по видео Reels для разработчиков.

Публикации историй

В настоящий момент публиковать истории с помощью Content Publising API могут только бизнес-аккаунты.

Истории — это видео или изображения, которые публикуются как истории в Instagram. Чтобы опубликовать историю, выполните те же действия, что и для размещения публикации с одним медиаобъектом, добавьте параметр media_type=STORIES и укажите путь к изображению или видео в параметре image_url или video_url.

Примечание. Истории — это не новый тип медиафайлов, хотя при публикации истории вы и указываете параметр media_type=STORIES. Если вы опубликуете историю, а затем запросите ее поле media_type, будет возвращено значение IMAGE/VIDEO. Чтобы определить, было ли опубликованное видео или изображение обозначено как история, запросите его поле media_product_type.

Протокол возобновляемой загрузки

Протокол возобновляемой загрузки — это совершенно новый поток для публикации контента в Instagram, который поддерживает загрузку таких media_types, как видео для Reels, видеоистории и элементы кольцевых галерей с видео.

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

Конечные точки

POST https://graph.facebook.com/{api-version}/{ig-user-id}/media — инициализация контейнеров создания видео путем задания параметра upload_type=resumable.
POST https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id} — более надежная загрузка локального видео или файла по URL благодаря использованию протокола возобновляемой загрузки.
POST https://graph.facebook.com/{api-version}/{ig-user-id}/media_publish — публикация загруженных медиафайлов с использованием их контейнеров.
GET /{ig-container-id}?fields=status_code — проверка доступности и статуса публикации медиаконтейнеров.

Шаг 1. Инициализация сеанса загрузки для Reels, видеоисторий и элементов кольцевой галереи

Пример запроса для видео Reels

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=REELS" \
    -d "upload_type=resumable" \
    -d "caption={caption}"\
    -d "collaborators={collaborators-username}"
    -d "cover_url={cover-url}" \
    -d "audio_name={audio-name}" \
    -d "user_tags={user-tags}" \
    -d "location_id={location-id}" \
    -d "thumb_offset={thumb-offset}" \
    -H "Authorization: OAuth {access-token}"

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

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=STORIES" \
    -d "upload_type=resumable" \
    -H "Authorization: OAuth {access-token}"

Пример запроса для элемента кольцевой галереи

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=VIDEO" \
    -d "is_carousel_item=true" \
    -d "upload_type=resumable" \
    -H "Authorization: OAuth {access-token}"

Пример ответа

{
   "id": "{ig-container-id}",
   "uri": "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}"
}

Шаг 2. Загрузка видео с использованием протокола возобновляемой загрузки

В большинстве вызовов Graph API используется хост graph.facebook.com, однако в вызовах для загрузки видео для Reels используется хост rupload.facebook.com.

Поддерживаются следующие источники загружаемых видеофайлов:

файлы, расположенные на вашем компьютере;
файлы, размещенные не общедоступном сервере, например в сети CDN.

Пример запроса для загрузки локального видеофайла

Загрузите видео, используя ig-container-id, возвращенный в запросе сеанса возобновляемой загрузки.

Убедитесь, что используется хост rupload.facebook.com.
Для всех media_type используется один и тот же поток загрузки видео.
ig-container-id — это ID, возвращаемый запросами сеанса возобновляемой загрузки.
access-token — тот же, что использовался на предыдущих этапах.
В параметре offset задается первый загружаемый байт, обычно это 0.
В параметре file_size задается размер файла в байтах.
В параметре Your_file_local_path указывается путь к локальному файлу, например при загрузке файла из папки Загрузки в macOS это будет следующий путь: @Downloads/example.mov.

curl -X POST "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}" \
     -H "Authorization: OAuth {access-token}" \
     -H "offset: 0" \
     -H "file_size: Your_file_size_in_bytes" \
     --data-binary "@my_video_file.mp4"

Пример запроса для загрузки видеофайла с общедоступного сервера

curl -X POST "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}" \
     -H "Authorization: OAuth {access-token}" \
     -H "file_url: https://example_hosted_video.com"

Пример ответа

// Success Response Message
{
  "success":true,
  "message":"Upload successful."
}

// Failure Response Message
{
  "debug_info":{
    "retriable":false,
    "type":"ProcessingFailedError",
    "message":"{\"success\":false,\"error\":{\"message\":\"unauthorized user request\"}}"
  }
}

Шаг 3. (Только для кольцевых галерей) Создание контейнеров кольцевых галерей

Чтобы создать несколько ig-container-ids, повторите шаги 1 и 2, задав для параметра is_carousel_item значение true. Затем создайте контейнер кольцевой галереи, который будет содержать все элементы галереи. В кольцевой галерее можно использовать одновременно изображения и видео.

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=CAROUSEL" \
    -d "caption={caption}"\
    -d "collaborators={collaborator-usernames}" \
    -d "location_id={location-id}" \
    -d "product_tags={product-tags}" \
    -d "children=[{ig-container-id},{ig-container-id}...]" \
    -H "Authorization: OAuth {access-token}"

Шаг 4. Публикация медиафайла

Для публикации видео Reels и видеоисторий используется {ig-container-id}, созданный на шаге 1. Для публикации контейнера кольцевой галереи используется {ig-container-id}, созданный на шаге 3.

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media_publish" \
    -d "creation_id={ig-container-id}" \
    -H "Authorization: OAuth {access-token}"

Шаг 5. Получение статуса медиафайла

graph.facebook.com предоставляет конечную точку GET для получения статуса загрузки. В поле video_status указываются сведения о процессе локальной загрузки.

Параметр uploading_phase позволяет определить, был ли файл загружен и сколько байт передано.
Параметр processing_phase содержит сведения о статусе обработки видео после загрузки видеофайла.

// GET status from graph.facebook.com
curl -X GET "https://graph.facebook.com/v19.0/{ig-container-id}?fields=id,status,status_code,video_status" \
    -H "Authorization: OAuth {access-token}"

Пример ответа от конечной точки `graph.facebook.com`

// A successfully created ig container
{
  "id": "{ig-container-id}",
  "status": "Published: Media has been successfully published.",
  "status_code": "PUBLISHED",
  "video_status": {
    "uploading_phase": {
      "status": "complete",
      "bytes_transferred": 37006904
    },
    "processing_phase": {
      "status": "complete"
    }
  }
}

// An interrupted ig container creation, from here you can resume your upload in step 2 with offset=50002. 
{
  "id": "{ig-container-id}",
  "status": "Published: Media has been successfully published.",
  "status_code": "PUBLISHED",
  "video_status": {
    "uploading_phase": {
      "status": "in_progress",
      "bytes_transferred": 50002
    },
    "processing_phase": {
      "status": "not_started"
    }
  }
}

Метки соавтора

Вы можете добавить пользователей Instagram с открытым профилем в качестве соавторов изображения, кольцевой галереи или видео Reels. Эти пользователи получат приглашения стать соавтором для этого конкретного медиаобъекта. Чтобы отметить пользователей на изображении, выполните действия, перечисленные выше в пункте "Публикации с одним медиаобъектом", но при создании контейнера медиаобъекта укажите в параметре collaborators массив строк с именами пользователей Instagram, которых вы хотите пригласить в качестве соавторов для этого медиаобъекта.

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

POST graph.facebook.com/17841400008460056/media
?image_url=https://www.example.com/images/bronzed-fonzes.jpg
&caption=#BronzedFonzes!
&collaborators= [‘username1’,’username2’]

Примечания

Значением параметра collaborators должен быть массив строк.
Отмечать можно только пользователей с общедоступными аккаунтами Instagram.
На один медиаобъект можно добавить не более 3 соавторов.
Соавторов нельзя добавлять в медиаобъекты историй.

Метки геоданных

Вы можете использовать Pages Search API . Обязательно добавьте в свой запрос поле 'location' для поиска Страниц, названия которых соответствуют строке поиска. Затем обработайте результаты и определите все Страницы, созданные для физического местоположения. Если при публикации изображения или видео указать ID такой Страницы, к этому медиаобъекту будет добавлена соответствующая геометка.

Ограничения

Чтобы Страницу можно было отметить, ее данные о местоположении должны содержать широту и долготу.

Убедитесь, что в ответе для Страницы, которую вы хотите использовать, указаны широта и долгота. Если при создании контейнера вы попытаетесь указать Страницу без геоданных, возникнет исключение INSTAGRAM_PLATFORM_API__INVALID_LOCATION_ID.

Как только вы получите ID Страницы, назначьте его параметру location_id при публикации контейнеров объектов с одним медиафайлом или кольцевой галереи.

Метки товаров

Ставить метки товаров Instagram Shopping можно как в публикациях с одним медиафайлом, так и в кольцевых галереях. Подробнее см. в руководстве по работе с метками товаров.

Метки пользователей

Вы можете отметить на изображении пользователей с общедоступными аккаунтами Instagram, после чего они получат уведомление о том, что их отметили.

Чтобы отметить пользователей на изображении, выполните шаги, приведенные выше в пункте Публикации с одним медиаобъектом, но при создании контейнера медиаобъекта укажите параметр user_tags и массив объектов с отмеченными пользователями Instagram и их координатами X/Y на изображении.

Примечание. Метки пользователей в видео в кольцевых галереях не поддерживаются.

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

POST graph.facebook.com/17841400008460056/media ?image_url=https://www.example.com/images/bronzed-fonzes.jpg &caption=#BronzedFonzes! &user_tags= [ { username:'kevinhart4real', x: 0.5, y: 0.8 }, { username:'therock', x: 0.3, y: 0.2 } ]

Будет получен ID контейнера, который затем можно опубликовать с использованием конечной точки Публикация медиаобъектов для IG User.

Примечания

Значением user_tags должен быть массив объектов в формате JSON.
Отмечать можно только пользователей с общедоступными аккаунтами Instagram.
Объект должен содержать все три свойства (username, x и y) для каждого пользователя.
Значения x и y должны быть числами с плавающей запятой (float) в диапазоне от 0.0 до 1.0 и отсчитываться от левого верхнего угла изображения.

Устранение неполадок

Если вы создали контейнер для видео, но конечная точка POST /{ig-user-id}/media_publish не возвращает ID опубликованного медиафайла, выполните запрос к конечной точке GET /{ig-container-id}?fields=status_code, чтобы узнать статус публикации. Вы можете получить следующие значения:

EXPIRED — контейнер не был опубликован в течение 24 часов и больше не действителен;
ERROR — контейнер не удалось опубликовать из-за ошибки;
FINISHED — контейнер с медиаобъектом готов к публикации;
IN_PROGRESS — процесс публикации контейнера ещё идет;
PUBLISHED — медиаобъект опубликован.

Мы рекомендуем запрашивать статус публикации раз в минуту в течение максимум пяти минут.

Ошибки

См. справку по кодам ошибок.

Content Publishing API

Требования

Маркеры доступа

Разрешения

Общедоступный сервер

Авторизация для публикации на Странице

Ограничения

Ограничение числа обращений

Конечные точки

Публикации с одним медиаобъектом

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

Пример ответа

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

Пример ответа

Публикации с кольцевыми галереями

Параметры

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

Пример ответа

Параметры

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

Пример ответа

Параметры

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

Пример ответа

Публикации видео Reels

Публикации историй

Протокол возобновляемой загрузки

Конечные точки

Рекомендации по HTML-кодированию URL

Шаг 1. Инициализация сеанса загрузки для Reels, видеоисторий и элементов кольцевой галереи

Пример запроса для видео Reels

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

Пример запроса для элемента кольцевой галереи

Пример ответа

Шаг 2. Загрузка видео с использованием протокола возобновляемой загрузки

Пример запроса для загрузки локального видеофайла

Пример запроса для загрузки видеофайла с общедоступного сервера

Пример ответа

Шаг 3. (Только для кольцевых галерей) Создание контейнеров кольцевых галерей

Шаг 4. Публикация медиафайла

Шаг 5. Получение статуса медиафайла

Пример ответа от конечной точки graph.facebook.com

Метки соавтора

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

Примечания

Метки геоданных

Ограничения

Метки товаров

Метки пользователей

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

Примечания

Устранение неполадок

Ошибки

Пример ответа от конечной точки `graph.facebook.com`