Python Facebook Premium Downloader API 集成指南与 Zyla API Hub

您需要以编程方式获取公共 Facebook Reel/视频元数据，并在本周下载 MP4 以供内部工作流程使用。在本指南结束时，您将拥有一个可工作的 Python 集成，它启动异步下载作业，轮询以获取完成状态，并保存 MP4，以及一种快速获取仅元数据的方法——使用 Zyla API Hub 上的 Facebook Premium Downloader API。

此 API 的功能及使用时机

Facebook Premium Downloader API 为公共 Facebook Reels 和视频提供了两种功能：

• 启动一个异步下载作业，一旦完成，将从 Facebook 的 CDN 提供可下载的 MP4。
• 在不运行下载工作流程的情况下获取视频信息（元数据）。

典型的用例包括自动化编辑摄取、用户生成内容策划队列、合规归档，或任何需要公共 Reel/视频的 MP4 文件或元数据的后端。API 期望公共 Facebook URL，例如 /reel/…、/watch/?v=、/videos/… 或 fb.watch/…

在 Zyla API Hub 上开始

打开 Zyla API Hub 上的 Facebook Premium Downloader API 列表并订阅。Zyla 使用一个帐户、一个 API 密钥和订阅 + 配额模型——没有按调用计费。对于此 API，您可以开始 7 天的试用或使用 50 次请求来验证您的集成。没有免费计划。请查看 API 页面以获取当前访问选项和定价。

订阅后，您将收到一个 API 密钥。下面显示的所有请求都将密钥作为 Authorization: Bearer YOUR_API_KEY 传递。

身份验证和头部

• 头部：Authorization: Bearer YOUR_API_KEY
• 下面的所有示例都使用此列表的 Zyla Hub URL 路径。请勿直接调用源主机。

端点概述

1) 视频信息

在不启动下载作业的情况下检索公共 Facebook Reel/视频的元数据。

• 方法：GET
• URL：https://zylalabs.com/api/13612/facebook-premium-downloader-api/30379/video-information
• 所需参数：
  • url (字符串)：公共 Facebook 视频 URL（下面提供示例）

cURL（复制粘贴准备就绪）：

curl -s -X GET "https://zylalabs.com/api/13612/facebook-premium-downloader-api/30378/download?url=https%3A%2F%2Fwww.facebook.com%2Freel%2F1716864869572990%2F&format=mp4" \
-H "Authorization: Bearer YOUR_API_KEY"

示例 JSON 响应：

{
"success": true,
"id": "ddbea44c8fee0af86c40da80b9fcebb71b43f2ec",
"image": "https://scontent-phl2-1.xx.fbcdn.net/v/t51.82787-15/783144007_18064358021738741_5417564166543599844_n.jpg?_nc_cat=102&ccb=1-7&_nc_sid=a27664&_nc_ohc=K3uWHXdnAsgQ7kNvwGYgRLm&_nc_oc=AdrBUhuPSyDpnRP-zBbXB4TK1V0E2f2mz-aGg6GbrFjlKwZbfFAH6ynNbPHxceeh_rw&_nc_zt=23&_nc_ht=scontent-phl2-1.xx&_nc_gid=XrcbYmbN8ZuG357GCmVnIA&_nc_ss=7a289&oh=00_AQJv9a3kURRiH1Uri6TBWExvljPutu75Ucj18F-X6BhbPg&oe=6AA48A83",
"progress_url": "https://fb-download.zylalabs.com/api/progress?id=ddbea44c8fee0af86c40da80b9fcebb71b43f2ec",
"message": "作业已启动。每 3–5 秒轮询 progress_url，直到进度为 100，然后使用 download_url。"
}

您实际使用的内容：

• post_id：您可以存储以便将来对账的 Facebook ID。
• title、duration、likes：用于 UI 或索引的轻量级上下文。
• image：预览的缩略图 URL。
• url：规范源链接。

2) 下载

