بدء الاستخدام السريع لواجهة برمجة تطبيقات التحكم في الحركة Kling V3.0

يتيح لك التحكم في الحركة من Kling V3.0 تحريك صورة شخصية ثابتة عن طريق استخراج الحركة من فيديو مرجعي وتطبيقها إطارًا بإطار. يحافظ المخرج على مظهر الشخصية من صورتك مع إعادة إنتاج الحركة من الفيديو — وهي تقنية تُسمى نقل الحركة. يغطي هذا الدليل نقطة نهاية Novita AI، والمدخلات المطلوبة، والمعلمات الرئيسية، وأمثلة عملية بلغة Python وcurl يمكنك تشغيلها مقابل مفتاح API حقيقي.

متى يكون التحكم في الحركة الأداة المناسبة

التحكم في الحركة هو الأداة المناسبة عندما يكون لديك شيئان: صورة شخصية ثابتة تريد تحريكها، وفيديو مرجعي تريد إعادة إنتاج حركته. يختلف هذا عن تحويل الصورة إلى فيديو (I2V)، الذي يولد الحركة من وصف نصي. باستخدام التحكم في الحركة، يتم نسخ الحركة من الفيديو المرجعي بدقة — ستتبع الشخصية في المخرج نفس مسار الحركة للشخص في الفيديو المرجعي.

استخدمه عندما:

• تريد رقصة معينة، أو دورة مشي، أو إيماءة مطبقة على رسم توضيحي أو صورة شخصية
• تحتاج إلى حركة متسقة وقابلة للتكرار عبر شخصيات مختلفة (نفس الفيديو المرجعي، صور مختلفة)
• تقوم ببناء محتوى حيث تكون جودة الحركة مهمة ونتائج I2V المفتوحة غير متوقعة للغاية

لا تستخدمه عندما تكون الحركة نفسها لا تزال غير محددة — في هذه الحالة، يمنحك I2V مع وصف نصي مرونة أكبر بتكلفة أقل.

الخطوة 1: الحصول على مفتاح API من Novita

سجّل في novita.ai وأنشئ مفتاح API من لوحة التحكم. تتلقى الحسابات الجديدة أرصدة مجانية يمكنك استخدامها لاختبار التحكم في الحركة قبل الالتزام بحجم الإنتاج.

الخطوة 2: تأكيد نقطة النهاية ومعرف النموذج

يستخدم التحكم في الحركة Kling V3.0 على Novita AI نمط الفيديو غير المتزامن القياسي:

إرسال المهمة:

POST https://api.novita.ai/v3/async/kling-v3.0-motion-control

استقصاء النتيجة:

GET https://api.novita.ai/v3/async/task-result?task_id={task_id}

جميع الطلبات تتطلب:

Authorization: Bearer YOUR_NOVITA_API_KEY
Content-Type: application/json

التوثيق الكامل: novita.ai/docs/api-reference/model-apis-kling-v3.0-motion-control

الخطوة 3: تحضير المدخلات الخاصة بك

يتطلب التحكم في الحركة مدخلين: صورة مرجعية وفيديو مرجعي. الحصول على هذه المدخلات بشكل صحيح هو أكبر عامل في جودة المخرج.

الصورة المرجعية

هذه هي الشخصية التي سيحافظ المخرج على مظهرها. المتطلبات:

• التنسيقات: JPEG, PNG, JPG
• الحجم الأقصى: 10 MB
• الحد الأدنى للدقة: 340 بكسل لكل جانب
• نسبة العرض إلى الارتفاع: بين 2:5 و5:2
• يجب أن تكون الشخصية مرئية بوضوح، وتشغل أكثر من 5% من مساحة الصورة، وليس بها حجب كثيف (لا تقطع الرأس أو الجسد)

للحصول على أفضل النتائج، استخدم صورة حيث تتطابق نسب جسم الشخصية تقريبًا مع ما هو مرئي في الفيديو المرجعي. إذا كان الفيديو المرجعي يظهر راقصًا كامل الجسد، فاستخدم صورة شخصية كاملة الجسد بدلاً من قص وجه.

