ƒƒffhub.io

快速开始

3 分钟跑通第一个 FFHub 云端 FFmpeg 任务。

这篇教你完成第一次 API 调用：拿到密钥、提交转码任务、读取结果。

1. 拿到 API Key

去 ffhub.io 注册，进 控制台 API Keys 创建一个。Key 形如 sk_xxxxx，注意保密。

新用户注册自带免费额度，下面这套流程跑下来不用花钱。

使用 GET /v1/me 验证 API Key，并携带 Authorization: Bearer YOUR_API_KEY。有效密钥返回 HTTP 200 和账号信息，无效密钥返回 HTTP 401。验证连接时应使用此接口，而不是依赖任务查询接口。

2. 提交任务

任意 FFmpeg 命令打到 POST /v1/tasks 即可。输入文件必须是公网可访问的 URL，本地路径会被云端 worker 拒掉。

curl -X POST https://api.ffhub.io/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "ffmpeg -i https://storage.ffhub.io/Sample_Video_File_100MB.mp4 -c:v libx264 -preset fast output.mp4"
  }'

const res = await fetch("https://api.ffhub.io/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FFHUB_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    command:
      "ffmpeg -i https://storage.ffhub.io/Sample_Video_File_100MB.mp4 -c:v libx264 -preset fast output.mp4",
  }),
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.ffhub.io/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['FFHUB_API_KEY']}"},
    json={
        "command": "ffmpeg -i https://storage.ffhub.io/Sample_Video_File_100MB.mp4 -c:v libx264 -preset fast output.mp4",
    },
)
task_id = res.json()["task_id"]

返回里的 task_id 拿来轮询状态：

{
  "task_id": "01abcd…"
}

3. 轮询直到完成

curl https://api.ffhub.io/v1/tasks/TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

当 status 为 pending 或 running 时，每 2–5 秒查询一次；变成 succeeded 或 failed 后停止轮询。只有 succeeded 时才从 outputs 下载文件；遇到 failed 应读取 error 并报告失败，不再尝试下载。查询接口返回 HTTP 成功不代表处理任务成功。下面是成功响应的节选：

{
  "task_id": "01abcd…",
  "status": "succeeded",
  "progress": 100,
  "outputs": [
    {
      "filename": "output.mp4",
      "url": "https://storage.ffhub.io/outputs/01abcd…/output.mp4",
      "size": 10485760
    }
  ]
}

任务查询响应还包含 created_at，任务结束后包含 finished_at。这些字段是带时区的 ISO 8601 时间戳，可能包含小数秒，例如 2026-05-10T12:00:00Z 和 2026-05-10T12:00:00.123Z 都有效。任务未结束时，finished_at 可能不存在；不要解析缺失值，也不要把它当成完成时间。

输出文件在任务完成 7 天后删除；需要长期保存请及时下载。

上传本地文件

如果输入文件不是公网 URL，先上传拿到一个。两步走：

# 1. 申请一次性的签名 PUT URL
SIGNED=$(curl -s -X POST https://api.ffhub.io/v1/uploads/sign \
  -H "Authorization: Bearer $FFHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"input.mp4","size":12345678,"content_type":"video/mp4"}')

# 2. 把文件直接 PUT 到 R2 —— 你的服务器不经手任何字节
curl -fsS -X PUT "$(echo "$SIGNED" | jq -r '.upload_url')" \
  -H "Content-Type: video/mp4" \
  --data-binary "@./input.mp4" || { echo "上传失败"; exit 1; }

# 返回的 .public_url 字段就是你在任务命令里传给 `-i` 的地址。

完整流程见 上传文件。

后续