Kling 4.0

الإمكانيات

الأسعار والأرصدة

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

يوضح الجدول أدناه النقاط المحتسبة لكل ثانية، وليس التكلفة الإجمالية للمهمة. تعتمد التعريفة على النموذج المستخدم، ودقة الفيديو الناتج، وما إذا كان قد تم إدخال مقاطع فيديو مرجعية في وضع "المرجع إلى فيديو" (reference-to-video). يرجى الاطلاع على المعادلات والأمثلة الموضحة أسفل الجدول لمعرفة كيفية حساب التكلفة الإجمالية.

• بدون إدخال فيديو: ثواني المخرجات × سعر عدم وجود فيديو.
• عند إدخال فيديو، تمثّل T إجمالي مدة مقاطع الفيديو المرجعية بالثواني كما يقيسها الخادم. يُقرّب إجمالي الأرصدة النهائي إلى العدد الصحيح الأعلى. ceil((duration + max(duration, T)) × rate)
• تطبق مراجع الصور أو الصوت وحدها سعر عدم وجود فيديو. لا يطبق سعر فوترة الفيديو المرجعي إلا في وضع مرجع إلى فيديو عند توفير مراجع فيديو.

تُحجز الأرصدة عند تقديم الطلب وتُخصم عند النجاح. تدخل المهام الفاشلة أو التي انتهت مهلتها في مسار استرداد الأموال. تعني حالة الفوترة refund_failed أن عملية الاسترداد لم تكتمل؛ يرجى مراجعة سجلات الـ API أو الاتصال بالدعم.

المصادقة

أنشئ مفتاح API في لوحة التحكم. يظهر المفتاح الكامل مرة واحدة فقط. احتفظ به في خادمك وأرسله كرمز حامل (Bearer token) مع كل طلب.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

قم بتعيين متغير البيئة SEEVIO_API_KEY قبل تشغيل هذه الأمثلة. يتم تشغيل أمثلة JavaScript على خادمك باستخدام Node.js؛ وتستخدم أمثلة Python حزمة requests.

البدء السريع

أرسل هذا الطلب البسيط، واحفظ الـ taskId المسترجع، ثم استخدم مثال الاستعلام عن المهمة أدناه. قيمة الرصيد في استجابة الإنشاء تمثل المبلغ المحجوز.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling-4-0",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video"
  }
}'

مثال على استجابة إنشاء المهمة

بعد قبول الطلب أعلاه، ترجع واجهة برمجة التطبيقات (API) استجابة JSON هذه. يمثل taskId معرف المهمة المستخدم في عمليات الاستعلام اللاحقة عن الحالة؛ بينما يمثل credits عدد النقاط المحجوزة لهذه المهمة. تؤكد هذه الاستجابة إنشاء المهمة بنجاح، ولا تعني أن الفيديو جاهز بعد. يتعين عليك تتبع حالة المهمة بشكل دوري (Poll) أو استخدام Webhook لتلقي نتائج الفيديو.

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 65
}

إنشاء مهمة

أرسل كائن JSON يحتوي على model وinput، بالإضافة إلى callback_url اختياري. حدد دائمًا معرف النموذج (model ID) المعروض في هذه الصفحة؛ وفي حال حذفه، سيتم تحديد seedance-2-0 تلقائيًا.

جسم الطلب (Request body)

معلمات الإدخال

استجابة الإنشاء

تعيد استجابة HTTP 200 المعرف taskId (نص) والرصيد credits (رقم). هذا تأكيد على إنشاء المهمة وليس اكتمالها. القيمة أدناه تتوافق مع البدء السريع لـ 5 ثوانٍ بدقة 720p.

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 65
}

أوضاع التوليد وأمثلة

نص إلى فيديو

التوليد من وصف نصي. لا يتم تمرير عناوين URL للوسائط في هذا الوضع.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling-4-0",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video"
  }
}'

الإطار الأول

قدم صورة واحدة كإطار أول، ثم صف الحركة المطلوبة في الوصف الخاص بك.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling-4-0",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "image-to-video",
    "image_urls": [
      "https://example.com/first.jpg"
    ]
  }
}'

