REST API Dokumentation

Microservice Integration & Webhooks für externe Server

Zurück zum Studio

Über diese API kannst du das FFmpeg Studio als Microservice nutzen und von externen Servern oder Webanwendungen aus Videos und Audiodateien konvertieren, zuschneiden und mit Wasserzeichen versehen.

Die API verarbeitet Anfragen asynchron: Du lädst eine Datei hoch, der Server startet sofort einen ressourcenschonenden Hintergrundprozess (background_worker) und du kannst entweder aktiv den Status abfragen (Polling) oder dich via Webhook benachrichtigen lassen, sobald die Datei fertig ist.

1. Authentifizierung

Die API ist durch einen API-Key geschützt. Der Standard-Key lautet (änderbar in der Datei api.php):

GEHEIMER_API_KEY_123

Du kannst den API-Key auf drei verschiedene Arten übergeben:

  1. Als HTTP-Header: X-API-Key: GEHEIMER_API_KEY_123
  2. Als GET-Parameter in der URL: ?api_key=GEHEIMER_API_KEY_123
  3. Als POST-Parameter im Body: api_key=GEHEIMER_API_KEY_123

2. Endpunkte

2.1 Datei hochladen & Konvertierung starten

POST /api.php?action=upload

Content-Type: multipart/form-data

Dieser Endpunkt nimmt eine Media-Datei sowie die Konvertierungsparameter entgegen und reiht sie in die Warteschlange ein.

Parameter (Form-Data)

Parameter Typ Pflicht Beschreibung
file File Ja Die zu konvertierende Video- oder Audiodatei.
type String Nein Zielmodus: video oder audio (Default: video).
format String Nein Das gewünschte Zielformat z.B. mp4, mkv, mp3 (Default: mp4).
videoCodec String Nein Videocodec libx264, libx265, libvpx-vp9, copy.
resolution String Nein Auflösung original, 1920x1080, etc.
fps String Nein Framerate original, 60, 30, 24.
crf Integer Nein Qualität 0-51 (Default: 23).
audioCodec String Nein Audiocodec aac, libmp3lame, copy, etc.
watermarkFile File Nein Optionales Bild (PNG/JPG) für ein Wasserzeichen.
webhook_url String Nein URL für die automatische Benachrichtigung nach Abschluss.

Beispiel-Response (Erfolg - HTTP 200)

{
  "success": true,
  "taskId": "api_6672c4b5e2a3f",
  "message": "Upload erfolgreich. Konvertierung im Hintergrund gestartet.",
  "status_url": "http://dein-server.de/api.php?action=status&taskId=api_...&api_key=..."
}

2.2 Status abfragen (Polling)

GET /api.php?action=status

Gibt in Echtzeit den prozentualen Fortschritt des FFmpeg-Prozesses zurück oder die fertigen Download-Links.

URL-Parameter

Beispiel-Response (Konvertierung läuft)

{
  "status": "progress",
  "percent": 45.2,
  "log": "frame= 1500 fps= 45 q=28.0 size= 5120kB time=00:00:50.00 ..."
}

Beispiel-Response (Konvertierung abgeschlossen)

{
  "status": "done",
  "downloadUrl": "download.php?file=api_6672c4b5e2a3f_video.mp4&name=video.mp4",
  "filename": "video.mp4"
}

3. Webhooks (Events)

Wenn du beim Hochladen den Parameter webhook_url definierst, sendet der Server einen HTTP POST Request mit einem JSON-Payload an deine URL, sobald die Konvertierung abgeschlossen ist oder ein Fehler auftrat.

Erfolgreicher Webhook-Payload

{
  "taskId": "api_6672c4b5e2a3f",
  "success": true,
  "originalName": "urlaubsvideo.mp4",
  "downloadUrl": "http://dein-server.de/download.php?file=...",
  "filename": "urlaubsvideo_converted.mp4"
}

4. Code Beispiele

cURL (Terminal)

curl -X POST http://dein-server.de/api.php?action=upload \
  -H "X-API-Key: GEHEIMER_API_KEY_123" \
  -F "file=@/pfad/zum/video.mp4" \
  -F "format=mp4" \
  -F "resolution=1920x1080" \
  -F "webhook_url=https://meine-app.com/callback/ffmpeg"

PHP (mit cURL)

<?php
$apiUrl = 'http://dein-server.de/api.php?action=upload';
$cfile = new CURLFile('/pfad/zum/lokalen/video.mp4', 'video/mp4', 'video.mp4');

$postData = [
    'api_key' => 'GEHEIMER_API_KEY_123',
    'file' => $cfile,
    'format' => 'webm',
    'webhook_url' => 'https://meine-app.com/api/video_fertig'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>