为公共 Facebook Reel/视频启动异步下载作业。响应提供作业 ID 和 progress_url。每 3–5 秒轮询该 URL，直到进度为 100，然后使用该响应中的 download_url（MP4 由 Facebook 的 CDN 提供；Hub 不代理二进制媒体）。

• 方法：GET
• URL：https://zylalabs.com/api/13612/facebook-premium-downloader-api/30378/download
• 所需参数：
  • url (字符串)：公共 Facebook 视频 URL（下面提供示例）
  • format (字符串)：mp4

cURL（复制粘贴准备就绪）：

示例 JSON 响应：

您实际使用的内容：

• id：您的作业参考，用于日志。
• progress_url：轮询此 URL，直到进度为 100；然后从该响应中读取 download_url 以获取 MP4。
• image：作业运行时的方便缩略图。

Python 实现：启动作业、轮询和保存 MP4

下面的代码片段执行以下操作：

1. 调用下载以启动提供的 Reel URL 的作业。
2. 每隔几秒轮询 progress_url。
3. 当进度达到 100 时，获取 download_url 并将 MP4 流式传输到磁盘。

import os
import time
import requests

API_KEY = os.getenv("ZYLA_API_KEY", "YOUR_API_KEY")
VIDEO_URL = "https://www.facebook.com/reel/1716864869572990/"

def start_download_job(video_url: str) -> dict:
hub_url = "https://zylalabs.com/api/13612/facebook-premium-downloader-api/30378/download"
params = {
"url": video_url,
"format": "mp4"
}
resp = requests.get(hub_url, headers={"Authorization": f"Bearer {API_KEY}"}, params=params, timeout=30)
resp.raise_for_status()
return resp.json()

def poll_progress(progress_url: str, interval_seconds: int = 4, max_wait_seconds: int = 180) -> dict:
deadline = time.time() + max_wait_seconds
last = None
while time.time() < deadline:
r = requests.get(progress_url, timeout=30)
r.raise_for_status()
data = r.json()
# 期望字段如 "progress" 和 "download_url" 完成时。
progress = data.get("progress")
if progress is not None:
print(f"progress={progress}")
last = data
if isinstance(progress, int) and progress >= 100:
return data
time.sleep(interval_seconds)
raise TimeoutError("下载作业未能及时达到 100%")

def save_mp4(download_url: str, out_path: str):
with requests.get(download_url, stream=True, timeout=120) as r:
r.raise_for_status()
with open(out_path, "wb") as f:
for chunk in r.iter_content(chunk_size=8192):
if chunk:
f.write(chunk)

if __name__ == "__main__":
job = start_download_job(VIDEO_URL)
if not job.get("success"):
raise RuntimeError(f"下载作业未能启动：{job}")
print(f"作业已启动：id={job.get('id')}")
print(f"缩略图：{job.get('image')}")
progress_url = job["progress_url"]

result = poll_progress(progress_url)
mp4_url = result.get("download_url")
if not mp4_url:
raise RuntimeError(f"在进度响应中未找到 download_url：{result}")

output_file = "facebook_reel.mp4"
print(f"正在下载：{mp4_url}")
save_mp4(mp4_url, output_file)
print(f"已保存到 {output_file}")

注意：

• 轮询间隔：根据端点指导，每 3–5 秒。示例使用 4 秒。
• 超时：根据您的队列延迟预算调整 max_wait_seconds。
• 二进制媒体：实际的 MP4 是通过 download_url 从 Facebook 的 CDN 提供的；Hub 不代理二进制媒体。

实际使用模式

• 元数据门：首先调用视频信息以验证 URL，提取 post_id，并在您的 UI 中显示缩略图。仅在用户确认摄取时启动下载。
• 队列工作者：在您的 Web 进程中启动下载作业，将 progress_url 入队，让工作者轮询并持久化 MP4。
• 幂等性：将作业 ID 与源 URL 和您的资产 ID 一起存储。如果请求被重试，您可以决定是重用还是启动一个新作业。
• 文件命名：将视频信息中的 post_id 与时间戳结合以获得确定性的文件名（例如，1716864869572990.mp4）。
• 缓存：如果您多次处理相同的 Reel，请使用以 post_id 为键的自己的存储跳过重新下载未更改的内容。

