واجهة برمجة التطبيقات للمطورين

منصّة Lipsync API

أنشئ فيديوهات مزامنة الشفاه برمجياً عبر واجهة REST القوية

مفاتيح API

إدارة مفاتيح المصادقة الخاصة بك

إنشاء مفتاح API جديد

امنح المفتاح اسماً يسهل تذكره (اختياري)

يتطلب تسجيل الدخول

يرجى تسجيل الدخول لإنشاء مفاتيح API وإدارتها.

أسعار تناسبك

ابدأ بخطط مرنة وتنافسية

تسعير API

ادفع حسب الاستخدام

ملاحظة: أرصدة API وأرصدة المستخدم منفصلة وغير قابلة للاستبدال.

ملاحظات:

الحد الأدنى للاقتطاع: 5 ثوانٍ لكل عملية إنشاء

دقة 480p: رصيدَان لكل ثانية

دقة 720p: 4 أرصدة لكل ثانية

lipsync-image/video/multi بدقة 1080p: 6 أرصدة لكل ثانية، بحد أدنى 30 رصيدًا

lipsync-image/video/multi بدقة 2k: 7 أرصدة لكل ثانية، بحد أدنى 35 رصيدًا

lipsync-image/video/multi بدقة 4k: 8 أرصدة لكل ثانية، بحد أدنى 40 رصيدًا

talking-avatar: تكلف دقات 720p/1080p/2k/4k مقدار 4/6/8/9 أرصدة لكل ثانية صوتية بعد التقريب للأعلى

lipsync-video: إذا كان الفيديو أطول من الصوت سيتم اقتطاعه؛ وإذا كان الصوت أطول سيتم تمديده تلقائياً. الفوترة تعتمد على طول الصوت عند الاقتطاع وعلى طول الفيديو عند التمديد.

lipsync-image-multi: إذا كانت القيمة "meanwhile"، تُستخدم أطول مدة صوت؛ وإلا فتُستخدم مجموع مدة "left_audio" و"right_audio".

مثال 1:

صوت مدته 3 ثوانٍ بدقة 720p = 5 ث × 4 = 20 رصيداً

(تطبق حد الاقتطاع الأدنى)

مثال 2:

صوت مدته 10 ثوانٍ بدقة 480p = 10 × 2 = 20 رصيداً

المصادقة

أمّن طلبات API الخاصة بك

ضمِّن مفتاح API في ترويسة Authorization لجميع الطلبات:

Authorization: Bearer sk_XXXX_YYYY

نقاط النهاية المتاحة

نقاط نهاية RESTful

POST/api/v1/lipsync-video

استبدال الصوت في فيديو موجود مع الحفاظ على مزامنة الشفاه

POST/api/v1/lipsync-image

صورة + صوت → فيديو أفاتار لمتحدث واحد

POST/api/v1/talking-avatar

صورة + صوت + Prompt -> أفاتار متكلم مع تحكم في التعبير والحركة

POST/api/v1/lipsync-image-multi

صورة + صوتان → أفاتار لعدة متحدثين (حوار/محادثة)

GET/api/v1/jobs/{requestId}

استعلم عن حالة المهمة واسترجع النتيجة

نطاق API الحالي

المدخلات والخصوصية وتغطية النماذج وملاحظات الإنتاج

المدخلات تعتمد على URL

تقبل API العامة حاليًا روابط الوسائط داخل JSON. الرفع المباشر multipart ونقاط رفع الأصول غير متاحة بعد. الروابط الموقعة أو المؤقتة مدعومة ما دام بإمكان العمال ومزوّد التوليد جلبها أثناء تشغيل المهمة.

مخرجات API خاصة

يتم تخزين مهام API بظهور خاص. مفتاح Public في الويب لا ينطبق على طلبات API، ولا يوجد حاليًا معامل API لنشر نتيجة توليد.

اختيار النموذج

اختر سير العمل عبر endpoint: lipsync-image أو lipsync-video أو lipsync-image-multi. استخدم talking-avatar لنموذج الصورة مع التحكم في التعبير والحركة.

لا يوجد ملف OpenAPI بعد

هذه الصفحة هي مرجع API الحالي. لم يتم نشر مواصفة OpenAPI/Swagger قابلة للقراءة آليًا حتى الآن.

عناصر تحكم غير مدعومة

نسبة العرض إلى الارتفاع و guidance scale و audio guidance غير مكشوفة كمعاملات API لنقاط lip-sync الحالية.

مهام الدُفعات

أرسل طلب API واحدًا لكل عملية توليد. للدُفعات الإنتاجية الكبيرة، أبقِ روابط الإدخال صالحة حتى الاكتمال وتواصل مع الدعم قبل تشغيل تزامن عالٍ جدًا.

المعلمات التفصيلية

مواصفات كاملة لنقاط النهاية

تتشارك جميع نقاط النهاية بنيةً عامة: باراميتر webhook اختياري ومعلمات formState خاصة بكل نموذج.

POST /api/v1/lipsync-video

يستبدل الصوت في فيديو موجود مع الحفاظ على تزامن الشفاه

معلمات المستوى الأعلى:

webhookاختياري

عنوان URL لرد النداء (HTTPS). سنرسل النتيجة عبر POST عند الاكتمال.

formStateمطلوب

كائن يحتوي جميع معلمات الإنشاء (انظر أدناه).

معلمات formState:

videoمطلوب

عنوان URL عام للفيديو المصدر (MP4، MOV، إلخ)

audioمطلوب

عنوان URL عام للصوت (MP3، WAV، إلخ)