الفيديو المرجعي

هذا هو مصدر الحركة. ستكرر الشخصية في المخرج الحركات من هذا الفيديو:

• التنسيقات: MP4, MOV
• الحجم الأقصى: 10 MB
• المدة: 3–30 ثانية
• الحد الأدنى للدقة: 340 بكسل لكل جانب
• نسبة العرض إلى الارتفاع: بين 2:5 و5:2
• يجب أن يكون الشخص في الفيديو المرجعي مرئيًا بالكامل أو الجزء العلوي من الجسد دون عوائق، بما في ذلك الرأس

اللقطات الواضحة والمضاءة جيدًا مع خلفية قليلة الفوضى تنقل الحركة بدقة أكبر من اللقطات المزعجة أو المزدحمة.

الخطوة 4: إرسال طلبك الأول

طلب curl بسيط:

curl --request POST \
  --url https://api.novita.ai/v3/async/kling-v3.0-motion-control \
  --header 'Authorization: Bearer $NOVITA_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "image": "https://example.com/character.jpg",
    "video": "https://example.com/reference_motion.mp4",
    "prompt": "شخص يؤدي رقصة سلسة، إضاءة سينمائية",
    "model_name": "kling-v3.0-motion-control",
    "character_orientation": "video"
  }'

يعيد الاستجابة task_id فورًا:

{
  "task_id": "abc123xyz"
}

الخطوة 5: استقصاء النتيجة

التحكم في الحركة Kling V3.0 غير متزامن. أرسل المهمة، ثم استقصِ حتى تصبح الحالة succeed:

curl --request GET \
  --url 'https://api.novita.ai/v3/async/task-result?task_id=abc123xyz' \
  --header 'Authorization: Bearer $NOVITA_API_KEY'

عند الانتهاء، يحتوي الرد على مصفوفة videos مع رابط المخرج:

{
  "task": {
    "status": "succeed"
  },
  "videos": [
    {
      "video_url": "https://cdn.novita.ai/output/abc123xyz.mp4",
      "video_url_ttl": "3600"
    }
  ]
}

الوقت النموذجي للتوليد هو 30–120 ثانية حسب مدة الفيديو والوضع. استقصِ كل 5–10 ثوانٍ بدلاً من الضغط المستمر على نقطة النهاية.

مثال تكامل كامل بلغة Python

هذا البرنامج النصي يرسل مهمة تحكم في الحركة ويستقصي حتى تكتمل:

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai"

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit_motion_control(image: str, video: str, prompt: str = "") -> str:
    payload = {
        "image": image,
        "video": video,
        "prompt": prompt,
        "model_name": "kling-v3.0-motion-control",
        "character_orientation": "video",
    }
    resp = requests.post(f"{BASE_URL}/v3/async/kling-v3.0-motion-control", json=payload, headers=HEADERS)
    resp.raise_for_status()
    return resp.json()["task_id"]


def poll_result(task_id: str, timeout: int = 300) -> str:
    deadline = time.time() + timeout
    while time.time() < deadline:
        resp = requests.get(
            f"{BASE_URL}/v3/async/task-result",
            params={"task_id": task_id},
            headers=HEADERS,
        )
        resp.raise_for_status()
        data = resp.json()
        status = data.get("task", {}).get("status")
        if status == "succeed":
            return data["videos"][0]["video_url"]
        if status == "failed":
            raise RuntimeError(f"فشلت المهمة: {data}")
        time.sleep(8)
    raise TimeoutError(f"المهمة {task_id} لم تكتمل خلال {timeout} ثانية")


if __name__ == "__main__":
    image = "https://example.com/character.jpg"
    video = "https://example.com/reference_motion.mp4"

    print("جارٍ إرسال المهمة...")
    task_id = submit_motion_control(image, video, prompt="رقصة سلسة، إضاءة دافئة")
    print(f"معرف المهمة: {task_id}")

    print("جارٍ استقصاء النتيجة...")
    output_url = poll_result(task_id)
    print(f"فيديو المخرج: {output_url}")

مرجع معلمات API