详细流程：端到端流

第 1 步 — （可选）获取视频元数据

使用视频信息快速验证公共 URL，并在下载之前向用户呈现详细信息：

第 2 步 — 启动异步下载作业

使用相同的 URL 和 format=mp4 调用下载：

持久化来自响应的 id 和 progress_url。消息字段提醒您每隔几秒轮询一次，直到准备就绪。

第 3 步 — 轮询 progress_url 并下载

每 3–5 秒，获取提供的 progress_url。当进度达到 100 时，读取 download_url 并将 MP4 流式传输到磁盘或对象存储。Hub 不代理二进制媒体；您的应用程序直接从 progress 端点返回的 CDN URL 下载。

计费、配额和环境设置

• 计费模型：订阅 + 配额。不是按调用计费。
• 试用：您的第一个 API 可以从 7 天的试用或 50 次请求开始。没有免费计划。
• 环境：将 YOUR_API_KEY 存储在您的秘密管理器中（或在开发中作为 ZYLA_API_KEY）。
• 重试：对于 progress_url 或最终 MP4 请求的瞬态网络问题，使用指数退避。

错误处理和边缘情况

• 私人或不可用的视频：API 针对公共 Reels/视频。如果 URL 不是公共的，请期待失败或不完整的数据。
• 轮询预算：确保您的工作者遵守队列 SLA；如果您的工作负载较大或源 CDN 较慢，请增加 max_wait_seconds。
• 存储生命周期：在保存 MP4 后，如果您期望很少重播，请将其移动到冷存储；保留 post_id 以避免重新获取。

真实世界用例

• 编辑审查管道：通过在下载之前显示标题、持续时间和缩略图来丰富提交。
• 合规归档：捕获 MP4 和元数据以进行审计跟踪，记录作业 ID 和 post_id 以便追溯。
• 数据集策划：使用视频信息根据持续时间或点赞情况进行筛选，然后再花费配额进行下载。

通过 MCP 从 AI 代理调用此 API

如果您使用 Claude Code、Cursor、Windsurf 或任何兼容 MCP 的客户端，您可以通过 Zyla 的 MCP 端点路由调用。将您的 Zyla API 密钥提供给 MCP 端点，让代理使用相同的 Authorization: Bearer 流来协调调用。

文档：MCP

生产检查清单

• 在每个请求中设置 Authorization: Bearer YOUR_API_KEY。
• 仅使用支持格式的公共 Facebook URL (/reel/…、/watch/?v=、/videos/…、fb.watch/…)。
• 每 3–5 秒轮询 progress_url；在访问 download_url 之前等待进度 == 100。
• 流式下载 MP4 以避免大内存缓冲。
• 记录作业 ID、源 URL 和最终文件路径以便可观察性。

常见问题

API 是否代理 MP4 文件？
不。Hub 启动作业并返回 progress_url。完成后，使用 progress 响应中的 download_url 直接从 Facebook 的 CDN 下载 MP4。

我可以使用私人或未列出的 Facebook 视频吗？
端点适用于公共 Reels/视频。如果 URL 不是公共的，元数据和下载可能会失败。

我应该发送什么身份验证头？
在每个请求中对 Zyla Hub URL 使用 Authorization: Bearer YOUR_API_KEY。

我应该如何轮询作业？
每 3–5 秒轮询 progress_url。当进度为 100 时，读取 download_url 并保存文件。

有免费计划吗？
没有免费计划。您的第一个 API 可以从 7 天的试用或 50 次请求开始。请查看项目页面以获取当前访问和定价。

准备好实施了吗？开始您的集成并在列表页面上进行端到端验证：开始 7 天的 Facebook Premium Downloader API 试用。