FreeLipSync API दस्तावेज़

शुरू करने से पहले

अपने ऑडियो से लिप सिंक, बोलती तस्वीर और संगीत वीडियो बनाने के लिए FreeLipSync REST API इस्तेमाल करें। आपको एक पंजीकृत खाता, Agent कंसोल से API Key और API क्रेडिट चाहिए। पुराने उपयोगकर्ताओं सहित हर खाते को पहली बार Agent कंसोल में बैलेंस लोड होने या मान्य वीडियो निर्माण अनुरोध भेजने पर एक बार 30 स्वागत क्रेडिट मिलते हैं। इसके बाद अतिरिक्त क्रेडिट खरीदे जा सकते हैं; सदस्यता में नियमित API क्रेडिट नहीं मिलते। सदस्यता उपलब्ध मॉडल, अवधि और साझा कार्य सीमाएँ तय करती है।

यह गाइड https://freelipsync.com/api/v1 का उपयोग करता है। staging पर परीक्षण करते समय, FLS_BASE_URL को उस वातावरण के मूल पर सेट करें और उसी वातावरण में अपनी कुंजी बनाएं। उस परिनियोजन पर एपीआई एक्सेस सक्षम होना चाहिए। उदाहरण एक लघु speech.mp3 और एक एकल-चेहरा face.jpg का उपयोग करते हैं।

मशीन-पठनीय अनुरोध और प्रतिक्रिया स्कीमा के लिए ओपनएपीआई संदर्भ खोलें। एक एजेंट को प्राथमिकता दें? MCP सेटअप गाइड देखें।

प्रमाणीकरण और आपका पहला अनुरोध

Agent कंसोल में एक कुंजी बनाएं और इसे निर्माण संवाद से कॉपी करें। पूरा रहस्य एक बार दिखाया गया है. इसे किसी पर्यावरण चर में संग्रहीत करें, ब्राउज़र कोड या सार्वजनिक रिपॉजिटरी में नहीं। यदि खो जाए तो उसे रद्द करें और दूसरा बनाएं। सभी कुंजियाँ समान खाता शेष और सीमा का उपयोग करती हैं; दूसरी कुंजी बनाने से समवर्तीता नहीं बढ़ती है।

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 आपके API Key को स्वीकार करता है। MCP के लिए जारी किया गया OAuth एक्सेस टोकन केवल /mcp के लिए मान्य है, REST के लिए नहीं। एक सफल प्रतिक्रिया अपने परिणाम को data में लपेटती है और इसमें एक request_id शामिल होता है; त्रुटियों के स्थान पर error और request_id हैं। आईडी अपारदर्शी स्ट्रिंग हैं और क्रेडिट राशि दशमलव स्ट्रिंग हैं।

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

यह एक उदाहरणात्मक परिसंपत्ति प्रतिक्रिया है, क्षमताओं के अनुरोध की प्रतिक्रिया नहीं। फ़ाइलें तैयार करने से पहले चालू खाते के मॉडल, max_audio_seconds, अपलोड बाइट/MIME सीमा और कार्य सीमा की जांच करने के लिए लौटाई गई क्षमताओं को पढ़ें।

जनरेशन वर्कफ़्लो

1. क्षमताएं प्राप्त करें और एक छवि या वीडियो तथा ड्राइविंग ऑडियो अपलोड करें।
2. प्रत्येक प्रत्यक्ष अपलोड की पुष्टि करें और दोनों संपत्तियों के ready बनने तक प्रतीक्षा करें।
3. एसेट आईडी और जनरेशन मोड का उपयोग करके एक कोटेशन बनाएं। total_points और expires_at की समीक्षा करें।
4. उस उद्धरण को स्थिर आइडेम्पोटेंसी कुंजी के साथ सबमिट करें। यह कार्य को स्वीकार करता है और श्रेय रखता है।
5. poll_after_seconds का उपयोग करके लौटाई गई जॉब आईडी का सर्वेक्षण करें, या एक वेबहुक प्राप्त करें।
6. पूरा होने पर, हस्ताक्षरित URL से डाउनलोड करें। एक असफल कार्य अपनी मूल पकड़ वापस लौटा देता है।

