Dokumentasi API FreeLipSync

Sebelum Anda mulai

Gunakan REST API FreeLipSync untuk membuat video sinkronisasi bibir, foto berbicara, dan video musik dari audio Anda. Anda memerlukan akun terdaftar, API Key dari konsol Agent, dan kredit API. Setiap akun, termasuk akun lama, mendapat 30 kredit sambutan satu kali saat pertama kali memuat saldo di konsol Agent atau mengirim permintaan pembuatan yang valid. Kredit tambahan dapat dibeli; keanggotaan tidak mencakup kredit API berkala. Keanggotaan menentukan model, durasi, dan batas tugas bersama yang tersedia.

Panduan ini menggunakan https://freelipsync.com/api/v1. Saat menguji pada staging, atur FLS_BASE_URL ke asal lingkungan tersebut dan buat kunci Anda di lingkungan yang sama. Akses API harus diaktifkan pada penerapan tersebut. Contohnya menggunakan speech.mp3 pendek dan face.jpg satu wajah.

Buka referensi OpenAPI untuk skema permintaan dan respons yang dapat dibaca mesin. Lebih suka agen? Lihat panduan pengaturan MCP.

Otentikasi dan permintaan pertama Anda

Buat kunci di konsol Agent dan salin dari dialog pembuatan. Rahasia lengkapnya ditampilkan satu kali. Simpan dalam variabel lingkungan, bukan kode browser atau repositori publik. Jika hilang, cabut dan buat yang lain. Semua kunci menggunakan saldo dan batasan akun yang sama; membuat kunci lain tidak meningkatkan konkurensi.

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 menerima API Key Anda. Token akses OAuth yang diterbitkan untuk MCP hanya valid untuk /mcp, bukan untuk REST. Respons yang berhasil membungkus hasilnya dalam data dan menyertakan request_id; kesalahan memiliki error dan request_id sebagai gantinya. ID adalah string buram dan jumlah kredit adalah string desimal.

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

Ini adalah respons aset ilustratif, bukan respons terhadap permintaan kemampuan. Baca kemampuan yang dikembalikan untuk memeriksa model akun saat ini, max_audio_seconds, batas byte unggahan/MIME dan batas tugas sebelum menyiapkan file.

Alur kerja generasi

1. Ambil kemampuan dan unggah gambar atau video ditambah audio mengemudi.
2. Konfirmasikan setiap unggahan langsung dan tunggu hingga kedua aset menjadi ready.
3. Buat penawaran harga menggunakan ID aset dan mode pembuatan. Tinjau total_points dan expires_at.
4. Kirimkan penawaran tersebut dengan kunci idempotensi yang stabil. Ini menerima tugas dan memegang penghargaan.
5. Lakukan polling ID pekerjaan yang dikembalikan menggunakan poll_after_seconds, atau terima webhook.
6. Setelah selesai, unduh dari URL yang telah ditandatangani. Tugas yang gagal mengembalikan penangguhan aslinya.

Membuat aset dan kuotasi tidak menghabiskan kredit atau menciptakan pekerjaan video. Sekali suatu generasi telah diterima, maka generasi tersebut tidak dapat dibatalkan. Hanya kegagalan pemrosesan yang mengembalikan kredit; batas waktu klien bukanlah bukti bahwa tugas tersebut gagal.

Unggah file lokal atau impor URL

Untuk file lokal, POST /assets mengembalikan PUT URL yang ditandatangani. Kirim byte file mentah dengan upload.headers yang dikembalikan, tanpa API Key Anda. Kemudian panggil POST /assets/{id}/confirm dengan {} dan polling GET /assets/{id}. awaiting_upload dan processing belum siap; failed adalah terminalnya. Gunakan saran polling server.

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

size_bytes harus berupa jumlah byte sebenarnya, bukan nomor contoh ini. Input gambar, video dan audio memiliki MIME dan batas ukuran yang berbeda; gunakan GET /capabilities sebagai sumber kebenaran. Ekstensi file saja tidak menentukan validitas.

