Documentation de l’API FreeLipSync

Avant de commencer

Utilisez l’API REST de FreeLipSync pour générer des vidéos synchronisées, des photos parlantes et des clips musicaux à partir de votre audio. Il vous faut un compte inscrit, une API Key créée dans la console Agent et des crédits API. Tous les comptes, y compris les comptes existants, reçoivent une seule fois 30 crédits de bienvenue au premier chargement du solde dans la console Agent ou à l’envoi d’une demande de génération valide. Vous pouvez ensuite acheter des crédits ; l’abonnement ne comprend pas de crédits API périodiques. Il détermine les modèles disponibles, la durée et les limites de tâches partagées.

Ce guide utilise https://freelipsync.com/api/v1. Lors des tests sur staging, définissez FLS_BASE_URL sur l'origine de cet environnement et créez votre clé dans le même environnement. L'accès à l'API doit être activé sur ce déploiement. Les exemples utilisent un speech.mp3 court et un face.jpg simple face.

Ouvrez la référence OpenAPI pour les schémas de requête et de réponse lisibles par machine. Vous préférez un agent? Consultez le Guide de configuration MCP.

Authentification et votre première demande

Créez une clé dans la console Agent et copiez-la depuis la boîte de dialogue de création. Le secret complet est montré une fois. Stockez-le dans une variable d'environnement, pas dans le code du navigateur ou dans un référentiel public. En cas de perte, révoquez-le et créez-en un autre. Toutes les clés utilisent le même solde et les mêmes limites de compte ; la création d'une autre clé n'augmente pas la concurrence.

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 accepte votre API Key. Un jeton d'accès OAuth émis pour MCP n'est valable que pour /mcp, pas pour REST. Une réponse réussie enveloppe son résultat dans data et inclut un request_id ; les erreurs ont à la place error et request_id. Les identifiants sont des chaînes opaques et les montants des crédits sont des chaînes décimales.

{"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"}

Il s’agit d’une réponse illustrative en matière d’actifs, et non d’une réponse à la demande de capacités. Lisez les fonctionnalités renvoyées pour vérifier les modèles du compte actuel, max_audio_seconds, les limites d'octets/MIME de téléchargement et les limites de tâches avant de préparer les fichiers.

Le workflow de génération

1. Récupérez les capacités et téléchargez une image ou une vidéo ainsi que l'audio de conduite.
2. Confirmez chaque téléchargement direct et attendez que les deux ressources deviennent ready.
3. Créez un devis à l'aide des identifiants d'actifs et d'un mode de génération. Passez en revue total_points et expires_at.
4. Soumettez ce devis avec une clé d'idempotence stable. Celui-ci accepte la tâche et détient des crédits.
5. Interrogez l’ID de tâche renvoyé à l’aide de poll_after_seconds ou recevez un webhook.
6. Une fois terminé, téléchargez à partir du URL signé. Une tâche ayant échoué renvoie sa prise d'origine.

La création d'actifs et de devis ne dépense pas de crédits et ne crée pas de tâches vidéo. Une fois qu'une génération a été acceptée, elle ne peut plus être annulée. Seul l'échec du traitement renvoie des crédits ; un délai d'attente client ne constitue pas une preuve que la tâche a échoué.

Téléchargez des fichiers locaux ou importez des URL

Pour un fichier local, POST /assets renvoie un PUT URL signé. Envoyez des octets de fichier brut avec le upload.headers renvoyé, sans votre API Key. Appelez ensuite POST /assets/{id}/confirm avec {} et interrogez GET /assets/{id}. awaiting_upload et processing ne sont pas prêts ; failed est le terminal. Utilisez les conseils d'interrogation du serveur.

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

size_bytes doit être le nombre réel d’octets, et non cet exemple de numéro. Les entrées image, vidéo et audio ont des limites de taille et de MIME différentes ; utilisez GET /capabilities comme source de vérité. Les extensions de fichiers à elles seules ne déterminent pas la validité.