संपत्ति और उद्धरण बनाने से क्रेडिट खर्च नहीं होता है या वीडियो कार्य नहीं बनती हैं। एक बार एक वीडियो निर्माण को स्वीकार कर लेने के बाद उसे रद्द नहीं किया जा सकता। केवल प्रोसेसिंग विफलता ही क्रेडिट लौटाती है; क्लाइंट टाइमआउट इस बात का प्रमाण नहीं है कि कार्य विफल हो गया।

स्थानीय फ़ाइलें अपलोड करें या URL आयात करें

स्थानीय फ़ाइल के लिए, POST /assets एक हस्ताक्षरित PUT URL लौटाता है। अपने API Key के बिना, लौटाए गए upload.headers के साथ कच्ची फ़ाइल बाइट्स भेजें। फिर {} के साथ POST /assets/{id}/confirm पर कॉल करें और GET /assets/{id} पोल करें। awaiting_upload और processing तैयार नहीं हैं; failed टर्मिनल है. सर्वर की नियमित स्थिति जाँच सलाह का उपयोग करें.

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

size_bytes वास्तविक बाइट गिनती होनी चाहिए, न कि यह उदाहरण संख्या। छवि, वीडियो और ऑडियो इनपुट की MIME और आकार सीमाएँ अलग-अलग हैं; सत्य के स्रोत के रूप में GET /capabilities का उपयोग करें। केवल फ़ाइल एक्सटेंशन ही वैधता निर्धारित नहीं करते.

आप सार्वजनिक रूप से पहुंच योग्य HTTPS URL भी आयात कर सकते हैं। यह अतुल्यकालिक है: तैयार होने तक लौटाई गई संपत्ति का सर्वेक्षण करें। आपकी वेबसाइट कुकीज़ की आवश्यकता वाला एक स्थानीय पथ, file:// URL, निजी-नेटवर्क URL या URL एक उपयोगी स्रोत नहीं है। यदि हस्ताक्षरित स्रोत URL का उपयोग कर रहे हैं, तो इसे लाने के लिए पर्याप्त समय दें।

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"

{"kind":"image"} के साथ तीसरा मार्ग POST /asset-upload-sessions है: उपयोगकर्ता को browser_upload_url लौटाएं, asset_id को बनाए रखें, और ब्राउज़र में अपलोड करने के बाद इसे पोल करें। यह उन ग्राहकों के लिए उपयोगी है जो स्थानीय फ़ाइलें नहीं पढ़ सकते। अपलोड टिकट और हस्ताक्षरित यूआरएल अस्थायी क्रेडेंशियल हैं; उन्हें लॉग या चैट ट्रांसक्रिप्ट में प्रकाशित न करें।

संपूर्ण कोड उदाहरण

नीचे cURL, Python या JavaScript चुनें। प्रत्येक उदाहरण समान अपलोड → उद्धरण → सबमिट → पोल → डाउनलोड वर्कफ़्लो करता है, उद्धरण प्रिंट करता है और क्रेडिट खर्च करने से पहले पूछता है। लंबे उदाहरण ध्वस्त हो गए हैं; कॉपी बटन हमेशा पूरे प्रोग्राम को कॉपी करता है।

• cURL: Bash, cURL, jq और Python 3 (UUID के लिए)। Bash स्क्रिप्ट के रूप में सहेजें और इसे चलाएँ।
• Python: Python 3 और requests लाइब्रेरी; python -m pip install requests से इंस्टॉल करें।
• JavaScript: Node.js 20+ और केवल अंतर्निर्मित मॉड्यूल। quickstart.mjs के रूप में सहेजें और node quickstart.mjs चलाएँ।

उपरोक्त पर्यावरण चर निर्यात करें और face.jpg और speech.mp3 को कार्यशील निर्देशिका में रखें। अपने सर्वर या डेवलपमेंट मशीन पर चलाएं, किसी सार्वजनिक वेब पेज पर नहीं। हस्ताक्षरित अपलोड/डाउनलोड अनुरोधों में कभी भी आपका API Key शामिल नहीं होता है। स्क्रिप्ट HTTP त्रुटियों पर रुकती हैं; संभवतः स्वीकृत सबमिशन को नई कुंजी के साथ पुनः आरंभ करने के बजाय पुनः प्रयास करने से पहले नीचे दिए गए पुनर्प्राप्ति नियमों की जांच करें।

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

मॉडल, विकल्प और क्रेडिट