resolutionمطلوب

"360p" أو "480p" أو "720p" أو "1080p" أو "2k" أو "4k"

mask_imageاختياري

عنوان URL عام لصورة القناع (يقيّد منطقة مزامنة الشفاه)

promptاختياري

نص إرشادي للنمط

seedاختياري

بذرة عددية للتكرارية

سير عمل غير متزامن

اختر كيفية استلام النتائج

جميع استدعاءات API غير متزامنة. لديك خياران لاسترجاع النتائج:

لمهام 1080p و2k و4k، تُرجع استجابات webhook وpolling نتيجة الفيديو النهائية بعد رفع الدقة فقط.

الخيار 1: Webhook (مُوصى به)

وفّر عنوان URL للـ webhook في JSON. سنرسل النتيجة عبر POST عند اكتمال المهمة.

يجب أن تكون روابط Webhook روابط HTTPS عامة. إذا فشل التسليم، نعيد المحاولة حتى 5 مرات بتراجع أسي.

الفوائد:

لا حاجة للاستقصاء المتكرر
إشعار فوري عند الاكتمال
أكثر كفاءة للمهام طويلة الأمد (عادة 30–120 ثانية)

الخيار 2: الاستقصاء (Polling)

احذف webhook واستخدم requestId المُعاد لاستقصاء GET /api/v1/jobs/{requestId} كل 5–10 ثوانٍ حتى تصبح الحالة "completed".

يُستخدم عندما:

لا يمكنك تعريض نقطة نهاية webhook عامة
الاختبار أو تصحيح الأخطاء

مثال باستخدام Webhook:

POST /api/v1/lipsync-image
Authorization: Bearer sk_XXXX_YYYY
Content-Type: application/json

{
  "webhook": "https://your-app.example.com/webhooks/lipsync",
  "formState": {
    "image": "https://.../face.png",
    "audio": "https://.../voice.mp3",
    "resolution": "720p",
    "seed": 42
  }
}

// Immediate Response:
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "message": "Task submitted successfully. Use requestId to query job status."
}

// Later, when job completes, we POST to your webhook:
POST https://your-app.example.com/webhooks/lipsync
Content-Type: application/json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "lipsync-image",
  "status": "completed",
  "output": "https://.../result.mp4",
  "error": "",
  "executionTime": 12345,
  "timings": null
}

مثال طلب Talking Avatar:

POST /api/v1/talking-avatar
Authorization: Bearer sk_XXXX_YYYY
Content-Type: application/json

{
  "webhook": "https://your-app.example.com/webhooks/lipsync",
  "formState": {
    "image": "https://.../character.png",
    "audio": "https://.../speech.mp3",
    "prompt": "Warm presentation style, natural facial expression, subtle head motion",
    "resolution": "1080p"
  }
}

// Completed webhook or polling response:
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "talking-avatar",
  "status": "completed",
  "output": "https://.../result.mp4",
  "error": "",
  "executionTime": 12345,
  "timings": null
}

مثال بدون Webhook (Polling):

// Step 1: Submit job (no webhook parameter)
POST /api/v1/lipsync-image
Authorization: Bearer sk_XXXX_YYYY
Content-Type: application/json

{
  "formState": {
    "image": "https://.../face.png",
    "audio": "https://.../voice.mp3",
    "resolution": "720p"
  }
}

// Immediate Response:
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "message": "Task submitted successfully. Use requestId to query job status."
}

// Step 2: Poll for status (repeat every 5-10 seconds)
GET /api/v1/jobs/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer sk_XXXX_YYYY

// Response while processing:
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "lipsync-image",
  "status": "processing",
  "output": null,
  "error": "",
  "executionTime": null,
  "timings": null
}

// Response when completed:
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "lipsync-image",
  "status": "completed",
  "output": "https://.../result.mp4",
  "error": "",
  "executionTime": 12345,
  "timings": null
}

// Response if failed:
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "lipsync-image",
  "status": "failed",
  "output": null,
  "error": "Generation failed. Please try again later.",
  "executionTime": null,
  "timings": null
}

أمثلة كود كاملة

أمثلة تكامل جاهزة للاستخدام

01Node.js مع Webhook (مُوصى به)

import fetch from 'node-fetch';
import express from 'express';

const API_KEY = 'Bearer sk_XXXX_YYYY';
const BASE_URL = 'https://lipsync.studio/api/v1';

// Set up webhook server to receive results
const app = express();
app.use(express.json());

app.post('/webhooks/lipsync', (req, res) => {
  const { id, status, output, error, model } = req.body;
  
  console.log('Job update received.');
  console.log('Job ID:', id);
  console.log('Model:', model);
  console.log('Status:', status);
  if (status === 'completed') {
    console.log('Video URL:', output);
  } else if (status === 'failed') {
    console.error('Error:', error);
  }
  
  // TODO: Save output URL to your database, send notification, etc.
  
  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

// Submit job with webhook
async function submitJobWithWebhook() {
  const webhookUrl = 'https://your-public-domain.com/webhooks/lipsync';
  
  const res = await fetch(`${BASE_URL}/lipsync-image`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': API_KEY
    },
    body: JSON.stringify({
      webhook: webhookUrl,
      formState: {
        image: 'https://example.com/portrait.jpg',
        audio: 'https://example.com/speech.mp3',
        resolution: '720p'
      }
    })
  });
  
  const data = await res.json();
  console.log('Job submitted:', data.requestId);
  console.log('Waiting for webhook callback...');
  
  // You don't need to poll! The result will be POSTed to your webhook.
}

submitJobWithWebhook();