FreeLipSync API-Dokumentation

Bevor Sie beginnen

Mit der REST API von FreeLipSync erzeugst du lippensynchrone Videos, sprechende Fotos und Musikvideos aus deinen Audiodateien. Du benötigst ein registriertes Konto, einen API Key aus der Agent-Konsole und API-Credits. Jedes Konto erhält einmalig 30 Willkommens-Credits, sobald erstmals das Guthaben in der Agent-Konsole geladen oder ein gültiger Generierungsauftrag eingereicht wird. Das gilt auch für bestehende Konten. Weitere Credits kannst du kaufen; die Mitgliedschaft enthält keine regelmäßigen API-Credits. Dein Tarif bestimmt verfügbare Modelle, Dauer und gemeinsam genutzte Aufgabenlimits.

In diesem Handbuch wird https://freelipsync.com/api/v1 verwendet. Wenn Sie staging testen, legen Sie FLS_BASE_URL auf den Ursprung dieser Umgebung fest und erstellen Sie Ihren Schlüssel in derselben Umgebung. Der API-Zugriff muss für diese Bereitstellung aktiviert sein. In den Beispielen werden ein kurzer speech.mp3 und ein einseitiger face.jpg verwendet.

Öffnen Sie die OpenAPI-Referenz für maschinenlesbare Anforderungs- und Antwortschemata. Bevorzugen Sie einen Agenten? Siehe die MCP-Einrichtungsanleitung.

Authentifizierung und Ihre erste Anfrage

Erstellen Sie einen Schlüssel in der Agent-Konsole und kopieren Sie ihn aus dem Erstellungsdialog. Das vollständige Geheimnis wird einmal angezeigt. Speichern Sie es in einer Umgebungsvariablen, nicht im Browsercode oder in einem öffentlichen Repository. Wenn es verloren geht, widerrufen Sie es und erstellen Sie ein neues. Alle Schlüssel verwenden denselben Kontostand und dieselben Limits. Durch das Erstellen eines weiteren Schlüssels wird die Parallelität nicht erhöht.

export FLS_BASE_URL='https://freelipsync.com'
export FLS_API_KEY='YOUR_API_KEY'
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $FLS_API_KEY" \
  "$FLS_BASE_URL/api/v1/capabilities"

REST akzeptiert Ihren API Key. Ein für MCP ausgestelltes OAuth-Zugriffstoken ist nur für /mcp gültig, nicht für REST. Eine erfolgreiche Antwort verpackt ihr Ergebnis in data und enthält einen request_id; Fehler haben stattdessen error und request_id. IDs sind undurchsichtige Zeichenfolgen und Guthabenbeträge sind Dezimalzeichenfolgen.

{"data":{"id":"YOUR_ASSET_ID","kind":"image","status":"processing","poll_after_seconds":5,"expires_at":"2026-10-21T00:00:00.000Z"},"request_id":"REQUEST_ID"}

Dies ist eine veranschaulichende Asset-Antwort, nicht die Antwort auf die Funktionsanfrage. Lesen Sie die zurückgegebenen Funktionen, um die Modelle des aktuellen Kontos, max_audio_seconds, Upload-Byte/MIME-Limits und Aufgabenlimits zu überprüfen, bevor Sie Dateien vorbereiten.

Der Generierungsworkflow

1. Rufen Sie Funktionen ab und laden Sie ein Bild oder Video sowie den Fahrton hoch.
2. Bestätigen Sie jeden direkten Upload und warten Sie, bis beide Assets zu ready werden.
3. Erstellen Sie ein Angebot mithilfe der Asset-IDs und eines Generierungsmodus. Überprüfen Sie total_points und expires_at.
4. Senden Sie dieses Angebot mit einem stabilen Idempotenzschlüssel. Dieser nimmt die Aufgabe an und hält Credits.
5. Fragen Sie die zurückgegebene Job-ID mit poll_after_seconds ab oder empfangen Sie einen Webhook.
6. Wenn Sie fertig sind, laden Sie es vom signierten URL herunter. Eine fehlgeschlagene Aufgabe gibt ihre ursprüngliche Sperre zurück.

