API Video

Публикация

С помощью API Video можно публиковать видео на Страницах и в Группах. Публикация для пользователей не поддерживается.

Вы также можете публиковать видео Reels на Страницах. Подробности см. в документации по API Reels Publishing.

При публикации видео необходимо выбрать протокол загрузки и отправить запрос POST к границе контекста /videos целевой Страницы или группы. API поддерживает протоколы возобновляемой и невозобновляемой загрузки. Рекомендуем использовать возобновляемую загрузку: этот протокол более универсальный и позволяет корректно обрабатывать обрывы соединения.

Обратите внимание: в примерах в этом документе используется узел Страницы, однако они в равной степени относятся и к узлам Групп.

Требования

Для всех действий по публикации необходимы соответствующие маркер доступа и разрешения для целевого узла. На этапе тестирования вы можете легко генерировать маркеры и предоставлять приложению разрешения с помощью Graph API Explorer. Соответствующие инструкции см. в нашем руководстве по началу работы. Когда приложение будет готово к переводу в рабочий режим, вам, вероятно, потребуется реализовать вход через Facebook, чтобы получать маркеры доступа и разрешения от пользователей.

Публикация на Страницах

Пользователь приложения должен быть администратором целевой Страницы. Вам потребуется маркер доступа к Странице пользователя приложения. Кроме того, он должен будет предоставить приложению разрешения pages_show_list, pages_read_engagement и pages_manage_posts.

Публикация в Группах

Пользователь приложения должен быть администратором целевой Группы. Вам потребуется маркер доступа пользователя приложения. Кроме того, пользователь должен будет предоставить приложению разрешение publish_to_groups.

Возобновляемая загрузка

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

Видео можно опубликовать на Странице или в Группе. Публикация состоит из следующих этапов:

  1. Инициализируйте сеанс загрузки на Странице или в Группе.
  2. Загрузите отдельные фрагменты в том порядке, в котором их затем нужно будет соединить.
  3. Завершите сеанс загрузки.

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

Ограничения

Максимальный размер видео — 10 ГБ, максимальная длительность — 4 часа.

Шаг 1. Инициализируйте сеанс загрузки

Чтобы инициализировать сеанс загрузки видео, отправьте запрос POST к конечной точке Page Videos:

POST /v19.0/{page-id}/videos
  ?upload_phase=start
  &access_token={access-token}
  &file_size={file-size}

Укажите следующие параметры:

Имя параметраЗначение

upload_phase

start

access_token

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

file_size

Общий размер видеофайла в байтах.

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

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos" \
  -F "upload_phase=start" \
  -F "access_token=EAADI..." \
  -F "file_size=22420886"

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

{
  "video_id":"2918040888250909",          //Capture this value (optional)
  "start_offset":"0",                     //Capture this value
  "end_offset":"1048576",
  "upload_session_id":"2918040901584241"  //Capture this value
}

Сохраните значения start_offset и upload_session_id, которые вернет API. Они потребуются на следующем этапе для загрузки первого фрагмента видео. Также стоит сохранить значение video_id. Оно не потребуется для публикации, однако затем будет использоваться в качестве ID опубликованного видео.

Шаг 2. Загрузите отдельные фрагменты

Загрузите отдельные фрагменты видео в том порядке, в котором их затем нужно будет соединить. Для этого последовательно отправьте соответствующие запросы POST к конечной точке Page Videos:

POST /v19.0/{page-id}/videos
  ?upload_phase=transfer
  &access_token={access-token}
  &upload_session_id={upload-session-id}
  &start_offset={start-offset}
  &video_file_chunk={video-file-chunk}

Добавьте в тело запроса следующие данные в виде multipart/form-data:

Название элемента данных формыЗначение

upload_phase

transfer

access_token

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

upload_session_id

ID сеанса загрузки.

start_offset

Значение start_offset, возвращенное в предыдущем ответе.

video_file_chunk

Имя загружаемого фрагмента видео.

Каждый раз после успешной загрузки фрагмента возвращается новое значение start_offset. Повторяйте этот запрос с использованием очередного полученного значения start_offset и имени следующего загружаемого фрагмента видео (оно присваивается параметру video_file_chunk), чтобы последовательно загрузить оставшиеся фрагменты видеофайла.

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

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos"  \
  -F "upload_phase=transfer" \
  -F "upload_session_id=2918040901584241" \
  -F "access_token=EAADI..." \
  -F "start_offset=0" \
  -F "video_file_chunk=@/Users/...xaa"

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