सभी मोड के लिए अपलोड की गई ड्राइविंग ऑडियो संपत्ति की आवश्यकता होती है। टेक्स्ट-टू-स्पीच, वॉयस क्लोनिंग और कैंसिलेशन इस एपीआई के पैरामीटर नहीं हैं। Image Super / Motion Control के लिए Starter या Pro की आवश्यकता है; अकेले क्रेडिट खरीदने से यह संभव नहीं होता है। मॉडल-विशिष्ट अपवादों सहित मॉडल उपलब्धता और अवधि सीमा के लिए क्षमताओं की जांच करें।

सत्यापित ऑडियो अवधि को अगले पूरे सेकंड तक ऊपर की ओर पूर्णांकित किया जाता है; न्यूनतम बिल योग्य अवधि 5 सेकंड है। 5 सेकंड के कोटेशन में Image Fast के 5, Image Max के 10 और Image Super या Music Video के 15 क्रेडिट लगते हैं। कोटेशन बनाने से वॉलेट से क्रेडिट नहीं कटते। अनुरोध भेजने पर कोटेशन की राशि आरक्षित होती है; सफलता पर वही राशि खर्च होती है और प्रोसेसिंग विफल होने पर वापस मिलती है। वीडियो बनने के बाद कीमत नहीं बदलती। खरीदे गए क्रेडिट सदस्यता से अलग हैं, उनकी समय-सीमा नहीं है और उन्हें नकद वापस नहीं किया जाता।

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

Music Video के लिए, mode: "music_video" और नीचे दी गई MV सेटिंग्स का उपयोग करें। version 1.0 या 1.1 स्वीकार करता है; ratio 21:9, 16:9, 4:3, 1:1, 3:4 या 9:16 स्वीकार करता है; resolution 480p या 720p स्वीकार करता है। डिफ़ॉल्ट 1.0, 16:9 और 480p हैं। लाइव स्कीमा के लिए क्षमताओं की जाँच करें. मोशन विकल्पों को किसी अन्य मोड में संलग्न न करें या आंतरिक वेब मॉडल उपनाम न भेजें।

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

समापन बिंदु संदर्भ

नीचे दिए गए पथ /api/v1 से संबंधित हैं। सभी व्यावसायिक कॉलों के लिए प्रमाणीकरण की आवश्यकता होती है।

सूचियों में डिफ़ॉल्ट रूप से 20 और अधिकतम 50 आइटम आते हैं। अगला पृष्ठ पाने के लिए data.next_cursor को बिना बदले भेजें। कई सक्रिय कार्यों को अलग-अलग जाँचने के बजाय एक सूची अनुरोध में अल्पविराम से अलग ids भेजें। यह सूची API/MCP क्रेडिट वाले कार्यों की है, वेबसाइट के पुराने कार्यों की सामान्य सूची नहीं।

आइडेम्पोटेंसी, त्रुटियाँ और दर सीमाएँ

हर अलग लिखने वाले ऑपरेशन के लिए नई Idempotency-Key बनाएँ। उसी ऑपरेशन को दोबारा भेजते समय कुंजी और पेलोड वही रखें। कुंजी में 8–128 दिखाई देने वाले ASCII अक्षर होने चाहिए। नया उपयोगकर्ता अनुरोध नई कुंजी लेता है; रीट्राई नहीं। उदाहरण अनुरोध भेजने से पहले कोटेशन/कुंजी की जोड़ी दिखाते हैं। प्रोडक्शन में भेजने से पहले इस जोड़ी को स्थायी रूप से सहेजें और मिली जॉब ID भी सहेजें। अनिश्चित परिणाम के बाद पूरा उदाहरण फिर से शुरू न करें, क्योंकि उससे नई कुंजी बनेगी।

उद्धरण 10 मिनटों में समाप्त हो जाते हैं। स्वीकृति से पहले एक निश्चित अस्वीकृति आपको अनुरोध को सही करने या एक नया उद्धरण प्राप्त करने की सुविधा देती है; अनिश्चित प्रतिक्रिया के लिए पहले मूल प्रयास को पुनर्प्राप्त करने की आवश्यकता होती है। किसी स्वीकृत कार्य को दोबारा चलाने से उसका मूल कार्य बिना दूसरे डेबिट के वापस आ जाता है। एक कोटेशन को अलग-अलग कुंजियों के अंतर्गत दो बार खर्च नहीं किया जा सकता।

