视频 API

发布

借助视频 API，您可以在公共主页和小组上发布视频。不支持向用户发布视频。

您还可以在公共主页上发布 Reels。详情请参阅 Reels 发布 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 值。发布时不需要使用该值，但该值将是最终发布的视频的编号。

第 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

上传会话的编号。

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

上传会话的编号。

您还可以添加公共主页视频端点支持的任何其他参数，如 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":"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"
}