ƒƒffhub.io

Inicio rápido

Ejecuta tu primera tarea de FFmpeg en FFHub en menos de 3 minutos.

Esta guía te lleva paso a paso por tu primera llamada a la API de FFmpeg: obtén una clave API, envía una tarea de transcodificación y lee el resultado.

1. Obtén una clave API

Regístrate en ffhub.io y crea una clave API en el panel. La clave tiene el formato sk_xxxxx — mantenla en privado.

Al registrarte también recibes créditos gratuitos, así que los pasos a continuación no tienen ningún costo.

Valida tu clave de API con GET /v1/me y el encabezado Authorization: Bearer YOUR_API_KEY. Una clave válida devuelve HTTP 200 con información de la cuenta; una clave inválida devuelve HTTP 401. Usa este endpoint para verificar la conexión en lugar del endpoint de consulta de tareas.

2. Envía una tarea

Envía cualquier comando de FFmpeg a POST /v1/tasks. Las entradas deben ser URLs públicas — las rutas locales son rechazadas por el worker en la nube.

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

La respuesta incluye un task_id que usarás para consultar el estado mediante polling:

{
  "task_id": "01abcd…"
}

3. Espera a que termine (polling)

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

Consulta cada 2–5 segundos mientras status sea pending o running. Deja de consultar cuando sea succeeded o failed. Descarga los archivos de outputs solo tras succeeded; si es failed, lee error e informa del fallo sin intentar descargar el resultado. Una respuesta HTTP correcta al consultar no significa que el procesamiento haya tenido éxito. Este es un extracto de una respuesta correcta:

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

La respuesta de consulta también incluye created_at y, al terminar la tarea, finished_at. Son marcas de tiempo ISO 8601 con zona horaria y pueden incluir fracciones de segundo. Por ejemplo, 2026-05-10T12:00:00Z y 2026-05-10T12:00:00.123Z son válidas. Antes de terminar, finished_at puede estar ausente; no interpretes un valor ausente como fecha de finalización.

Los archivos de salida se eliminan 7 días después de que termina la tarea — descarga lo que quieras guardar.

Subir archivos locales

Si tu entrada no es una URL pública, primero súbela para obtener una. Son dos pasos:

# 1. Solicita una URL firmada de un solo uso para hacer PUT
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. Sube el archivo directamente a R2 — tu servidor nunca toca los bytes
curl -fsS -X PUT "$(echo "$SIGNED" | jq -r '.upload_url')" \
  -H "Content-Type: video/mp4" \
  --data-binary "@./input.mp4" || { echo "Fallo al subir el archivo"; exit 1; }

# El campo .public_url es lo que pasas a `-i` en el comando de la tarea.

Guía completa en Subir archivos.

Próximos pasos