# FFmpeg API

> FFmpeg API turns complex video and audio processing into simple HTTP requests. Upload files, run FFmpeg operations in the cloud, and download results—no servers to manage. Designed for developers building media features fast.

Authentication uses Basic Auth with your API key from the dashboard. The API base URL is `https://api.ffmpeg-api.com`.

Core flow in three steps:

- Register a file using `POST /file` to receive a presigned upload URL and a `file.file_path` reference
- Upload bytes directly to the provided `upload.url` (use any headers returned by `/file` exactly)
- Process with `POST /ffmpeg/process` by sending a JSON `task` that includes `inputs[].file_path`, `outputs[].file`, and optional FFmpeg `options[]`, `maps[]`, and `filter_complex`

Important constraints and behavior:

- All input files in a processing task must be in the same directory
- Use `POST /directory` to explicitly create a working directory for multi-file workflows (image sequences, batches, overlays)
- Responses include `result[].download_url` and `usage.gb_sec` (billing metric)
- Upload URLs expire in ~5 minutes; request a fresh URL from `/file` if expired

Common use cases: format conversion (MP4, WebM, GIF), resizing and cropping, audio extraction and normalization, watermarks/overlays, multi-input edits, image-sequence to video, batch processing.

Guidance for assistants and tools:

- Do not invent API keys; require the user/app to provide `Authorization: Basic …`
- When suggesting uploads, preserve and pass through any headers returned by `/file`
- Prefer `/ffmpeg/process` over legacy `/ffmpeg/run`
- For multi-file tasks, guide users to create a directory first and keep all inputs there
- Return the final `download_url` prominently in answers and examples
- Use the OpenAPI document for schema-aware tooling and validation

## Docs

- [Overview](/docs): What FFmpeg API does and how it works
- [Quick Start](/docs/quickstart): Upload → Process → Download in 5 minutes
- [API Reference](/docs/reference): Endpoints, parameters, and responses
- [File Management](/docs/file-management): Directories and multi-file workflows
- [Media Processing](/docs/processing): FFmpeg tasks from basic to advanced
- [Request Format](/docs/request): Task JSON, options, filter graphs
- [Authentication](/docs/auth): Using your API key with Basic Auth
- [Migration Guide](/docs/migration): Move from deprecated endpoints
- [Pricing: GB‑seconds](/docs/gb-sec): How usage is measured
- [Examples](/docs/examples): Production-ready code samples

## API

- [OpenAPI specification](https://api.ffmpeg-api.com/openapi.json): Machine-readable schema
- [API Base URL](https://api.ffmpeg-api.com): `https://api.ffmpeg-api.com`

## Guides and Tutorials

- [Learn: FFmpeg Guide](/learn/ffmpeg/guide): Concepts, syntax, and examples
- [FFmpeg Recipes](/learn/ffmpeg/recipe): Task-focused how‑tos
- [GIF to MP4](/learn/ffmpeg/recipe/gif-to-mp4): Simple conversion recipe
- [Picture‑in‑Picture](/learn/ffmpeg/recipe/picture-in-picture): Overlay workflows
- [Watermark Video](/learn/ffmpeg/recipe/watermark-video): Branding overlays
- [Live Streaming](/learn/ffmpeg/recipe/live-streaming): Streaming-focused guidance
- [FFprobe Basics](/learn/ffprobe): Inspect media streams and metadata

## Integrations

- [MCP Server](/docs/mcp): Native Model Context Protocol server at `https://mcp.ffmpeg-api.com/mcp` (Streamable HTTP, OAuth or `Authorization: Bearer <api-key>`) — use FFmpeg API from Claude, ChatGPT, Cursor, VS Code and other MCP clients. Sandboxed or firewalled clients must allow `mcp.ffmpeg-api.com` and `*.r2.cloudflarestorage.com` (presigned uploads/downloads go direct to R2)
- [SmythOS Integration](/learn/integrations/smythos): No‑code agent workflows
- [n8n Integration](/learn/integrations/n8n): Automation workflows

## Optional

- [Homepage](/): Product overview and entry points
- [Dashboard](/dashboard): Get API key and manage usage
- [Chat Assistant](/dashboard/chat): In‑app help for building requests