Vous pouvez également importer un HTTPS URL accessible au public. Ceci est asynchrone : interrogez l'actif renvoyé jusqu'à ce qu'il soit prêt. Un chemin local, file:// URL, un réseau privé URL ou URL nécessitant les cookies de votre site Web n'est pas une source utilisable. Si vous utilisez une source signée URL, donnez-lui suffisamment de temps pour être récupérée.

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"

Une troisième route est POST /asset-upload-sessions avec {"kind":"image"} : renvoie le browser_upload_url à l'utilisateur, conserve le asset_id et l'interroge après son téléchargement dans le navigateur. Ceci est utile pour les clients qui ne peuvent pas lire les fichiers locaux. Les tickets de téléchargement et les URL signées sont des informations d'identification temporaires ; ne les publiez pas dans les journaux ou les transcriptions de chat.

Exemples de code complets

Choisissez cURL, Python ou JavaScript ci-dessous. Chaque exemple effectue le même workflow de téléchargement → devis → soumission → vérification périodique → téléchargement, en imprimant le devis et en demandant avant de dépenser des crédits. Les longs exemples sont réduits ; le bouton Copier copie toujours le programme complet.

• cURL : Bash, cURL, jq et Python 3 (pour les UUID). Enregistrez-le en tant que script Bash et exécutez-le.
• Python : Python 3 avec la bibliothèque requests ; installez-la avec python -m pip install requests.
• JavaScript : Node.js 20+ et modules intégrés uniquement. Enregistrez sous quickstart.mjs et exécutez node quickstart.mjs.

Exportez les variables d'environnement ci-dessus et placez face.jpg et speech.mp3 dans le répertoire de travail. Exécutez sur votre serveur ou machine de développement, pas sur une page Web publique. Les demandes de téléchargement/téléchargement signées n'incluent jamais votre API Key. Les scripts s'arrêtent en cas d'erreurs HTTP ; vérifiez les règles de récupération ci-dessous avant de réessayer, plutôt que de redémarrer une soumission éventuellement acceptée avec une nouvelle clé.

# 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")"

Modèles, options et crédits

Tous les modes nécessitent un élément audio de conduite téléchargé. La synthèse vocale, le clonage vocal et l'annulation ne sont pas des paramètres de cette API. Image Super / Motion Control nécessite Starter ou Pro ; l’achat de crédits à lui seul ne permet pas cela. Vérifiez les fonctionnalités pour connaître la disponibilité du modèle et les limites de durée, y compris les exceptions spécifiques au modèle.

La durée audio vérifiée est arrondie à la seconde supérieure, avec un minimum de 5 secondes. Un devis de 5 secondes coûte 5 crédits avec Image Fast, 10 avec Image Max et 15 avec Image Super ou Music Video. Créer un devis ne débite pas le portefeuille. L’envoi réserve le montant du devis ; la réussite consomme ce même montant et un échec de traitement le restitue. Aucun ajustement de prix n’a lieu après la génération. Les crédits achetés sont indépendants de l’abonnement, n’expirent pas et ne sont pas remboursables en argent.

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

Pour Music Video, utilisez mode: "music_video" et les paramètres MV ci-dessous. version accepte 1.0 ou 1.1 ; ratio accepte 21:9, 16:9, 4:3, 1:1, 3:4 ou 9:16 ; resolution accepte 480p ou 720p. Les valeurs par défaut sont 1.0, 16:9 et 480p. Vérifiez les capacités du schéma en direct. N'attachez pas d'options de mouvement à un autre mode et n'envoyez pas d'alias de modèle Web interne.

{
  "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"}}}
}

Référence du point de terminaison

Les chemins ci-dessous sont relatifs à /api/v1. Tous les appels professionnels nécessitent une authentification.

Répertorie par défaut les éléments 20, maximum 50. Passez data.next_cursor inchangé pour récupérer la page suivante. Pour plusieurs tâches actives, utilisez des ids séparés par des virgules dans une requête de liste au lieu de les interroger séparément. La liste concerne les tâches de crédit API/MCP, et non une liste générale des anciennes tâches de votre site Web.