المعلمة	النوع	إلزامي	الوصف
image	string	نعم	رابط صورة الشخصية المراد تحريكها. راجع متطلبات المدخلات أعلاه.
video	string	نعم	رابط الفيديو المرجعي الذي سيتم نقل حركته.
model_name	string	نعم	اضبط على kling-v3.0-motion-control.
prompt	string	لا	وصف نصي لنمط الحركة المطلوب أو سياق المشهد. اختياري لكن يمكنه تحسين جودة المخرج.
character_orientation	string	لا	يتحكم في محاذاة الوضعية ومدة المخرج. "video" يطابق اتجاه الفيديو المرجعي — أفضل للحركات المعقدة لكامل الجسد، يدعم حتى 30 ثانية. "image" يطابق اتجاه صورة الشخصية — أفضل للحركات المتعلقة بالكاميرا، ثابت عند 5 ثوان.

character_orientation عمليًا

إذا كان الفيديو المرجعي يظهر راقصًا مواجهًا للأمام وكانت صورتك الشخصية أيضًا مواجهة للأمام، فإن "video" سيعطي نقل حركة أفضل ويدعم حتى 30 ثانية. إذا كان الفيديو المرجعي يحتوي على كاميرا تتحرك حول الشخص وكانت صورتك عبارة عن صورة وجه بزاوية ثابتة، فإن "image" يميل إلى تقليل التشوه المنظوري غير المرغوب فيه — لكن لاحظ أنه يولد مقطعًا ثابتًا لمدة 5 ثوان.

المستوى القياسي مقابل الاحترافي: أي مستوى جودة تختار

يتوفر التحكم في الحركة Kling V3.0 بمستويين من الجودة:

القياسي يخرج بدقة 720p. إنه الخيار المناسب للتكرار، واختبار توافق الحركة، أو إنشاء مسودات قبل الالتزام بالنسخة النهائية.

الاحترافي يخرج بدقة 1080p مع دقة حركة محسنة واتساق شخصية أفضل. استخدم الاحترافي عندما:

• المخرج سيذهب إلى إنتاج نهائي (منشور اجتماعي، فيلم قصير، عرض منتج)
• التفاصيل الدقيقة في وجه الشخصية أو ملابسها مهمة
• تقوم بتوليد مقاطع أطول (10 ثوانٍ+) حيث يكون تدهور الجودة بمرور الوقت أكثر وضوحًا

معظم سير عمل التطوير، ابدأ بالقياسي لتأكيد توافق المدخلات وجودة الحركة، ثم انتقل إلى الاحترافي للمرور النهائي.

التسعير، المدة، وتقديرات التكلفة

تقوم Novita AI بفوترة التحكم في الحركة لكل ثانية من الفيديو المولد. المستويان القياسي والاحترافي لهما معدلات منفصلة لكل ثانية. للحصول على التسعير الحالي، تحقق من صفحة نموذج Novita AI.

حدود المدة:

• character_orientation: "video" — حتى 30 ثانية
• character_orientation: "image" — ثابت عند 5 ثوان

تتزايد التكلفة مع المدة لوضع "video". وضع "image" دائمًا يولد مقطعًا مدته 5 ثوان.

استكشاف الأخطاء الشائعة وإصلاحها

تفشل المهمة فورًا مع خطأ 422 أو خطأ في التحقق تحقق من أن كل من image و video هما روابط يمكن الوصول إليها علنًا (ليست خلف مصادقة أو رابط مؤقت منته صلاحيت). يجب أن يكوت خادم Novita قادرًا عى جلب كلا الملفين في وقت تنفيذ المهمة.

تبدو الحركة في المخرج خاطئة أو تتشوه الشخصية السب الأكثر شيوعًا هو عد تطابق اتجهاه الشخصية في الصورة مع اتجهاه الفيديو المرجعي. جرب تبديل character_orientation بين "video" و "image" لرى أيهما ينتج محاذاة أفضل.

تفقد الشخصية هويتها الوجهية في منتصف المقطع تأكد من أن الشخصية في الصورة المرجعية لها وجه وجسد واضحين وغير معوقين. للمقاطع الأطول، يحافظ المستوى الاحترافي على اتساق الشخصية بشكل أفضل من المستوى القياسي.

