Media Processing HTTP API

An HTTP API for processing video, audio, and images with FFmpeg. A request supplies named inputs and one or more FFmpeg command argument lists. Results can be uploaded to S3, returned as Base64 JSON, served as a completed file, or streamed from FFmpeg while it is running.

Endpoint

POST /v1/process

curl http://localhost:8080/v1/process \
  --request POST \
  --header "Content-Type: application/json" \
  --data '{
    "input": {
      "input.mp4": { "http": "https://example.com/video.mp4" }
    },
    "commands": [
      ["-i", "input.mp4", "-vn", "output.mp3"]
    ],
    "output": { "base64": true }
  }'

The request body has this shape:

{
  "s3Config": {},
  "input": {},
  "commands": [],
  "output": {}
}

Unknown fields and multiple JSON values in one request body are rejected.

Inputs

input maps a filename to exactly one source. Filenames cannot contain a directory path.

Field	Purpose
http	Download an accessible HTTP or HTTPS URL.
s3	Download an object such as s3://bucket/path/input.mp4.
base64	Decode Base64 content into the named input file.
temporary	Reserve a filename for an intermediate file created by a command. It is not fetched and is excluded from returned outputs.

{
  "input.mp4": {
    "http": "https://example.com/video.mp4"
  },
  "intermediate.wav": {
    "temporary": true
  }
}

Independent inputs are fetched concurrently. If the client disconnects, active HTTP downloads, S3 transfers, and FFmpeg processes are canceled.

Commands

commands is a non-empty array of FFmpeg argument lists. Commands run sequentially in an isolated job directory, so a later command can use a file produced by an earlier command. The service adds -hide_banner; do not include the ffmpeg executable itself.

[
  ["-i", "input.mp4", "-vn", "intermediate.wav"],
  ["-i", "intermediate.wav", "-codec:a", "libmp3lame", "output.mp3"]
]

Output modes

At least one output mode is required. S3 and Base64 can be combined. Inline output is exclusive because its response body is media rather than JSON.

S3

{
  "s3": "s3://my-bucket/outputs/"
}

Each output file is uploaded beneath the supplied prefix. The JSON response contains its resulting S3 URL.

Base64 JSON

{
  "base64": true
}

{
  "results": {
    "output.mp3": {
      "base64": "..."
    }
  }
}

Base64 responses hold encoded output in memory and are best suited to small files. Prefer S3 or HTTP output for larger media.

Completed file response

{
  "inlineContentType": "audio/mpeg"
}

FFmpeg finishes first, then the first output file is served with the supplied content type. No JSON body is returned.

Live FFmpeg stream

Set stream to true and make the final command write to standard output with pipe:1. An explicit -f is required because a pipe has no filename extension from which FFmpeg can infer a format.

curl http://localhost:8080/v1/process \
  --request POST \
  --header "Content-Type: application/json" \
  --dump-header stream.headers \
  --output output.mp3 \
  --data '{
    "input": {
      "input.wav": { "http": "https://example.com/audio.wav" }
    },
    "commands": [
      ["-i", "input.wav", "-f", "mp3", "pipe:1"]
    ],
    "output": {
      "stream": true,
      "inlineContentType": "audio/mpeg"
    }
  }'

The body begins as FFmpeg produces bytes and is not written to a temporary output file. The response ends with these HTTP trailers:

Trailer	Value
X-Ffmpeg-Status	ok when FFmpeg exits successfully, otherwise error.
X-Ffmpeg-Bytes	Number of media bytes written to the response.

The initial status is 200 OK before FFmpeg completes. A later FFmpeg failure therefore produces a truncated body with an error trailer rather than a different HTTP status. Clients and reverse proxies used for this mode must preserve HTTP trailers.

S3 configuration

s3Config is required when any input or output uses S3.

{
  "s3Config": {
    "endpoint": "s3.amazonaws.com",
    "region": "us-east-1",
    "accessKey": "AKIA...",
    "secretKey": "SECRET...",
    "useSSL": true
  }
}

The endpoint must not include a URL scheme or bucket name. useSSL defaults to true. AWS S3 and path-style S3-compatible services such as MinIO, DigitalOcean Spaces, and Cloudflare R2 are supported.

Docker

The published image contains the API and FFmpeg:

ghcr.io/aureum-cloud/ffmpeg-api:latest

docker run --detach --publish 8080:8080 ghcr.io/aureum-cloud/ffmpeg-api:latest

The API is then available at http://localhost:8080.

To build and test locally:

go test ./...
docker build --tag ffmpeg-api .

Operations

Each request gets its own temporary directory and FFmpeg process. Job files are removed when the response finishes. The container runs as an unprivileged user. The service keeps no session state and can be scaled horizontally behind a load balancer.

FFmpeg controls its own worker threads. Supply -threads 0 for automatic selection or a fixed value such as -threads 4 in the relevant command.

The API does not provide authentication. Deploy it behind an authenticated gateway and apply network controls appropriate for an endpoint that fetches URLs and executes FFmpeg workloads.