Durch das Erstellen von Assets und Angeboten werden weder Credits ausgegeben noch Videojobs erstellt. Sobald eine Generation akzeptiert wurde, kann sie nicht mehr abgebrochen werden. Nur ein Verarbeitungsfehler gibt Gutschriften zurück; Ein Client-Timeout ist kein Beweis dafür, dass die Aufgabe fehlgeschlagen ist.

Laden Sie lokale Dateien hoch oder importieren Sie URLs

Für eine lokale Datei gibt POST /assets einen signierten PUT URL zurück. Senden Sie rohe Dateibytes mit dem zurückgegebenen upload.headers, ohne Ihr API Key. Rufen Sie dann POST /assets/{id}/confirm mit {} auf und fragen Sie GET /assets/{id} ab. awaiting_upload und processing sind nicht bereit; failed ist Terminal. Nutzen Sie die Polling-Hinweise des Servers.

{
  "kind":"image",
  "source":{
    "type":"upload",
    "filename":"face.jpg",
    "content_type":"image/jpeg",
    "size_bytes":123456
  }
}

size_bytes muss die tatsächliche Byteanzahl sein, nicht diese Beispielzahl. Für Bild-, Video- und Audioeingänge gelten unterschiedliche MIME- und Größenbeschränkungen. Verwenden Sie GET /capabilities als Quelle der Wahrheit. Dateierweiterungen allein bestimmen nicht die Gültigkeit.

Sie können auch ein öffentlich erreichbares HTTPS URL importieren. Dies ist asynchron: Fragen Sie das zurückgegebene Asset ab, bis es bereit ist. Ein lokaler Pfad, file:// URL, privates Netzwerk URL oder URL, der Ihre Website-Cookies erfordert, ist keine verwendbare Quelle. Wenn Sie eine signierte Quelle URL verwenden, geben Sie ihr genügend Zeit zum Abrufen.

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $FLS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: image-import-UNIQUE-REQUEST-ID' \
  --data '{"kind":"image","source":{"type":"url","url":"https://YOUR-PUBLIC-HOST/face.jpg"}}' \
  "$FLS_BASE_URL/api/v1/assets"

Eine dritte Route ist POST /asset-upload-sessions mit {"kind":"image"}: browser_upload_url an den Benutzer zurückgeben, asset_id behalten und nach dem Hochladen im Browser abfragen. Dies ist nützlich für Clients, die lokale Dateien nicht lesen können. Upload-Tickets und signierte URLs sind temporäre Anmeldeinformationen; Veröffentlichen Sie sie nicht in Protokollen oder Chat-Transkripten.

Vollständige Codebeispiele

Wählen Sie unten cURL, Python oder JavaScript. In jedem Beispiel wird derselbe Workflow „Upload → Angebot → Absenden → Umfrage → Download“ durchgeführt, bei dem das Angebot gedruckt und nachgefragt wird, bevor Credits ausgegeben werden. Lange Beispiele sind ausgeblendet; Die Schaltfläche „Kopieren“ kopiert immer das komplette Programm.

• cURL: Bash, cURL, jq und Python 3 (für UUIDs). Speichern Sie es als Bash-Skript und führen Sie es aus.
• Python: Python 3 mit der Bibliothek requests; Installation mit python -m pip install requests.
• JavaScript: Nur Node.js 20+ und integrierte Module. Speichern Sie es als quickstart.mjs und führen Sie node quickstart.mjs aus.

Exportieren Sie die oben genannten Umgebungsvariablen und platzieren Sie face.jpg und speech.mp3 im Arbeitsverzeichnis. Führen Sie es auf Ihrem Server oder Entwicklungscomputer aus, nicht auf einer öffentlichen Webseite. Signierte Upload-/Download-Anfragen enthalten niemals Ihr API Key. Skripte stoppen bei HTTP-Fehlern; Überprüfen Sie die Wiederherstellungsregeln unten, bevor Sie es erneut versuchen, anstatt eine möglicherweise akzeptierte Übermittlung mit einem neuen Schlüssel neu zu starten.