{
  "start_offset":"10485760",  //Value for second chunk
  "end_offset":"15728640"
}

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

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos"  \
  -F "upload_phase=transfer" \
  -F "upload_session_id=2918040901584241" \
  -F "access_token=EAADI..." \
  -F "start_offset=10485760" \
  -F "video_file_chunk=@/Users/...xab"

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

{
  "start_offset":"20971520",  //Value for third chunk
  "end_offset":"22420886"
}

После загрузки последнего фрагмента вы должны получить от API одинаковые значения start_offset и end_offset. Это будет означать, что сеанс загрузки можно завершать.

Пример последнего ответа

{
  "start_offset":"22420886",  //When values match you can
  "end_offset":"22420886"     //end the upload session
}

Шаг 3. Завершите сеанс загрузки

Когда сеанс загрузки будет завершен, мы соберем полное видео, закодируем его и опубликуем на Странице. Чтобы завершить сеанс загрузки, отправьте последний запрос POST к конечной точке Page Videos:

POST /v19.0/{page-id}/videos
  ?upload_phase=finish
  &access_token={access-token}
  &upload_session_id={upload-session-id}

Укажите следующие параметры:

Имя параметраЗначение

upload_phase

finish

access_token

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

upload_session_id

ID сеанса загрузки.

Также можно указать дополнительные параметры, поддерживаемые конечной точкой Page Videos, такие как title, description и thumb.

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

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos"  \
  -F "upload_phase=finish" \
  -F "access_token=EAADI..." \
  -F "upload_session_id=2918040901584241"

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

{
  "success":true
}

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

Невозобновляемая загрузка

Мы рекомендуем использовать протокол возобновляемой загрузки, так как он позволяет обрабатывать ситуации с обрывом подключения и поддерживает загрузку больших файлов. Однако если вы предпочитаете протокол невозобновляемой загрузки, то можете отправить запрос POST к границе контекста Page Videos и указать параметр source (для локального видеофайла) или file_url (для файла, расположенного на общедоступном сервер) в теле запроса в виде multipart/form-data. Также можно указать дополнительные параметры, поддерживаемые конечной точкой Page Videos, такие как title, description и thumb.

Ограничения

Максимальный размер видео — 1 ГБ, максимальная длительность — 20 минут. Если размер вашего видеофайла больше, разбейте его на фрагменты и опубликуйте с использованием протокола возобновляемой загрузки.

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

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos" \
  -F "access_token=EAADd..." \
  -F "source=@/Users/...incredible.mov"

Пример запроса для файла, расположенного на сервере

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos" \
  -F "access_token=EAADd..." \
  -F "file_url=https://socialsizz.../incredible.mov"

В случае успеха API вернет ID опубликованного видео.

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

{
  "id":"287788272232962"  //ID of the published Video
}

Миниатюры видео

Мы автоматически генерируем изображения миниатюр с использованием кадров из опубликованных видео. Эти миниатюры можно улучшить: скорректировать яркость, цвета и контрастность. Вы можете предоставить собственное изображение миниатюры, добавив поле thumb (оно поддерживается для протоколов возобновляемой и невозобновляемой загрузки). Если вы используете протокол возобновляемой загрузки, добавьте поле thumb на шаге 3, завершение сеанса загрузки. Предоставленные вами изображения миниатюр публикуются без изменений.

Требования к изображениям миниатюр

Формат: .bmp, .gif, .jpeg, .png, .tiff
Размер файла: не более 10 МБ.

Требований к размерам изображения нет, однако у него должно быть то же соотношение сторон, что и у видео.

Пример запроса с использованием протокола возобновляемой загрузки и миниатюры

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos" \
  -F "upload_phase=finish" \
  -F "access_token=EAADI..." \
  -F "upload_session_id=2918040901584241"
  -F "thumb=@/Users/...thumbnail_image.png"

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

{
  "success":true
}

Пример запроса с использованием протокола невозобновляемой загрузки и миниатюры

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos" \
  -F "access_token=EAADd..." \
  -F "source=@/Users/...incredible.mov"
  -F "thumb=@/Users/...thumbnail_image.png"

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

{
  "id":"287788272232962"
}