واجهة API و SDK لتحرير الفيديو بالذكاء الاصطناعي: أتمتة المونتاج داخل تطبيقك

لا يحتاج معظم تحرير الفيديو إلى شخص يعمل على خط الزمن. تبديل الخلفية في 200 مقطع منتج، وتحويل ملخص مكتوب إلى خمسة مقاطع عمودية، وقص كل ملف مرفوع إلى 15 ثانية: هذه مهام مناسبة للكود. تتيح واجهة API لتحرير الفيديو بالذكاء الاصطناعي لتطبيقك إرسال هذا العمل كطلبات HTTP وجمع المقاطع الجاهزة، كما أن SDK، حتى لو كان صغيرًا تكتبه بنفسك، يُبقي هذه الاستدعاءات منظمة. يعرض هذا المقال ما يمكن أن تقدمه هذه الواجهة اليوم، وكيف تعمل واجهة PicassoIA للمطورين، وكيف تربط التعديلات التوليدية بخطوات FFmpeg بسيطة في خط إنتاج آلي واحد للفيديو. وحيثما تكون الميزة متاحة فقط في تطبيق الويب، يوضح النص ذلك.

ما الذي تفعله واجهة API للتحرير فعليًا

قبل كتابة أي كود، افصل كلمة "تحرير" إلى مهمتين، لأنهما تحتاجان إلى أدوات مختلفة.

التعديلات التوليدية مقابل تعديلات خط الزمن

تعديلات خط الزمن حتمية. قص عند 1.0 ثانية، ادمج مقطعين، أضف الترجمات المدمجة، غيّر الحجم إلى 9:16: المدخل نفسه يعطي المخرج نفسه دائمًا، ويُنفَّذ ذلك بواسطة FFmpeg على خادمك. أما التعديلات التوليدية فاحتمالية. يعيد النموذج رسم البكسلات انطلاقًا من أمر نصي، فقد تبدو عبارة "اجعل الأريكة من الجلد البنفسجي" أو "حرّك هذه الصورة" مختلفة قليلًا في كل تشغيل ما لم تثبّت قيمة البذرة.

خط الإنتاج يحتاج غالبًا إلى النوعين معًا. هذا هو توزيع المهام الشائعة:

أين يناسب SDK

SDK هو الطبقة التي تُبعد HTTP الخام عن منطق عملك. فهو يرفق الرمز المميز، وينشئ المهام، ويستعلم عن النتائج، ويعيد المحاولة عند الإخفاقات المناسبة، ويلغي المهام العالقة، ويحدّ من عدد المهام التي تعمل في وقت واحد. ولأن مهام الفيديو غير متزامنة (الإنشاء، ثم الانتظار، ثم الجلب)، فإن معظم الكود المربك يقع في هذا الانتظار. تقدّم صفحة API أمثلة بلغات Python و Node و cURL. وهذا يكفي لبناء عميل خفيف خاص بك، وهذا تحديدًا ما تفعله الأقسام اللاحقة.

ما الذي تكشفه PicassoIA اليوم

تقع واجهة API للمطورين على https://api.picassoia.com/v1. تُصادَق الطلبات باستخدام رمز Bearer الذي يبدأ بالنص pia_sk_، وتنشئه من صفحة API في picassoia.com (يمكن للحساب الواحد أن يحمل رمزين كحد أقصى). وأسلوب العمل على طريقة Replicate: إنشاء تنبؤ، ثم الاستعلام عنه، ثم قراءة النتيجة.

أربعة نماذج خلف API

💡 خطّط على أساس هذا التقسيم. حتى أكتوبر 2026، تعمل نماذج تحرير الفيديو الموجودة في الكتالوج، مثل P Video Edit، وAleph 2، وLucy Edit 2، في تطبيق الويب، لا عبر API. استخدم API للتوليد وإعادة التصيير، واستخدم تطبيق الويب للتعديلات القائمة على الأمر النصي على اللقطات الموجودة.

حدود يجب التخطيط حولها

• 5 تنبؤات متزامنة لكل حساب، مشتركة بين كل الرموز المميزة واتصالات MCP.
• 10 ميغابايت لجسم الطلب. أرسل روابط الصور والفيديو، ولا ترسل ملفات base64 أبدًا.
• 4,000 حرف لكل أمر نصي.
• 3 ساعات قبل أن ينتهي وقت التنبؤ.

💡 تتغيّر قواعد الوصول ومتطلبات الخطط، لذا تحقّق منها في صفحة API قبل أن تعد فريقك بخارطة طريق.

أرسل طلبك الأول

تقرأ كل الاستدعاءات أدناه متغير بيئة واحدًا، PICASSOIA_TOKEN، حتى لا يظهر الرمز المميز في كود المصدر أبدًا.

إنشاء مهمة باستخدام cURL