الإطاران الأول والأخير

عند الإنشاء من صورة أرسل الإطار الأول ثم الأخير إن رغبت. يقبل وضع المراجع حتى 10 صور.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling-4-0",
  "input": {
    "prompt": "",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "image-to-video",
    "image_urls": [
      "https://example.com/first.jpg",
      "https://example.com/last.jpg"
    ]
  }
}'

مثال على الإطارات الرئيسية: تفتّح وردة

أنشئ مقطعًا بتقنية التصوير المتسارع مدته 8 ثوانٍ باستخدام أربع صور التُقطت من الزاوية نفسها. ضع في image_urls صورة البرعم المغلق أولًا والوردة المتفتحة بالكامل ثانيًا لتحديد إطاري البداية والنهاية. وفي keyframe_urls ضع صورة البتلات التي بدأت تتفتح ثم صورة الوردة نصف المتفتحة. ينتقل الفيديو من البرعم عبر هاتين المرحلتين إلى التفتح الكامل. يحدّد ترتيب المصفوفة تسلسل الصور ويختار النموذج توقيت ظهورها.

استبدل عناوين URL الخاصة بالوسائط في example.com بملفات HTTPS الخاصة بك والمتاحة للعامة. عناوين URL التجريبية مخصصة لتوضيح هيكلية الطلب وليست أصولاً صالحة للتنزيل.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling-4-0",
  "input": {
    "prompt": "A time-lapse of a rose opening. Keep the camera still and the light soft as the petals unfold.",
    "duration": 8,
    "resolution": "720p",
    "generation_type": "image-to-video",
    "image_urls": [
      "https://example.com/rose-bud.jpg",
      "https://example.com/rose-full-bloom.jpg"
    ],
    "keyframe_urls": [
      "https://example.com/rose-opening.jpg",
      "https://example.com/rose-half-open.jpg"
    ]
  }
}'

مرجع متعدد الوسائط

دمج مراجع الصور، الفيديو والصوت معًا. يظل الوصف النصي مطلوبًا. يؤدي إدخال الفيديو المرجعي إلى تغيير معادلة الفوترة.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling-4-0",
  "input": {
    "prompt": "Animate @Image1 with the movement of @Video1 and ambience from @Audio1.",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "reference-to-video",
    "image_urls": [
      "https://example.com/character.jpg"
    ],
    "video_urls": [
      "https://example.com/motion.mp4"
    ],
    "audio_urls": [
      "https://example.com/surf.mp3"
    ],
    "keep_original_sound": false
  }
}'

الاستعلام عن مهمة

استبدل معرف المثال بـ taskId المسترجع من عملية الإنشاء. تعيد الاستعلامات فقط المهام المملوكة لمستخدم مفتاح API؛ وتعيد المعرفات غير المعروفة أو التي لا يمكن الوصول إليها خطأ HTTP 404.

استعلم كل 10–20 ثوانٍ كخطوة أولى، وتراجع مؤقتًا عند تلقي HTTP 429، وتوقف عندما تصبح الحالة completed أو failed. يُفضل استخدام خطاطيف الويب (webhooks) في بيئة الإنتاج. يقوم كل مثال كود أدناه باستعلام واحد.

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

مهمة مكتملة: استجابة الاستعلام مع نتائج الفيديو

عندما ترجع نتيجة الاستعلام status=completed، فهذا يعني أن عملية إنشاء الفيديو قد انتهت بنجاح. يمكنك قراءة روابط الفيديو من data.results وتنزيلها قبل حلول تاريخ data.video_expires_at. تشير القيمة billing_status=charged إلى أنه تم خصم الرصيد المحجوز بالفعل.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "kling-4-0",
  "is_draft": false,
  "draft_task_id": null,
  "status": "completed",
  "billing_status": "charged",
  "credits": 65,
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/videos/example.mp4"
    ],
    "video_expires_at": "2026-09-07T00:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

مهمة فاشلة: استجابة الاستعلام مع تفاصيل الفشل والفوترة

