Documentación de la API de FreeLipSync

Antes de comenzar

Usa la API REST de FreeLipSync para generar vídeos de sincronización labial, fotos parlantes y vídeos musicales a partir de tu audio. Necesitas una cuenta registrada, una API Key de la consola Agent y créditos de API. Todas las cuentas, incluidas las existentes, reciben 30 créditos de bienvenida una sola vez al cargar por primera vez el saldo en la consola Agent o enviar una solicitud de generación válida. Puedes comprar más créditos; la suscripción no incluye créditos de API periódicos. Tu plan determina los modelos disponibles, la duración y los límites de tareas compartidos.

Esta guía utiliza https://freelipsync.com/api/v1. Al probar en staging, configure FLS_BASE_URL en el origen de ese entorno y cree su clave en el mismo entorno. El acceso a la API debe estar habilitado en esa implementación. Los ejemplos utilizan un speech.mp3 corto y un face.jpg de una sola cara.

Abra la referencia de OpenAPI para obtener esquemas de solicitud y respuesta legibles por máquina. ¿Prefieres un agente? Consulte la guía de configuración MCP.

Autenticación y su primera solicitud

Cree una clave en la consola Agent y cópiela desde el cuadro de diálogo de creación. El secreto completo se muestra una vez. Guárdelo en una variable de entorno, no en el código del navegador ni en un repositorio público. Si se pierde, revocarlo y crear otro. Todas las claves utilizan el mismo saldo y límites de cuenta; crear otra clave no aumenta la simultaneidad.

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 acepta su API Key. Un token de acceso OAuth emitido para MCP solo es válido para /mcp, no para REST. Una respuesta exitosa envuelve su resultado en data e incluye un request_id; Los errores tienen error y request_id en su lugar. Los ID son cadenas opacas y los montos de crédito son cadenas decimales.

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

Esta es una respuesta de activo ilustrativa, no la respuesta a la solicitud de capacidades. Lea las capacidades devueltas para verificar los modelos de la cuenta actual, max_audio_seconds, los límites de bytes de carga/MIME y los límites de tareas antes de preparar los archivos.

El flujo de trabajo de generación

1. Obtenga capacidades y cargue una imagen o video más el audio de referencia.
2. Confirme cada carga directa y espere a que ambos activos se conviertan en ready.
3. Cree una cotización utilizando los ID de activos y un modo de generación. Revise total_points y expires_at.
4. Envíe esa cotización con una clave de idempotencia estable. Este acepta la tarea y retiene los créditos.
5. Sondee el ID del trabajo devuelto utilizando poll_after_seconds o reciba un webhook.
6. Cuando esté completo, descárguelo desde el URL firmado. Una tarea fallida devuelve su retención original.

La creación de activos y cotizaciones no gasta créditos ni crea trabajos de video. Una vez aceptada una generación, no se puede cancelar. Sólo el procesamiento fallido devuelve créditos; un tiempo de espera del cliente no es prueba de que la tarea haya fallado.

Cargar archivos locales o importar URL

Para un archivo local, POST /assets devuelve un PUT URL firmado. Envíe bytes de archivo sin formato con el upload.headers devuelto, sin su API Key. Luego llame a POST /assets/{id}/confirm con {} y sondee GET /assets/{id}. awaiting_upload y processing no están listos; failed es terminal. Utilice los consejos de consulta periódica del servidor.

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

size_bytes debe ser el recuento de bytes real, no este número de ejemplo. Las entradas de imagen, video y audio tienen diferentes límites de tamaño y MIME; utilice GET /capabilities como fuente de verdad. Las extensiones de archivo por sí solas no determinan la validez.

También puede importar un HTTPS URL accesible públicamente. Esto es asincrónico: sondea el activo devuelto hasta que esté listo. Una ruta local, file:// URL, red privada URL o URL que requiera cookies de su sitio web no es una fuente utilizable. Si utiliza una fuente firmada URL, déle tiempo suficiente para que se recupere.

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"

Una tercera ruta es POST /asset-upload-sessions con {"kind":"image"}: devolver el browser_upload_url al usuario, conservar el asset_id y sondearlo después de cargarlo en el navegador. Esto es útil para clientes que no pueden leer archivos locales. Cargar tickets y URL firmadas son credenciales temporales; no los publique en registros o transcripciones de chat.

Ejemplos de código completos

Elija cURL, Python o JavaScript a continuación. Cada ejemplo realiza el mismo flujo de trabajo de carga → cotización → envío → consulta periódica → descarga, imprime la cotización y pregunta antes de gastar créditos. Los ejemplos largos se colapsan; el botón Copiar siempre copia el programa completo.

• cURL: Bash, cURL, jq y Python 3 (para UUID). Guárdelo como un script Bash y ejecútelo.
• Python: Python 3 con la biblioteca requests; instálala con python -m pip install requests.
• JavaScript: Node.js 20+ y módulos integrados únicamente. Guarde como quickstart.mjs y ejecute node quickstart.mjs.

Exporte las variables de entorno anteriores y coloque face.jpg y speech.mp3 en el directorio de trabajo. Ejecútelo en su servidor o máquina de desarrollo, no en una página web pública. Las solicitudes de carga/descarga firmadas nunca incluyen su API Key. Los scripts se detienen ante errores HTTP; verifique las reglas de recuperación a continuación antes de volver a intentarlo, en lugar de reiniciar un envío posiblemente aceptado con una nueva clave.

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

Modelos, opciones y créditos.