curl -X POST https://api.picassoia.com/v1/models/picassoia/picassoia-video/predictions \
  -H "Authorization: Bearer $PICASSOIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "prompt": "Slow push-in on a ceramic mug of coffee on a sunlit desk, steam rising, soft room tone",
      "image": "https://example.com/first-frame.jpg",
      "resolution": "720p"
    }
  }'

نسخ الأمر النصي

يعيد الرد تنبؤًا بالمعرّف id وstatus. يتبع كائن input مخطط النموذج. بالنسبة إلى PicassoIA Video يعني ذلك حقلًا إلزاميًا هو prompt، وحقولًا اختيارية هي image، وresolution (480p أو 720p، والافتراضي 720p)، وaspect_ratio، وseed وsave_audio. عند تمرير صورة، تصبح الإطار الافتتاحي ويرث المقطع نسبة عرضها إلى ارتفاعها. كل مقطع مدته 5 ثوانٍ بمعدل 24 إطارًا في الثانية مع صوت متزامن، ما لم تُطفئ save_audio.

الاستعلام حتى يصبح المقطع جاهزًا

المهام غير متزامنة، لذلك فالاستجابة الأولى إيصال استلام وليست فيديو. استعلم عن التنبؤ كل بضع ثوانٍ باستخدام GET /v1/predictions/{id} حتى تُظهر الحالة أنه نجح أو فشل، ثم اقرأ عنوان URL للمخرجات. تستغرق أمثلة التشغيل في صفحات النماذج عادةً ما بين 30 ثانية و2 دقيقة، لذا يكفي فاصل استعلام من 3 إلى 5 ثوانٍ. وإذا لم تعد تهتم بمهمة ما، فاستدعِ نقطة نهاية الإلغاء حتى لا تشغل إحدى فتحاتك الخمس.

بناء غلاف SDK صغير

غلاف في أقل من 40 سطرًا

غلّف الاستدعاءات التي تحتاجها في وحدة واحدة. يؤدي هذا الإصدار بلغة Node (الإصدار 18 أو أحدث، لذا fetch مدمج فيه) المهمة:

const BASE = "https://api.picassoia.com/v1";
const headers = {
  Authorization: `Bearer ${process.env.PICASSOIA_TOKEN}`,
  "Content-Type": "application/json",
};

export async function createPrediction(model, input) {
  const res = await fetch(`${BASE}/models/${model}/predictions`, {
    method: "POST",
    headers,
    body: JSON.stringify({ input }),
  });
  if (!res.ok) throw new Error(`Create failed: ${res.status} ${await res.text()}`);
  return res.json();
}