عندما ترجع نتيجة الاستعلام status=failed، فهذا يعني أن عملية الإنشاء قد انتهت دون نجاح. يمكنك قراءة سبب الفشل من failed_reason وحالة الفوترة من billing_status لمعرفة تفاصيل عملية الاسترداد. في هذا المثال، تعني refunded أنه تمت إعادة الرصيد المحجوز. يحتفظ الحقل credits بالقيمة الأصلية المحجوزة، ولا تتضمن الاستجابة أي بيانات في data.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "kling-4-0",
  "is_draft": false,
  "draft_task_id": null,
  "status": "failed",
  "billing_status": "refunded",
  "credits": 65,
  "failed_reason": "provider_failed"
}

خطاطيف الويب (Webhooks)

اضبط callback_url في طلب الإنشاء لتلقي طلب JSON POST عند اكتمال المهمة أو فشلها. يجب إرجاع استجابة بترميز 2xx في غضون 15 ثانية. تتم إعادة المحاولة للإرسال الفاشل؛ لذا يرجى معالجة الطلبات المتكررة بشكل متطابق (idempotently) باستخدام معرف المهمة.

يجب أن تدعم نقطة نهاية الاستدعاء الذاتي (Callback endpoint) استقبال طلبات من نوع POST مع نص طلب بتنسيق JSON ‏(Content-Type: application/json).

إنشاء مهمة مع تعيين خطاف الويب (callback)

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling-4-0",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video"
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

اكتملت المهمة: بيانات الاستدعاء الذاتي الناجح

عند نجاح عملية الإنشاء، ستحتوي استجابة الاستدعاء الذاتي على status=completed. استخدم المعرّف (id) لتحديد المهمة، وdata.results للحصول على روابط الفيديو. يُرجى تنزيل النتائج وحفظها قبل تاريخ صلاحية الفيديو الموضح في data.video_expires_at.

يشير created_at إلى وقت إنشاء الحدث، وtask_created_at إلى وقت إنشاء المهمة، بالثواني وفق Unix. تعرض الأمثلة الحقول الموصى بها؛ وقد تتضمن الاستجابات حقولاً إضافية.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652848,
  "model": "kling-4-0",
  "status": "completed",
  "task_created_at": 1788652800,
  "billing_status": "charged",
  "credits": 65,
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/videos/example.mp4"
    ],
    "video_expires_at": "2026-09-07T00:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

فشلت المهمة: بيانات استدعاء ذاتي غير ناجح

عند فشل عملية الإنشاء، ستحتوي استجابة الاستدعاء الذاتي على status=failed. استخدم المعرّف (id) لتحديد المهمة، وfailed_reason لمعرفة سبب الفشل، وcredits_refunded لمعرفة عدد الرصيد المسترد.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652848,
  "model": "kling-4-0",
  "status": "failed",
  "task_created_at": 1788652800,
  "billing_status": "refunded",
  "credits": 65,
  "failed_reason": "provider_failed",
  "credits_refunded": 65
}

مثال للمستقبل (Receiver)

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrls = callbackData.data.results;
    // Save the video URLs and mark this task as completed in your application.
    console.log(callbackData.id, videoUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

  return new Response(null, { status: 200 });
}

يقرأ نموذج Next.js هذا نص استجابة JSON للتعامل مع المهام المكتملة والفاشلة مباشرةً. يُرجى إضافة ميزة الحفظ الدائم وتجنب تكرار معرفات المهام (Task-ID) في تطبيقك، مع جدولة المهام البطيئة في قائمة انتظار قبل تأكيد الاستدعاء الذاتي.

متطلبات الوسائط والقيود

• يجب أن تكون جميع روابط الوسائط وخطاطيف الويب روابط HTTPS عامة. تجنب الاستضافة المحلية (localhost)، وعناوين IP الخاصة، والملفات التي تتطلب ملفات تعريف ارتباط (cookies) أو تسجيل دخول. يجب أن تؤدي روابط الفيديوهات/الصوتيات المرجعية إلى وسائط قابلة للقراءة مباشرة.
• يجب ألا يتجاوز حجم مقطع الفيديو الواحد 100 ميجابايت.
• يجب ألا يتجاوز حجم الملف الصوتي الواحد 15 ميجابايت.
• حتى 15 من الملفات المرجعية إجمالاً