Anda juga dapat mengimpor HTTPS URL yang dapat dijangkau secara publik. Ini tidak sinkron: lakukan polling pada aset yang dikembalikan hingga siap. Jalur lokal, file:// URL, URL jaringan pribadi, atau URL yang memerlukan cookie situs web Anda bukanlah sumber yang dapat digunakan. Jika menggunakan sumber bertanda URL, berikan waktu yang cukup untuk diambil.

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"

Rute ketiga adalah POST /asset-upload-sessions dengan {"kind":"image"}: kembalikan browser_upload_url ke pengguna, simpan asset_id, dan jajak pendapat setelah mereka mengunggahnya di browser. Ini berguna untuk klien yang tidak dapat membaca file lokal. Tiket unggahan dan URL yang ditandatangani adalah kredensial sementara; jangan mempublikasikannya dalam log atau transkrip obrolan.

Contoh kode lengkap

Pilih cURL, Python atau JavaScript di bawah. Setiap contoh melakukan alur kerja unggah → kutipan → kirim → jajak pendapat → unduh yang sama, cetak kutipan dan tanyakan sebelum membelanjakan kredit. Contoh-contoh panjang diciutkan; tombol Salin selalu menyalin program lengkap.

• cURL: Bash, cURL, jq dan Python 3 (untuk UUID). Simpan sebagai skrip Bash dan jalankan.
• Python: Python 3 dengan pustaka requests; instal menggunakan python -m pip install requests.
• JavaScript: Node.js 20+ dan modul bawaan saja. Simpan sebagai quickstart.mjs dan jalankan node quickstart.mjs.

Ekspor variabel lingkungan di atas dan tempatkan face.jpg dan speech.mp3 di direktori kerja. Jalankan di server atau mesin pengembangan Anda, bukan di halaman web publik. Permintaan unggah/unduh yang ditandatangani tidak pernah menyertakan API Key Anda. Skrip berhenti pada kesalahan HTTP; periksa aturan pemulihan di bawah ini sebelum mencoba lagi, daripada memulai ulang pengiriman yang mungkin diterima dengan kunci baru.

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

Model, opsi, dan kredit

Semua mode memerlukan aset audio mengemudi yang diunggah. Text-to-speech, kloning suara, dan pembatalan bukan merupakan parameter API ini. Image Super / Motion Control memerlukan Starter atau Pro; membeli kredit saja tidak memungkinkannya. Periksa kemampuan untuk mengetahui ketersediaan model dan batas durasi, termasuk pengecualian khusus model.

Durasi audio yang telah diverifikasi dibulatkan ke atas ke detik penuh, dengan minimum 5 detik. Estimasi untuk 5 detik membutuhkan 5 kredit pada Image Fast, 10 pada Image Max, dan 15 pada Image Super atau Music Video. Membuat estimasi tidak memotong saldo. Pengiriman tugas mencadangkan jumlah dalam estimasi; keberhasilan menghabiskan jumlah yang sama, sedangkan kegagalan pemrosesan mengembalikannya. Tidak ada penyesuaian harga setelah pembuatan. Kredit yang dibeli terpisah dari keanggotaan, tidak kedaluwarsa, dan tidak dapat dikembalikan sebagai uang tunai.

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

Untuk Music Video, gunakan mode: "music_video" dan pengaturan MV di bawah. version menerima 1.0 atau 1.1; ratio menerima 21:9, 16:9, 4:3, 1:1, 3:4 atau 9:16; resolution menerima 480p atau 720p. Defaultnya adalah 1.0, 16:9 dan 480p. Periksa kemampuan skema langsung. Jangan lampirkan opsi gerakan ke mode lain atau kirimkan alias model web internal.

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

Referensi titik akhir

Jalur di bawah ini relatif terhadap /api/v1. Semua panggilan bisnis memerlukan otentikasi.

Daftar default untuk item 20, maksimum 50. Lulus data.next_cursor tidak berubah untuk mengambil halaman berikutnya. Untuk beberapa pekerjaan aktif, gunakan ids yang dipisahkan koma dalam satu permintaan daftar alih-alih melakukan polling secara terpisah. Daftar ini ditujukan untuk pekerjaan kredit API/MCP, bukan daftar umum pekerjaan situs web lama Anda.

Idempotensi, kesalahan dan batas kecepatan