REST और MCP प्रति खाता रीड/सहायक बकेट साझा करते हैं: Free 30, Starter 30, Pro 60 अनुरोध प्रति मिनट। सहायक कॉल में अपलोड, पुष्टिकरण और उद्धरण शामिल हैं। poll_after_seconds और Retry-After का सम्मान करें, जिसके लिए अधिक प्रतीक्षा की आवश्यकता हो। वेबसाइट स्थिति पठन को अलग से प्रबंधित किया जाता है; वीडियो निर्माण की आवृत्ति और वीडियो निष्पादन क्षमता वेबसाइट, REST और MCP पर साझा की जाती है। वेबसाइट और API/MCP प्रत्येक के पास एक स्वतंत्र अधूरा-कार्य भत्ता है: Free 1, Starter 3, Pro 10 प्रति पूल। REST और MCP सभी कुंजियाँ और OAuth कनेक्शन सहित API/MCP पूल साझा करते हैं; अतिरिक्त क्रेडेंशियल इसे कभी नहीं बढ़ाते। वर्कफ़्लो उदाहरणों के लिए API/MCP का उपयोग क्यों करें देखें।

परिणाम और वैकल्पिक वेबहुक

कार्यों में queued, processing, completed या failed स्थिति है। जब आपके आवेदन का समय समाप्त हो जाए तो जॉब आईडी अपने पास रखें; आपका टाइमआउट सर्वर कार्य को रद्द नहीं करता है। सफल होने पर, वैध रहते हुए output.download_url का उपयोग करें। कार्य को पुनः प्राप्त करें या कार्य बरकरार रहने के दौरान नवीनीकृत लिंक प्राप्त करने के लिए एंडपॉइंट डाउनलोड करें; बार-बार डाउनलोड करने पर क्रेडिट खर्च नहीं होता। अवधारण आपके खाते के सामान्य कार्य प्रतिधारण का अनुसरण करता है, न कि एक अलग एपीआई-केवल अवधि का। आउटपुट मूल गुणवत्ता वाला है, वॉटरमार्क के बिना, और आपके स्रोत अधिकारों और शर्तों के अधीन व्यावसायिक रूप से उपयोग करने योग्य है।

सर्वर एकीकरण के लिए, Agent कंसोल → एडवांस्ड में एक वेबहुक एंडपॉइंट बनाएं, फिर सबमिट करने पर इसकी आईडी को webhook_endpoint_id के रूप में पास करें। आपके समापन बिंदु को पहले सादे-पाठ प्रतिक्रिया निकाय के रूप में चुनौती के साथ endpoint.verification POST का उत्तर देना होगा। यह सेटअप वेबसाइट कंसोल का उपयोग करता है, सार्वजनिक क्रेडेंशियल-प्रबंधन एपीआई का नहीं।

वेबहुक इवेंट में event_id, event_type, occurred_at, generation_id और data शामिल हैं। वेबहुक पेलोड से डाउनलोड लिंक हटा दिए गए हैं; नए लिंक के लिए कार्य के बारे में पूछें। रॉ रिक्वेस्ट बॉडी के विरुद्ध FLS-Webhook-Signature को सत्यापित करें: timestamp + "." + body के HMAC-SHA256, अपने एंडपॉइंट सीक्रेट का उपयोग करके, FLS-Webhook-Timestamp के टाइमस्टैम्प के साथ; निरंतर समय में v1= हस्ताक्षर का मिलान करें और रीप्ले को अस्वीकार करने के लिए हालिया टाइमस्टैम्प लागू करें। event_id / FLS-Webhook-Id द्वारा डुप्लिकेट हटाएँ और तुरंत 2xx वापस करें। डुप्लिकेट सूचनाओं को दूसरी वीडियो निर्माण या दूसरी व्यावसायिक कार्रवाई को ट्रिगर नहीं करना चाहिए। नियमित स्थिति जाँच को सबसे सरल प्रथम एकीकरण के रूप में रखें।

HTTP के बजाय किसी सहायक के माध्यम से काम करने की आवश्यकता है? अपने एजेंट के साथ MCP सेट करें, या Agent कंसोल पर वापस लौटें।