export async function waitFor(id, { everyMs = 4000, timeoutMs = 10 * 60_000 } = {}) {
  const started = Date.now();
  while (Date.now() - started < timeoutMs) {
    const res = await fetch(`${BASE}/predictions/${id}`, { headers });
    const prediction = await res.json();
    if (prediction.status === "succeeded") return prediction;
    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${id} ${prediction.status}`);
    }
    await new Promise((r) => setTimeout(r, everyMs));
  }
  await fetch(`${BASE}/predictions/${id}/cancel`, { method: "POST", headers });
  throw new Error(`Prediction ${id} timed out`);
}

نسخ الأمر النصي

ثلاث عادات تحافظ على سلامة الأمر في بيئة الإنتاج. أعد المحاولة فقط لما يمكن أن ينجح في المحاولة الثانية: تُمنح انقطاعات الشبكة واستجابات 5xx محاولتين أو ثلاث محاولات مع تأخيرات متزايدة، أما أخطاء 4xx مثل المدخلات غير الصالحة أو الرمز غير الصالح فلا، لأن تكرارها لا يغيّر شيئًا. اضبط دائمًا مهلة زمنية وألغِ المهمة عند انتهائها، كما يفعل الكود أعلاه، حتى لا تشغل مهمة عالقة فتحة أبدًا. سجّل معرّف التنبؤ بجانب معرّف مهمتك، لأنه أول ما ستحتاج إليه عندما يبدو شيء خاطئًا. تحقق من حقول الاستجابة الدقيقة في وثائق API قبل الإطلاق.

ابقَ دون خمس مهام في الوقت نفسه

الحد الأقصى للحساب هو خمسة تنبؤات متزامنة، مشتركة بين الرموز المميزة واتصالات MCP. دفعة من 40 مقطعًا تُرسل مرة واحدة باستخدام Promise.all ستصل إلى الحد فورًا. ضع مجموعة صغيرة أمام الغلاف واجعل حجمها 4، حتى تبقى خانة واحدة متاحة للاختبارات اليدوية أو لأداة أخرى على الحساب نفسه:

export function pool(limit = 4) {
  let active = 0;
  const queue = [];
  const next = () => {
    if (active >= limit || queue.length === 0) return;
    active++;
    const { task, resolve, reject } = queue.shift();
    task().then(resolve, reject).finally(() => { active--; next(); });
  };
  return (task) => new Promise((resolve, reject) => { queue.push({ task, resolve, reject }); next(); });
}

const run = pool(4);
const clips = await Promise.all(
  shots.map((shot) => run(async () => {
    const job = await createPrediction("picassoia/picassoia-video", shot);
    return waitFor(job.id);
  }))
);

نسخ الأمر النصي

أتمتة التعديلات داخل تطبيقك

مع وجود الغلاف، يصبح التعديل الآلي سلسلة قصيرة من الخطوات:

1. خطة: يحوّل نموذج لغوي كبير (LLM) الملخص إلى قائمة تعديلات بصيغة JSON.
2. الصور الثابتة: توليد الصور أو تحريرها عبر API.
3. اللقطات: تصيير مقاطع جديدة من تلك الصور الثابتة.
4. عمل خط الزمن: القص والدمج والترجمة باستخدام FFmpeg.
5. المراجعة والتسليم: تحقّق من كل ملف، ثم انشره.

الأنماط الثلاثة التالية تملأ الجزء الوسط من هذه السلسلة.

حرّر الإطار الأول ثم حرّكه

لا تستطيع API أن تأخذ لقطاتك المصوّرة وتطبّق عليها تعديلًا نصيًا، لكنها تقترب من ذلك. استخرج إطارًا من المقطع المصدر، وعدّل تلك الصورة الثابتة باستخدام PicassoIA Image Editor Pro، ثم صيّر لقطة جديدة تبدأ من الإطار المعدّل باستخدام PicassoIA Video أو Seedance 2.5 Lite.

1. استخرج إطارًا: ffmpeg -ss 2 -i source.mp4 -frames:v 1 frame.jpg
2. ارفعه إلى التخزين ليصبح له رابط عام.
3. أرسله في المصفوفة images واذكره بعبارة "الصورة 1" في الأمر النصي. يقبل المحرر حتى ثلاث صور مرجعية، وتعود أمثلة التحرير على صفحته خلال ثانية إلى ثانيتين تقريبًا، لذا يمكنك رفض التعديل السيئ قبل أن تدفع تكلفة توليد الفيديو.
4. مرّر الصورة المعدّلة بوصفها image إلى نموذج فيديو مع أمر نصي للحركة.

const edit = await waitFor((await createPrediction("picassoia/picassoia-image-editor-pro", {
  prompt: "Change the sofa in image 1 to light purple leather. Keep everything else unchanged.",
  images: [frameUrl],
})).id);
const firstFrame = Array.isArray(edit.output) ? edit.output[0] : edit.output;

const clip = await waitFor((await createPrediction("picassoia/picassoia-video", {
  prompt: "Slow push-in toward the sofa, soft window light, a hand places a cushion.",
  image: firstFrame,
  resolution: "720p",
})).id);

نسخ الأمر النصي

هذا يعيد توليد اللقطة بدلًا من تحرير بكسلات المصدر الأصلية، لذا ستختلف الحركة عن لقطاتك الأصلية. تعامل معه كوسيلة لإنتاج تنويعة، لا كتعديل مطابق للإطار بدقة. كما يقبل Seedance 2.5 Lite حقل last_frame_image ومدة 10 ثوانٍ، وهذا يفيد عندما يجب أن تنتهي اللقطة عند إطار محدد.

دع نموذجًا لغويًا يكتب خطة التعديل

كتابة كل تعديل يدويًا داخل الكود لا تتوسع. اجعل نموذجًا لغويًا يحوّل ملخصًا بلغة عادية إلى قائمة تعديلات بصيغة JSON، ثم دع كودك ينفذ هذه القائمة. يُصمَّم GPT 5 Structured لإعادة JSON نظيف، وClaude Sonnet 5 وGemini 3.5 Flash شريكان جيدان في صياغة الخطط عند اختبارها يدويًا في تطبيق الويب. في الإنتاج، استدعِ أي مزوّد نموذج لغوي يستخدمه تطبيقك أصلًا.

{
  "shots": [
    { "source": "clip_01.mp4", "start": 1.0, "end": 4.5, "caption": "New arrivals" },
    { "generate": "Slow dolly toward a sunlit storefront, shallow depth of field", "seconds": 5 }
  ]
}

نسخ الأمر النصي

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

القص والدمج والترجمة باستخدام FFmpeg

تبقى خطوات خط الزمن حتمية ومنخفضة التكلفة. شغّلها من Node باستخدام child_process أو من أي مشغّل مهام:

# trim 3.5 seconds starting at 1.0
ffmpeg -ss 1.0 -t 3.5 -i clip_01.mp4 -c:v libx264 -c:a aac trimmed.mp4

# merge the clips listed in list.txt (same codec, size and frame rate)
ffmpeg -f concat -safe 0 -i list.txt -c copy merged.mp4

# burn captions from an SRT file
ffmpeg -i merged.mp4 -vf subtitles=captions.srt -c:a copy final.mp4

نسخ الأمر النصي

الدمج باستخدام -c copy يعمل فقط عندما تشترك كل المقاطع في الترميز نفسه والحجم نفسه ومعدل الإطارات نفسه. تخرج المقاطع من PicassoIA Video كلها بمدة 5 ثوانٍ و24 إطارًا في الثانية، لكن إن خلطتها مع لقطات الهاتف فأعد ترميز الكل وفق مواصفة واحدة أولًا. يقدّم تطبيق الويب المهام نفسها يدويًا عبر Trim Video وVideo Merge وAutocaption.

استخدم P Video Edit على PicassoIA

عندما تحتاج إلى تعديل قائم على أمر نصي على لقطات صوّرتها بالفعل، فالأداة هي P Video Edit. تعمل في تطبيق PicassoIA على الويب، وتقبل مقطعًا بطول يصل إلى 15 ثانية. تغيّر الفيديو بمتابعة تعليمة نصية بسيطة، لذلك لا يحتاج طلب مثل "غيّر السماء إلى غروب الشمس" أو "اجعل السترة حمراء" إلى خط زمن.

خطوة بخطوة في تطبيق الويب

1. افتح صفحة P Video Edit وارفع مقطعك (15 ثانية كحد أقصى).
2. اكتب تعليمة واحدة، مثلًا: Change the material of the sofa to light purple leather. Do not change anything else.
3. اختياري: أرفق حتى أربع صور مرجعية (jpg أو jpeg أو png أو webp) عندما يجب أن يتطابق لون أو ملمس أو كائن تمامًا.
4. فعّل Draft لمعاينة أسرع وأقل جودة قبل التصيير النهائي.
5. أبقِ Prompt Upsampling مفعّلًا للتعليمات القصيرة. أوقفه عندما يكون أمرك النصي دقيقًا أصلًا.
6. أبقِ Save Audio مفعّلًا حتى تبقى المقاطع الصوتية الأصلية متزامنة.
7. شغّل التعديل، وراجع النتيجة، وعدّل الأمر النصي، ثم أعد التشغيل. اضبط قيمة البذرة إذا أردت تكرار النتيجة بالضبط.

استغرقت أمثلة التشغيل على صفحة النموذج نحو دقيقة إلى دقيقتين لكل تشغيل.

أوامر نصية تحافظ على المشهد

سمِّ ما يجب أن يتغير، ثم سمِّ ما يجب ألا يتغير. يتبع أحد أمثلة الأوامر النصية على صفحة النموذج هذا النمط: غيّر لون هيكل SUV إلى الأصفر فقط. وينتهي بعبارة أبقِ البيئة والإضاءة وحركة الكاميرا دون تغيير. التزم بتغيير واحد في كل تشغيل، ثم اربط عدة تشغيلات إذا احتجت إلى المزيد.

يضم الكتالوج محررات أخرى تستحق تجربة على المقطع نفسه:

التكاليف والإخفاقات وضوابط الحماية

خطّط للإخفاقات والتكلفة

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

افحص المدخلات قبل التوليد

إذا كان المستخدمون يستطيعون كتابة أوامر نصية أو رفع صور، فافحصها أولًا. Llama Guard 4 12B نموذج لإدارة المحتوى يمكنك تجربته في تطبيق الويب، وتنطبق الفكرة نفسها على أي خدمة إشراف تستخدمها منصتك. أضف أيضًا حدًا لمعدل الطلبات لكل مستخدم، حتى لا يستطيع عميل واحد أن يأخذ الخانات الخمس كلها.

جرّب تعديلك الخاص اليوم

أسرع طريقة لرؤية خط الإنتاج هي تشغيل أجزائه يدويًا. افتح PicassoIA، واصنع صورة ثابتة باستخدام PicassoIA Image، وغيّر تفصيلة واحدة باستخدام PicassoIA Image Editor Pro، ثم حرّك النتيجة باستخدام PicassoIA Video. بضع دقائق من التجارب ستُظهر لك الأوامر النصية التي تصمد قبل أن تكتب سطرًا واحدًا من كود الدمج. شغّل جولة ثانية على الصورة الثابتة نفسها باستخدام Seedance 2.5 Lite وقارن الحركة.

عندما تبدو النتائج صحيحة، اربط الخطوات نفسها بتطبيقك باستخدام الغلاف من هذا المقال. تصفح كل النماذج، بما فيها محررات الفيديو، على picassoia.com/en/all-models، وأنشئ صورك الخاصة اليوم.