وثائق FreeLipSync API

قبل أن تبدأ

استخدم FreeLipSync REST API لإنشاء فيديوهات مزامنة الشفاه والصور الناطقة والفيديوهات الموسيقية من ملفاتك الصوتية. تحتاج إلى حساب مسجّل و API Key من لوحة Agent ورصيد API. يحصل كل حساب، بما في ذلك الحسابات الحالية، على 30 وحدة رصيد ترحيبية لمرة واحدة عند تحميل الرصيد لأول مرة في لوحة Agent أو إرسال طلب إنشاء صالح. يمكنك شراء رصيد إضافي؛ العضوية لا تشمل رصيد API دوريًا. تحدد العضوية النماذج المتاحة والمدة وحدود المهام المشتركة.

يستخدم هذا الدليل https://freelipsync.com/api/v1. عند الاختبار على staging، قم بتعيين FLS_BASE_URL على أصل تلك البيئة وقم بإنشاء مفتاحك في نفس البيئة. يجب تمكين الوصول إلى واجهة برمجة التطبيقات (API) عند هذا النشر. تستخدم الأمثلة speech.mp3 القصير وface.jpg ذو الوجه الواحد.

افتح مرجع OpenAPI للحصول على مخططات الطلب والاستجابة القابلة للقراءة آليًا. تفضل وكيل؟ راجع دليل الإعداد 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 الخاص بك. رمز الوصول OAuth الصادر لـ MCP صالح فقط لـ /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. قم بإرسال هذا عرض السعر باستخدام مفتاح Idempotency المستقر. هذا يقبل المهمة ويحمل وحدات الرصيد.
5. قم باستقصاء معرف المهمة الذي تم إرجاعه باستخدام poll_after_seconds، أو احصل على خطاف عبر الويب.
6. عند الانتهاء، قم بالتنزيل من ملف URL الموقع. تقوم المهمة الفاشلة بإرجاع المبلغ المحجوز الأصلي.

لا يؤدي إنشاء الأصول وعروض الأسعار إلى إنفاق وحدات الرصيد أو إنشاء مهام فيديو. بمجرد قبول إنشاء الفيديو، لا يمكن إلغاؤه. فشل المعالجة فقط هو الذي يعيد وحدات الرصيد؛ مهلة العميل ليست دليلاً على فشل المهمة.

تحميل الملفات المحلية أو استيراد عناوين URL

بالنسبة للملف المحلي، تقوم POST /assets بإرجاع PUT URL الموقع. أرسل بايتات الملف الخام باستخدام upload.headers الذي تم إرجاعه، بدون API Key. ثم اتصل بـ 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"

المسار الثالث هو POST /asset-upload-sessions مع {"kind":"image"}: قم بإرجاع browser_upload_url إلى المستخدم، واحتفظ بـ asset_id، وقم باستقصائه بعد تحميله في المتصفح. وهذا مفيد للعملاء الذين لا يستطيعون قراءة الملفات المحلية. تعد تذاكر التحميل وعناوين URL الموقعة بمثابة بيانات اعتماد مؤقتة؛ لا تنشرها في السجلات أو نصوص الدردشة.

أمثلة التعليمات البرمجية كاملة

اختر 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: منع تكرار الأثر، والأخطاء وحدود المعدل

استخدم Idempotency-Key جديدًا لكل عملية كتابة مميزة، واحتفظ بنفس المفتاح والحمولة عند إعادة محاولة تلك العملية. المفاتيح هي أحرف ASCII مرئية 8–128. يحتاج طلب المستخدم الجديد إلى مفتاح جديد؛ إعادة المحاولة لا. تطبع الأمثلة زوج عرض السعر/المفاتيح قبل الإرسال. في الإنتاج، استمر في هذا الزوج قبل إرسال معرف المهمة الذي تم إرجاعه واستمر في ذلك. لا تقم بإعادة تشغيل المثال بأكمله بعد إرسال غير مؤكد: فهذا من شأنه إنشاء مفتاح جديد.

تنتهي عروض الأسعار خلال دقائق 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 في تجمع API/MCP، بما في ذلك جميع المفاتيح واتصالات OAuth؛ أوراق الاعتماد الإضافية لا تضاعفها أبدًا. راجع لماذا نستخدم API/MCP للحصول على أمثلة سير العمل.

النتائج وخطافات الويب الاختيارية

المهام لها حالة queued أو processing أو completed أو failed. احتفظ بمعرف المهمة عند انتهاء مهلة طلبك؛ المهلة الخاصة بك لا تلغي مهمة الخادم. عند النجاح، استخدم output.download_url أثناء صلاحيته. قم بإعادة جلب المهمة أو تنزيل نقطة النهاية للحصول على رابط متجدد أثناء الاحتفاظ بالعمل؛ تكرار التنزيلات لا تنفق وحدات الرصيد. يتبع الاحتفاظ الاحتفاظ بالعمل العادي لحسابك، وليس فترة منفصلة لواجهة برمجة التطبيقات فقط. المخرجات ذات جودة أصلية، بدون علامة مائية، وقابلة للاستخدام تجاريًا وفقًا لحقوق المصدر والشروط الخاصة بك.

بالنسبة لعمليات تكامل الخادم، قم بإنشاء نقطة نهاية خطاف الويب في وحدة التحكم Agent → Advanced، ثم قم بتمرير معرفها كـ webhook_endpoint_id عند الإرسال. يجب أن تجيب نقطة النهاية الخاصة بك أولاً على endpoint.verification POST مع التحدي كنص استجابة بنص عادي. يستخدم هذا الإعداد وحدة تحكم موقع الويب، وليس واجهة برمجة التطبيقات العامة لإدارة بيانات الاعتماد.

تحتوي أحداث Webhook على event_id وevent_type وoccurred_at وgeneration_id وdata. يتم حذف روابط التنزيل من حمولات الويب هوك؛ الاستعلام عن المهمة للحصول على رابط جديد. تحقق من FLS-Webhook-Signature مقابل نص الطلب الأولي: HMAC-SHA256 لـ timestamp + "." + body، باستخدام سر نقطة النهاية الخاصة بك، مع الطابع الزمني من FLS-Webhook-Timestamp؛ مطابقة توقيع v1= في وقت ثابت وفرض طابع زمني حديث لرفض عمليات الإعادة. قم بإلغاء التكرار بواسطة event_id / FLS-Webhook-Id وإرجاع 2xx على الفور. يجب ألا تؤدي الإشعارات المكررة إلى تشغيل عملية إنشاء أخرى أو إجراء تجاري ثانٍ. استمر في الاستعلام الدوري عن الحالة باعتباره أبسط تكامل أولي.

هل تحتاج إلى العمل من خلال مساعد بدلاً من HTTP؟ قم بإعداد MCP مع وكيلك، أو ارجع إلى وحدة التحكم Agent.