Idempotence, erreurs et limites de taux

Utilisez un nouveau Idempotency-Key pour chaque opération d’écriture distincte et conservez la même clé et la même charge utile lorsque vous réessayez cette opération. Les clés sont des caractères ASCII visibles 8 – 128. Une nouvelle demande utilisateur nécessite une nouvelle clé ; une nouvelle tentative ne le fait pas. Les exemples impriment la paire devis/clé avant la soumission. En production, conservez cette paire avant d’envoyer et conservez l’ID de tâche renvoyé. Ne redémarrez pas tout l'exemple après une soumission incertaine : cela créerait une nouvelle clé.

Les devis expirent dans 10 minutes. Un refus définitif avant acceptation vous permet de corriger la demande ou d'obtenir un nouveau devis ; une réponse incertaine nécessite d'abord de récupérer la tentative d'origine. La relecture d'une tâche acceptée renvoie sa tâche d'origine sans deuxième débit. Un devis ne peut pas être dépensé deux fois sous des clés différentes.

REST et MCP partagent un compartiment de lecture/auxiliaire par compte : Free 30, Starter 30, Pro 60 requêtes par minute. Les appels auxiliaires incluent les téléchargements, les confirmations et les devis. Respectez poll_after_seconds et Retry-After, selon celui qui nécessite une attente plus longue. Les lectures de l'état du site Web sont gérées séparément ; la fréquence de génération et la capacité d'exécution vidéo sont partagées sur le site Web, REST et MCP. Le site Web et l'API/MCP disposent chacun d'une allocation de tâches inachevées indépendante : Free 1, Starter 3, Pro 10 par pool. REST et MCP partagent le pool API/MCP, y compris toutes les clés et connexions OAuth ; les informations d'identification supplémentaires ne le multiplient jamais. Voir pourquoi utiliser API/MCP pour des exemples de flux de travail.

Résultats et webhooks facultatifs

Les travaux ont le statut queued, processing, completed ou failed. Conservez l'identifiant du poste lorsque votre candidature expire ; votre délai d'attente n'annule pas la tâche du serveur. En cas de succès, utilisez output.download_url tant qu'il est valide. Récupérez le travail ou téléchargez le point de terminaison pour obtenir un lien renouvelé pendant que le travail est conservé ; les téléchargements répétés ne dépensent pas de crédits. La conservation suit la conservation normale du travail de votre compte, et non une période distincte réservée uniquement à l'API. La sortie est de qualité originale, sans filigrane, et utilisable commercialement sous réserve de vos droits d'origine et des conditions.

Pour les intégrations de serveur, créez un point de terminaison webhook dans la console Agent → Avancé, puis transmettez son ID comme webhook_endpoint_id lors de la soumission. Votre point de terminaison doit d’abord répondre au POST endpoint.verification avec le défi sous forme de corps de réponse en texte brut. Cette configuration utilise la console du site Web et non une API publique de gestion des informations d'identification.

Les événements Webhook contiennent event_id, event_type, occurred_at, generation_id et data. Les liens de téléchargement sont omis des charges utiles du webhook ; interrogez le travail pour un nouveau lien. Vérifiez FLS-Webhook-Signature par rapport au corps brut de la requête : HMAC-SHA256 de timestamp + "." + body, à l'aide de votre secret de point de terminaison, avec l'horodatage de FLS-Webhook-Timestamp ; faites correspondre une signature v1= en temps constant et appliquez un horodatage récent pour rejeter les rediffusions. Dédupliquez par event_id / FLS-Webhook-Id et renvoyez 2xx rapidement. Les notifications en double ne doivent pas déclencher une autre génération ou une deuxième action commerciale. Conservez le vérification périodique comme la première intégration la plus simple.

Besoin de travailler via un assistant au lieu de HTTP ? Configurez MCP avec votre agent ou revenez à Console Agent.