لا تنتقل حركة الفيديو المرجعي بشكل نظيف اللقطات المرجعية المزعجة أو المزدحمة تقلل من استخراج الحركة. استخدم لقطات حيث يكون المؤدي هو الموضوع الرئيسي على خلفية نظيفة بشكل معقول. تجنب اللقطات المحمولة باليد المهتزة إذا كان الهدف هو نقل حركة سلس.

حالة stuck (عالقة) في processing لأكثر م 3 دقائق تأخيرات الطابور العارضة تحدث. انتظر حتى 5 دقائق قبل معالجتها كعالقة. إذا ظلت عالقة، أرسل مهمة جددة — لا تعد استخدام task_id القديم.

ما يبنيه المطورون باستخدام Kling Motيon Control

ت حريك الشخصيات لأصو ل العبة: خذ رسما توضيحيا لشخصية وطب ق مقطع حركة مرجعيا (مش ي، ركض، هجوم) دون برامج تجهيز أو رس متحركة.

محتو ى اجتماعي بحركة متناسقة: طب ق نفس فيديو الرقص المرجعي عى صو ر متع ددة لشخصيات إنت ج سلسلة م مقاطع بت صميم حركة متطابق و لكن أشك ال مخلتفة.

التصو ير المس ب ق: اختبار كي ف يبدو تس لس ل حركة مح دد عى ت صميم شخصية قب ل الستثما ر في إنت اج رس متحركة كام ل.

عر ض منتج التجا رة الإلكترو نية: طب ق تغييرات طفيفة في الوضعية أو حركة الملابس على صور المنتج باستخدام فيديو مرجعي مختار بعناية يظهر حركة القماش.

ال أسئلة ال شائعة

ما ال فرق ب ين التحكم في الحركة و تحويل الصورة إلى فيديو عى Novita AI؟

تحويل الصورة إلى فيديو (I2V) يح رك صورة بنا ء عى وص ف نص — ت و ل د ال حركة بو اسطة النموذج م وصفك. التح كم في الحركة ينقل حركة مح ددة م فيديو مرجعي إلى الشخصية في صورتك. التحكم في الحركة يعطيك حركة د قيقة وقابلة للتكرار؛ I2V يعطيك مرونة إبداعية دون الحاجة إلى مقطع مرجعي.

هل يحتاج شخصية الفيديو المرجعي إلى مطابقة مظهر شخصية الصورة؟

لا. ي ستخدم الف يدو ال مرجعي لستخراج الحركة فقط — شخصية المخرج تأتي م الصورة، ل م الف يدو. ذلك ه و ال قدرة ال جوهرية: حركة من مصدر، مظهر من مصدر آخر. يجب أن تتطابق النسب تقريبيًا (صورة كاملة الجسد لفيديو كامل الجسد، صورة وجه لفيديو الجزء العلوي من الجسد) للحصول على أفضل جودة نقل.

هل يمكنني استخدا م أي فيديو متاح للعموم كمرجع؟

يمكنك استخدام أي فيديو يلبي متطلبات التنسيق والحجم. تنتقل الحركة بشكل أفضل من اللقطات حيث يكون الشخص مرئيًا بوضوح مع أقل إعاقة. المشاهد المعقدة متعددة الأشخاص أو اللقطات المحررة بشك كبير (قص، تكرير) يمكن أن تقلل من الدقة.

كم من الوقت يستغرق التوليد؟

عادة 30–120 ثانية حسب مدة المخرج وما إذا اخترت ال وضع القياسي أ م الاحترافي. استقصِ كل 8–10 ثوانٍ بدلاً من حلقة ضيقة.

مقالات موصى بها

• Kling 3.0 الآن على Novita AI: توليد فيديو بالذكاء الاصطناعي سينمائي على نطاق واسع
• بدء الاستخدام السريع لواجهة برمجة تطبيقات Kling V3.0 4K
• واجهة برمجة تطبيقاات Kling V2.5 Turbo على Novita AI