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

2番目のチャンクのリクエストの例

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

最後のチャンクをアップロードしたら、start_offset値とend_offset値が同じ値になってAPI応答が返されます。これは、アップロードセッションを終了できることを示します。

最後の応答の例

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

ステップ3: アップロードセッションを終了する

アップロードセッションが終了したら、動画全体は再度組み立てられ、エンコードされ、ページで公開されます。アップロードセッションを終了するには、次の1つの最終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
}

この応答を受け取ったら、動画全体の組み立てとエンコードが開始されているということです。1分以内に公開された動画を見ることができるはずです。

再開不可アップロード

ファイルのアップロードには再開可能アップロードプロトコルを使用することをおすすめします。それは、このプロトコルが接続の中断をより効率的に処理し、より大きなサイズのファイルをサポートしているからです。しかし、再開不可アップロードプロトコルを使用したい場合は、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フィールドを含めれば独自のサムネイル画像を指定できます。再開可能プロトコルを使用している場合、thumbフィールドは、ステップ3: アップロードセッションを終了するで含めてください。自分で指定したサムネイル画像は変更されません。

サムネイル画像の要件

フォーマット: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"
}