Documentation

ffpipe API Reference

Everything you need to start processing video via REST API.

Quickstart

ffpipe processes video via simple HTTP POST requests. You pass a URL to a video file, pick a preset or write a custom FFmpeg command, and get back a URL to the processed output.

You can be running your first job in under 5 minutes:

  1. Create a free account at app.ffpipe.net
  2. Copy your API key from the dashboard
  3. Make your first request (see below)
curl
curl -X POST https://api.ffpipe.net/v1/presets/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "transcode_h264",
    "input_url": "https://your-storage.com/input.mov"
  }'
Response
{
  "job_id": "job_01HXB8K...",
  "status": "processing",
  "output_url": null,
  "eta_seconds": 12
}

Poll /v1/jobs/{job_id} or set a webhook to get the result when processing is complete.

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API keys are available in your dashboard. Keep your key secret — it grants full access to your account.

Base URL

https://api.ffpipe.net

All endpoints are versioned under /v1.

POST /v1/presets/run

Run a named preset on a video file. The simplest way to get started.

Request body

ParameterTypeRequiredDescription
presetstringYesPreset name (see presets list)
input_urlstringYesPublicly accessible URL to the input file
webhook_urlstringNoURL to POST the result to when done
output_filenamestringNoCustom filename for the output
Example
POST /v1/presets/run
{
  "preset": "compress_web",
  "input_url": "https://storage.example.com/raw_video.mp4",
  "webhook_url": "https://n8n.yoursite.com/webhook/abc123"
}

POST /v1/run

Execute a raw FFmpeg command. Full control for advanced use cases.

ParameterTypeRequiredDescription
input_urlstringYesPublicly accessible URL to the input file
commandstringYesFFmpeg arguments (after -i input, before output)
output_formatstringYesOutput file extension, e.g. mp4, gif
webhook_urlstringNoURL to POST the result to when done
Example — extract audio
POST /v1/run
{
  "input_url": "https://storage.example.com/video.mp4",
  "command": "-vn -acodec mp3 -ab 192k",
  "output_format": "mp3"
}

GET /v1/jobs/{id}

Check the status of a processing job.

Response — completed
{
  "job_id": "job_01HXB8K...",
  "status": "completed",
  "output_url": "https://cdn.ffpipe.net/out/job_01HXB8K.../output.mp4",
  "duration_seconds": 8.4,
  "file_size_bytes": 12480000,
  "expires_at": "2025-01-22T14:30:00Z"
}

Possible status values: queued, processing, completed, failed

Available presets

Use these preset names in the preset field of /v1/presets/run.

transcode_h264
Convert any video to MP4 (H.264/AAC). Universal format for web, mobile, and sharing.
transcode_h265
Convert to MP4 (H.265/HEVC). Smaller files, same quality. Slower to encode.
compress_web
Shrink video for web delivery. Targets ≤2 Mbps with minimal quality loss.
thumbnail_jpg
Extract a JPEG thumbnail at the midpoint of the video. Returns an image URL.
scale_fit_max
Downscale to max 1080p on longest side. Preserves aspect ratio.
extract_audio
Extract audio track as MP3 (192kbps). Strips video entirely.
gif_loop
Convert first 10 seconds to a looping GIF at 480p. Great for previews.
vertical_crop
Center-crop to 9:16 aspect ratio for Reels/TikTok/Shorts.

Webhooks

Pass a webhook_url in your request and ffpipe will POST the completed job result to that URL. This is the recommended approach for n8n workflows — no polling needed.

Webhook payload
{
  "job_id": "job_01HXB8K...",
  "status": "completed",
  "output_url": "https://cdn.ffpipe.net/out/...",
  "duration_seconds": 8.4,
  "file_size_bytes": 12480000
}

In n8n, create a Webhook trigger node and paste its URL as the webhook_url.

Error handling

HTTP status codes follow standard conventions:

CodeMeaning
200Success
400Bad request — check your parameters
401Unauthorized — invalid or missing API key
402Quota exceeded — upgrade plan or wait for reset
413File too large for your plan
422FFmpeg error — check your command or input file
500Server error — retry or contact support

Questions? Email hello@ffpipe.net