Todos los modos requieren un recurso de audio de referencia cargado. La conversión de texto a voz, la clonación y cancelación de voz no son parámetros de esta API. Image Super / Motion Control requiere Starter o Pro; la compra de créditos por sí sola no lo permite. Verifique las capacidades para conocer la disponibilidad del modelo y los límites de duración, incluidas las excepciones específicas del modelo.

La facturación redondea hacia arriba la duración verificada del audio al segundo entero, con un mínimo de 5 segundos. Un presupuesto de 5 segundos cuesta 5 créditos con Image Fast, 10 con Image Max y 15 con Image Super o Music Video. Crear un presupuesto no descuenta créditos. Al enviar la tarea se reserva el importe indicado; si se completa, se cobra ese mismo importe, y si falla el procesamiento, se devuelve la reserva. No se ajusta el precio después de generar. Los créditos comprados son independientes de la suscripción, no caducan y no son reembolsables en efectivo.

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

Para Music Video, utilice mode: "music_video" y la configuración MV a continuación. version acepta 1.0 o 1.1; ratio acepta 21:9, 16:9, 4:3, 1:1, 3:4 o 9:16; resolution acepta 480p o 720p. Los valores predeterminados son 1.0, 16:9 y 480p. Verifique las capacidades del esquema en vivo. No adjunte opciones de movimiento a otro modo ni envíe alias de modelos web internos.

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

Referencia de punto final

Las rutas siguientes son relativas a /api/v1. Todas las llamadas comerciales requieren autenticación.

Muestra los elementos predeterminados de 20, máximo 50. Pase data.next_cursor sin cambios para buscar la página siguiente. Para varios trabajos activos, utilice ids separados por comas en una solicitud de lista en lugar de sondear cada uno por separado. La lista es para trabajos de crédito API/MCP, no una lista general de trabajos de sitios web más antiguos.

Idempotencia, errores y límites de solicitudes

Utilice un Idempotency-Key nuevo para cada operación de escritura distinta y mantenga la misma clave y carga útil cuando vuelva a intentar esa operación. Las claves son caracteres ASCII visibles 8–128. Una nueva solicitud de usuario necesita una nueva clave; un reintento no. Los ejemplos imprimen el par de cotización/clave antes del envío. En producción, conserve ese par antes de enviarlo y conserve el ID del trabajo devuelto. No reinicie todo el ejemplo después de un envío incierto: eso crearía una nueva clave.

Las cotizaciones vencen en minutos 10. Un rechazo definitivo antes de la aceptación le permite corregir la solicitud u obtener una nueva cotización; una respuesta incierta requiere recuperar primero el intento original. Al reproducir una tarea aceptada se devuelve su trabajo original sin un segundo débito. Una cotización no se puede gastar dos veces bajo claves diferentes.

REST y MCP comparten un depósito auxiliar/de lectura por cuenta: Free 30, Starter 30, Pro 60 solicitudes por minuto. Las llamadas auxiliares incluyen cargas, confirmación y cotizaciones. Respetar poll_after_seconds y Retry-After, el que requiera mayor espera. Las lecturas del estado del sitio web se gestionan por separado; La frecuencia de generación y la capacidad de ejecución de video se comparten entre el sitio web, REST y MCP. El sitio web y API/MCP tienen cada uno una asignación independiente de tareas pendientes: Free 1, Starter 3, Pro 10 por grupo. REST y MCP comparten el grupo API/MCP, incluidas todas las claves y conexiones OAuth; Las credenciales adicionales nunca lo multiplican. Consulte por qué utilizar API/MCP para ver ejemplos de flujo de trabajo.

Resultados y webhooks opcionales

Los trabajos tienen estado queued, processing, completed o failed. Conserve la identificación del trabajo cuando su solicitud expire; su tiempo de espera no cancela la tarea del servidor. En caso de éxito, utilice output.download_url mientras sea válido. Vuelva a buscar el trabajo o descargue el punto final para obtener un enlace renovado mientras se conserva el trabajo; Las descargas repetidas no gastan créditos. La retención sigue la retención de trabajo normal de su cuenta, no un período separado solo de API. La producción es de calidad original, sin marca de agua y utilizable comercialmente sujeto a sus derechos de origen y los términos.

Para integraciones de servidor, cree un punto final de webhook en la consola Agent → Avanzado y luego pase su ID como webhook_endpoint_id al enviarlo. Su punto final primero debe responder al POST endpoint.verification con el desafío como un cuerpo de respuesta de texto sin formato. Esta configuración utiliza la consola del sitio web, no una API pública de administración de credenciales.

Los eventos de webhook contienen event_id, event_type, occurred_at, generation_id y data. Los enlaces de descarga se omiten en las cargas útiles de los webhooks; Consulta el trabajo para obtener un enlace nuevo. Verifique FLS-Webhook-Signature con el cuerpo de solicitud raw: HMAC-SHA256 de timestamp + "." + body, utilizando su secreto de punto final, con la marca de tiempo de FLS-Webhook-Timestamp; haga coincidir una firma v1= en tiempo constante y aplique una marca de tiempo reciente para rechazar repeticiones. Elimine los duplicados mediante event_id / FLS-Webhook-Id y devuelva 2xx lo antes posible. Las notificaciones duplicadas no deben desencadenar otra generación ni una segunda acción empresarial. Siga las consultas periódicas como la primera integración más simple.

¿Necesita trabajar con un asistente en lugar de HTTP? Configure MCP con su agente, o regrese a la consola Agent.