Gunakan Idempotency-Key baru untuk setiap operasi penulisan yang berbeda, dan pertahankan kunci dan payload yang sama saat mencoba kembali operasi tersebut. Kuncinya adalah karakter ASCII 8–128 yang terlihat. Permintaan pengguna baru memerlukan kunci baru; percobaan ulang tidak. Contoh mencetak pasangan kutipan/kunci sebelum diserahkan. Dalam produksi, pertahankan pasangan tersebut sebelum mengirim dan pertahankan ID pekerjaan yang dikembalikan. Jangan memulai ulang seluruh contoh setelah penyerahan yang tidak pasti: hal itu akan membuat kunci baru.

Harga habis masa berlakunya dalam 10 menit. Penolakan yang pasti sebelum penerimaan memungkinkan Anda memperbaiki permintaan atau mendapatkan penawaran baru; respons yang tidak pasti memerlukan pemulihan upaya awal terlebih dahulu. Memutar ulang tugas yang diterima akan mengembalikan pekerjaan aslinya tanpa debit kedua. Kutipan tidak dapat digunakan dua kali dengan kunci yang berbeda.

REST dan MCP berbagi bucket baca/tambahan per akun: Free 30, Starter 30, Pro 60 permintaan per menit. Panggilan tambahan mencakup unggahan, konfirmasi, dan penawaran harga. Hormati poll_after_seconds dan Retry-After, mana saja yang memerlukan waktu tunggu lebih lama. Pembacaan status situs web dikelola secara terpisah; frekuensi pembuatan dan kapasitas eksekusi video dibagikan ke seluruh situs web, REST dan MCP. Situs web dan API/MCP masing-masing memiliki tunjangan tugas yang belum selesai secara independen: Free 1, Starter 3, Pro 10 per kumpulan. REST dan MCP berbagi kumpulan API/MCP, termasuk semua kunci dan koneksi OAuth; kredensial tambahan tidak pernah melipatgandakannya. Lihat mengapa menggunakan API/MCP untuk contoh alur kerja.

Hasil dan webhook opsional

Pekerjaan memiliki status queued, processing, completed, atau failed. Simpan ID pekerjaan saat lamaran Anda habis; batas waktu Anda tidak membatalkan tugas server. Jika berhasil, gunakan output.download_url selagi valid. Ambil kembali pekerjaan atau unduh titik akhir untuk mendapatkan tautan yang diperbarui selagi pekerjaan dipertahankan; unduhan berulang tidak menghabiskan kredit. Retensi mengikuti retensi kerja normal akun Anda, bukan periode terpisah khusus API. Output adalah kualitas asli, tanpa tanda air, dan dapat digunakan secara komersial sesuai dengan hak sumber dan persyaratan Anda.

Untuk integrasi server, buat titik akhir webhook di konsol Agent → Lanjutan, lalu teruskan ID-nya sebagai webhook_endpoint_id saat pengiriman. Titik akhir Anda harus terlebih dahulu menjawab endpoint.verification POST dengan tantangan sebagai isi respons teks biasa. Penyiapan ini menggunakan konsol situs web, bukan API manajemen kredensial publik.

Peristiwa webhook berisi event_id, event_type, occurred_at, generation_id, dan data. Tautan unduhan dihilangkan dari muatan webhook; menanyakan pekerjaan untuk mendapatkan tautan baru. Verifikasi FLS-Webhook-Signature terhadap isi permintaan mentah: HMAC-SHA256 dari timestamp + "." + body, menggunakan rahasia titik akhir Anda, dengan stempel waktu dari FLS-Webhook-Timestamp; cocokkan tanda tangan v1= dalam waktu yang konstan dan terapkan stempel waktu terkini untuk menolak pemutaran ulang. Hapus duplikat sebesar event_id / FLS-Webhook-Id dan segera kembalikan 2xx. Pemberitahuan duplikat tidak boleh memicu generasi berikutnya atau tindakan bisnis kedua. Pertahankan polling sebagai integrasi pertama yang paling sederhana.

Perlu bekerja melalui asisten, bukan HTTP? Siapkan MCP dengan agen Anda, atau kembali ke konsol Agent.