# Requires bash, curl and jq. Set these before running:
# export FLS_API_KEY='YOUR_API_KEY'
# export FLS_BASE_URL='https://freelipsync.com'  # or your staging origin
# Place face.jpg and speech.mp3 in this directory.
set -euo pipefail
: "${FLS_API_KEY:?Set FLS_API_KEY first}"
BASE="${FLS_BASE_URL:-https://freelipsync.com}/api/v1"
RUN="$(python3 -c 'import uuid; print(uuid.uuid4())')"
request() {
  curl --fail-with-body --silent --show-error \
    -H "Authorization: Bearer $FLS_API_KEY" "$@"
}
wait_ready() {
  local id="$1" row status
  for ((i=0; i<120; i++)); do
    row="$(request "$BASE/assets/$id")"

Modelle, Optionen und Credits

Für alle Modi ist ein hochgeladenes Fahraudio-Asset erforderlich. Text-to-Speech, Sprachklonen und Löschung sind keine Parameter dieser API. Image Super / Motion Control erfordert Starter oder Pro; Durch den Kauf von Credits allein ist dies nicht möglich. Überprüfen Sie die Funktionen auf Modellverfügbarkeit und Dauerbeschränkungen, einschließlich modellspezifischer Ausnahmen.

Die geprüfte Audiodauer wird auf volle Sekunden aufgerundet; mindestens werden 5 Sekunden berechnet. Ein Angebot für 5 Sekunden kostet bei Image Fast 5 Credits, bei Image Max 10 und bei Image Super oder Music Video 15. Ein Angebot allein belastet das Guthaben nicht. Beim Einreichen wird der Angebotsbetrag reserviert; bei Erfolg wird genau dieser Betrag verbraucht, bei einem Verarbeitungsfehler wird er freigegeben. Es gibt keine nachträgliche Preisanpassung. Gekaufte Credits sind von der Mitgliedschaft getrennt, verfallen nicht und werden nicht in Geld erstattet.

{
  "mode":"image_super",
  "face_asset_id":"READY_IMAGE_ID",
  "audio_asset_id":"READY_AUDIO_ID",
  "options":{"motion":{"action":"Smile gently","camera":"Static camera"}}
}

Für Music Video verwenden Sie mode: "music_video" und die MV-Einstellungen unten. version akzeptiert 1.0 oder 1.1; ratio akzeptiert 21:9, 16:9, 4:3, 1:1, 3:4 oder 9:16; resolution akzeptiert 480p oder 720p. Die Standardeinstellungen sind 1.0, 16:9 und 480p. Überprüfen Sie die Funktionen für das Live-Schema. Hängen Sie keine Bewegungsoptionen an einen anderen Modus an und senden Sie keine internen Webmodell-Aliase.

{
  "mode":"music_video",
  "face_asset_id":"READY_IMAGE_ID",
  "audio_asset_id":"READY_AUDIO_ID",
  "options":{"mv":{"version":"1.0","ratio":"16:9","resolution":"480p","style":{"directorial":"A calm performance","artistic":"Warm evening light"}}}
}

Endpunktreferenz

Die folgenden Pfade beziehen sich auf /api/v1. Alle geschäftlichen Anrufe erfordern eine Authentifizierung.

Listet standardmäßig 20-Elemente auf, maximal 50.. Übergeben Sie data.next_cursor unverändert, um die nächste Seite abzurufen. Verwenden Sie für mehrere aktive Jobs das durch Kommas getrennte ids in einer Listenanforderung, anstatt jeden einzeln abzufragen. Die Liste gilt für API/MCP-Kreditjobs und ist keine allgemeine Liste Ihrer älteren Website-Jobs.

Idempotenz, Fehler und Ratengrenzen

Verwenden Sie für jeden einzelnen Schreibvorgang einen neuen Idempotency-Key und behalten Sie den gleichen Schlüssel und die gleiche Nutzlast bei, wenn Sie diesen Vorgang wiederholen. Schlüssel sind sichtbare ASCII-Zeichen 8–128. Eine neue Benutzeranfrage erfordert einen neuen Schlüssel; ein erneuter Versuch funktioniert nicht. Die Beispiele drucken das Zitat/Schlüssel-Paar vor der Übermittlung aus. Behalten Sie in der Produktion dieses Paar bei, bevor Sie es senden, und behalten Sie die zurückgegebene Job-ID bei. Starten Sie das gesamte Beispiel nach einer unsicheren Übermittlung nicht neu, da sonst ein neuer Schlüssel erstellt würde.

Angebote verfallen in 10 Minuten. Durch eine eindeutige Ablehnung vor der Annahme können Sie die Anfrage korrigieren oder ein neues Angebot einholen; Eine unsichere Reaktion erfordert zunächst die Wiederherstellung des ursprünglichen Versuchs. Durch das erneute Abspielen einer angenommenen Aufgabe wird der ursprüngliche Auftrag ohne eine zweite Belastung zurückgegeben. Ein Angebot kann nicht zweimal unter verschiedenen Schlüsseln ausgegeben werden.

REST und MCP teilen sich einen Lese-/Hilfs-Bucket pro Konto: Free 30, Starter 30, Pro 60 Anfragen pro Minute. Zu den Hilfsanrufen gehören Uploads, Bestätigungen und Angebote. Respektieren Sie poll_after_seconds und Retry-After, je nachdem, was eine längere Wartezeit erfordert. Das Lesen des Website-Status wird separat verwaltet. Die Generierungsfrequenz und die Videoausführungskapazität werden von der Website, REST und MCP gemeinsam genutzt. Die Website und API/MCP verfügen jeweils über eine unabhängige Zulage für nicht erledigte Aufgaben: Free 1, Starter 3, Pro 10 pro Pool. REST und MCP teilen sich den API/MCP-Pool, einschließlich aller Schlüssel und OAuth-Verbindungen; Zusätzliche Anmeldeinformationen vervielfachen es nie. Workflow-Beispiele finden Sie unter Warum API/MCP verwenden.

Ergebnisse und optionale Webhooks

Jobs haben den Status queued, processing, completed oder failed. Behalten Sie die Job-ID, wenn Ihre Bewerbung abläuft; Ihr Timeout bricht den Server-Task nicht ab. Bei Erfolg verwenden Sie output.download_url solange gültig. Rufen Sie den Auftrag erneut ab oder laden Sie den Endpunkt herunter, um einen erneuerten Link zu erhalten, während die Arbeit erhalten bleibt. Für wiederholte Downloads werden keine Credits ausgegeben. Die Aufbewahrung erfolgt nach der normalen Arbeitsaufbewahrung Ihres Kontos und nicht nach einem separaten reinen API-Zeitraum. Die Ausgabe erfolgt in Originalqualität, ohne Wasserzeichen und kann vorbehaltlich Ihrer Quellenrechte und der Bedingungen kommerziell genutzt werden.

Erstellen Sie für Serverintegrationen einen Webhook-Endpunkt in der Agent-Konsole → Erweitert und übergeben Sie bei der Übermittlung seine ID als webhook_endpoint_id. Ihr Endpunkt muss zunächst den endpoint.verification POST mit der Challenge als Klartext-Antworttext beantworten. Dieses Setup verwendet die Website-Konsole und keine öffentliche API zur Verwaltung von Anmeldeinformationen.

Webhook-Ereignisse enthalten event_id, event_type, occurred_at, generation_id und data. Download-Links werden in Webhook-Payloads weggelassen; Fragen Sie den Job nach einem neuen Link ab. Überprüfen Sie FLS-Webhook-Signature anhand des Rohanforderungstexts: HMAC-SHA256 von timestamp + "." + body unter Verwendung Ihres Endpunktgeheimnisses und des Zeitstempels von FLS-Webhook-Timestamp. Gleichen Sie eine v1=-Signatur in konstanter Zeit ab und erzwingen Sie einen aktuellen Zeitstempel, um Wiederholungen abzulehnen. Deduplizieren Sie durch event_id / FLS-Webhook-Id und geben Sie 2xx umgehend zurück. Doppelte Benachrichtigungen dürfen keine weitere Generierung oder eine zweite Geschäftsaktion auslösen. Behalten Sie die Abfrage als einfachste erste Integration bei.

Müssen Sie einen Assistenten anstelle von HTTP verwenden? MCP mit Ihrem Agenten einrichten oder zur Agent-Konsole zurückkehren.