동영상 API

게시

동영상 API를 사용하면 페이지 및 그룹에 동영상을 게시할 수 있습니다. 사용자에 대한 게시는 지원되지 않습니다.

페이지에 릴스를 게시할 수도 있습니다. 자세한 내용은 릴스 게시 API를 참조하세요.

동영상을 게시하는 과정에는 업로드 프로토콜을 선택하고 POST 요청을 대상 페이지 또는 그룹의 /videos 에지로 보내는 작업이 포함됩니다. 이 API는 재개 가능 및 재개 불가능 업로드 프로토콜을 모두 지원합니다. 재개 가능 업로드 프로토콜은 더욱 다양한 용도를 지원하고 연결 중단을 적절히 처리할 수 있으므로 이를 사용하는 것이 좋습니다.

이 문서의 모든 예시는 페이지 노드를 사용하지만 그룹 노드에도 똑같이 적용됩니다.

요구 사항

모든 게시 작업은 타게팅하는 노드에 따라 적절한 액세스 토큰과 권한이 필요합니다. 테스트하는 동안 그래프 API 탐색기를 사용하여 손쉽게 토큰을 생성하고 앱에 권한을 부여할 수 있습니다. 자세한 방법은 시작하기 가이드를 참조하세요. 앱을 프로덕션에 배포할 준비가 되면 Facebook 로그인을 구현하여 앱 사용자로부터 토큰과 권한을 받아야 할 수 있습니다.

페이지에 게시하기

앱 사용자는 타게팅하는 페이지의 관리자여야 합니다. 앱 사용자의 페이지 액세스 토큰이 필요하며, 앱 사용자는 앱에 pages_show_list, pages_read_engagement 및 pages_manage_posts 권한을 부여해야 합니다.

그룹에 게시하기

앱 사용자는 타게팅하는 그룹의 관리자여야 합니다. 앱 사용자의 사용자 액세스 토큰이 필요하며, 앱 사용자는 앱에 publish_to_groups 권한을 부여해야 합니다.

재개 가능 업로드

재개 가능 업로드 프로토콜은 대용량 동영상을 작은 청크로 분할하여 시간 초과를 방지할 수 있으므로 선호되는 게시 프로토콜입니다. 이는 연결 오류가 발생할 가능성이 큰 대용량 동영상에 특히 유용합니다. 대용량 동영상을 업로드하는 중 연결 오류가 발생하면 일반적으로 동영상 전체를 다시 업로드해야 합니다. 하지만 재개 가능 업로드 프로토콜을 사용하는 경우 해당 청크만 다시 업로드하면 됩니다. 이미 업로드된 청크는 다시 업로드할 필요가 없습니다.

페이지 또는 그룹에 동영상을 게시할 수 있습니다. 게시하는 방법은 다음과 같습니다.

  1. 페이지 또는 그룹에서 업로드 세션을 초기화합니다.
  2. 결합되어야 하는 순서대로 각 청크를 업로드합니다.
  3. 업로드 세션을 종료합니다.

업로드 세션을 종료하면 동영상을 다시 결합하고 인코딩한 다음, 게시합니다.

제한 사항

동영상은 10GB와 4시간으로 제한됩니다.

1단계: 업로드 세션 초기화

동영상 업로드 세션을 초기화하려면 페이지 동영상 엔드포인트로 POST 요청을 보냅니다.

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
}

이 API에서 반환된 start_offset과 upload_session_id 값을 캡처합니다. 해당 값은 다음 단계에서 첫 동영상 청크를 업로드할 때 사용하게 됩니다. 또한 video_id 값을 캡처하는 것이 좋습니다. 이 값은 게시 작업에는 필요하지 않지만 최종적인 게시 동영상 ID가 됩니다.

2단계: 개별적으로 청크 업로드

연속적인 POST 요청을 페이지 동영상 엔드포인트로 보내서 결합되어야 하는 순서대로 각 동영상 청크를 업로드합니다.

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 요청을 페이지 동영상 엔드포인트로 보냅니다.

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

페이지 동영상 엔드포인트가 지원하는 모든 추가 매개변수를 포함할 수도 있습니다(예: 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 요청을 페이지 동영상 에지로 보내고, 요청 본문에 source 매개변수(로컬 동영상 파일) 또는 file_url 매개변수(공용 서버에 호스팅된 파일)를 multipart/form-data로 포함하면 됩니다. 페이지 동영상 엔드포인트가 지원하는 모든 추가 매개변수를 포함할 수도 있습니다(예: title, description, thumb).

제한 사항

동영상은 1GB와 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 필드를 포함하여 자체적인 썸네일 이미지를 제공할 수 있습니다. 재개 가능 프로토콜을 사용할 경우 3단계: 업로드 세션 종료에서 thumb 필드를 포함합니다. 직접 제공하는 썸네일 이미지는 변경되지 않습니다.

썸네일 이미지 요구 사항

형식: BMP, GIF, JPEG, PNG, TIFF
파일 크기: 10MB 이하

이미지 크기에 대한 요구 사항은 없지만 가로세로비가 동영상과 동일해야 합니다.

재개 가능 업로드 요청(썸네일 포함) 샘플

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"
}