API RapidVideoMaker
تتيح REST API معالجة ملفات الفيديو من أي عميل HTTP — سكريبتات Python، سير عمل n8n، أدوات الطرف الثالث. خمسة أوضاع متاحة: دمج الفيديوهات (عدة MP4)، تحرير الصوت (MP4 + MP3)، إنشاء فيديو (JPG/PNG + MP3)، تراكب الفيديو (2 MP4 صورة داخل صورة). المعالجة غير متزامنة: أرسل الملفات ثم استعلم عن النتيجة.
احصل على رمز API مجاناً
أنشئ حساباً للحصول على رمز API — 20 طلباً يومياً قابلة للاستخدام من الواجهة أو API.
سير العمل الكامل
كل تكامل يتبع نفس التسلسل المكون من 4 خطوات:
1
إنشاء مهمة —
POST /api/v1/render.phpأرسل ملفاتك بصيغة
multipart/form-data مع رمز Bearer. صورة JPG/PNG + ملف MP3 + mode=image_to_video → إنشاء فيديو. ملف MP4 + ملف MP3 → تحرير صوتي. عدة ملفات MP4 → دمج. يعيد الخادم job_id فريداً.2
انتظار المهمة —
GET /api/v1/jobs.php?job_id=…استعلم عن هذه النقطة بانتظام (كل 5-10 ثوانٍ). تمر المهمة بـ
queued → processing → ready (أو error).3
الحصول على رابط التنزيل
عندما تصبح الحالة
ready، يحتوي الرد على حقل download_url جاهز للاستخدام.4
تنزيل الملف —
GET /api/download.php?job_id=…قم بتنزيل ملف MP4 النهائي. الملف متاح لمدة ساعتين بعد اكتمال المهمة، ثم يُحذف تلقائياً.
المصادقة
يجب أن يتضمن كل طلب رمز API الخاص بك. يُقبل نوعان من الصيغ:
# المصادقة — يجب أن يتضمن كل طلب رمز API الخاص بك. يُقبل نوعان من الصيغ:
Authorization: Bearer rvm_your_token_here
# Alternative
X-API-Key: rvm_your_token_here
رمزك متاح في منطقة الأعضاء — رمز واحد لكل حساب، يُنشأ تلقائياً عند التسجيل.
الحصة
لكل حساب عضو 20 طلباً يومياً مشتركة بين واجهة الويب وAPI. المهام الفاشلة لا تستهلك الحصة. يُعاد ضبط العداد عند منتصف الليل UTC.
تتضمن ردود POST حقلَي quota_used وquota_remaining. عند تجاوز الحد، يرد الخادم بـ 429.
الواجهة + API = عداد واحد. مقطع فيديو أُنشئ من الواجهة وطلب API يستهلكان كل منهما نقطة واحدة من الحصة اليومية ذاتها.
قائمة الانتظار
تُعالج مهمة واحدة في كل مرة. إذا أُرسلت عدة مهام في آنٍ واحد، تُضاف إلى قائمة انتظار وتُعالج بالترتيب. أثناء الانتظار، يتضمن رد الحالة:
queue_position— موقع المهمة في قائمة الانتظار (1 = التالية للمعالجة)queue_total— إجمالي المهام المنتظرةeta_minutes— الوقت التقديري قبل بدء المعالجة
يُطبَّق حد المعدل: تقبل نقطة
/api/v1/jobs.php حداً أقصى 12 طلباً في الدقيقة لكل رمز. التوصية: 10 ثوانٍ بين كل طلب. الانتقالات المتاحة
مرر transition_type=none (الافتراضي) للدمج المباشر، أو أحد الأنواع التالية للتلاشي بين المقاطع:
none
fade
fadeblack
dissolve
wipeleft
wiperight
slideleft
slideright
zoomin
circleclose
المدة (transition_duration) بين 0.2 و2.0 ثانية.
نقاط النهاية
POST
/api/v1/render.php
ينشئ مهمة معالجة فيديو
خمسة أوضاع، يمكن الوصول إليها عبر حقل mode (احذف mode مع عدة MP4 لاكتشاف fusion تلقائياً):
| الاستخدام | نمط API | الملفات المطلوبة | الوصف |
|---|---|---|---|
| دمج مقاطع الفيديو | fusion |
2-20 ملف MP4 | تُجمَّع المقاطع من البداية إلى النهاية بالترتيب المقدم. انتقالات اختيارية بين المقاطع. |
| تحرير الصوت | add_audio أو mix_audio |
ملف MP4 + ملف MP3 | يستبدل أو يُثري المسار الصوتي للفيديو. لا يُعاد ترميز مسار الفيديو أبداً.add_audio — يُحذف الصوت الأصلي ويُستبدل كلياً بملف MP3.mix_audio — يُحتفظ بالصوت الأصلي ويُضاف MP3 فوقه. |
| إنشاء فيديو | image_to_video |
صورة JPG/PNG + ملف MP3 | ينشئ فيديو من صورة ثابتة وملف صوتي. يمكن تكوين تراكب النص والتلاشي والدقة وfps عبر حقل options. |
| تراكب الفيديو | overlay_video |
2 MP4 | يضع فيديو ثانياً فوق الفيديو الرئيسي. الموضع والحجم والشفافية والصوت قابلة للضبط عبر حقل options. |
| نص إلى MP3 | text_to_mp3 |
(نص فقط) | يحوّل النص إلى كلام ويُعيد ملف MP3. لا حاجة لرفع ملفات — أرسل mode=text_to_mp3 وtext وlang كحقول نموذج. يدعم جميع لغات الموقع العشرين. |
تحقق صارم: كل نمط يتطلب عدداً وأنواعاً محددة من الملفات.
add_audio وmix_audio يقبلان ملف MP4 واحد + ملف MP3 واحد فقط. image_to_video يقبل صورة JPG/PNG واحدة + ملف MP3 واحد فقط.قاعدة المدة: في أنماط الصوت وimage_to_video، مدة النتيجة مقفلة على مدة MP3.
المعاملات المشتركة (multipart/form-data)
| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
| videos[] | File[] | نعم | الملفات المراد معالجتها. حسب النمط: 2-20 ملف MP4، أو ملف MP4 + ملف MP3، أو صورة (JPG/PNG) + ملف MP3. الحد الأقصى 500 ميجابايت لكل ملف. |
| mode | string | * | image_to_video | add_audio | mix_audio. مطلوب لهذه الأنماط الثلاثة. يُتجاهل فقط إذا كانت جميع الملفات MP4 (fusion). |
| order | JSON | نمط fusion فقط — مصفوفة JSON من الفهارس التي تحدد ترتيب المقاطع. | |
| transition_type | string | نمط fusion فقط. الافتراضي: none. | |
| transition_duration | float | نمط fusion فقط. المدة 0.2-2.0 ثانية. الافتراضي: 0.5. | |
| options | JSON | نمط image_to_video فقط — كائن JSON لمعاملات التصيير. | |
| callback_url | string | رابط عام (http/https) يُستدعى عند اكتمال المهمة. يتضمن الرد webhook_secret. |
معاملات options — نمط image_to_video
جميعها اختيارية. القيم غير المحددة → تُطبَّق الافتراضيات من طرف العامل.
| المفتاح | النوع | الافتراضي | الوصف |
|---|---|---|---|
| text | string | "" | النص المعروض كتراكب. فارغ = بلا نص. حد أقصى 500 حرف. |
| font_size | int | 60 | حجم الخط بالبكسل. النطاق: 10-300. |
| text_color | string | "white" | لون النص (مثلاً: white، yellow، #ffffff). |
| text_position | string | "center" | موضع النص: center، top، bottom. |
| box | bool | true | خلفية شبه شفافة خلف النص. |
| box_color | string | "black@0.4" | اللون + الشفافية بصيغة FFmpeg: color@opacity. |
| fade_duration | float | 0.5 | مدة التلاشي الداخل/الخارج بالثوانٍ (0-2). 0 = بلا تأثير. |
| width | int | 1080 | عرض الفيديو بالبكسل (64-3840، يُجبر على عدد زوجي). |
| height | int | 1920 | ارتفاع الفيديو بالبكسل (64-3840، يُجبر على عدد زوجي). |
| fps | int | 24 | معدل الإطارات (1-60). |
| image_fit | string | "contain" | نمط التأطير: contain = الصورة الكاملة مرئية؛ cover = تكبير لملء الإطار كاملاً. |
| bg_color | string | "black" | لون الخلفية إذا لم تملأ الصورة الدقة المستهدفة. |
| enable_image_motion | bool | false | تفعيل حركة الصورة. إذا كانت false، تبقى الصورة ثابتة. |
| image_motion_effect | string | "ken_burns" | تأثير الحركة. القيم المقبولة: zoom_in، zoom_out، pan_left_to_right، ken_burns، إلخ. |
| motion_intensity | float | 1.0 | شدة حركة الصورة (0.25-2.0). تضاعف سعة التكبير وسرعة الانتقال. |
| text_effect | string | "none" | تأثير حركة النص. القيم المقبولة: none، fade_in، slide_up، bounce. |
| text_effect_intensity | float | 1.0 | شدة حركة النص (0.25-2.0). تُتجاهل إذا كان text_effect هو none. |
| text_border_width | int | 0 | سمك الحدود السوداء حول الأحرف بالبكسل (0 = معطل). |
| text_mode | string | "static" | وضع ظهور النص. static (افتراضي): النص كاملاً مرئي من الإطار الأول. word_by_word: تظهر الكلمات واحدة تلو الأخرى بالسرعة المحددة في word_reveal_speed. لا يجمع مع text_effect: عند text_mode=word_by_word يُتجاهل text_effect. |
| word_reveal_speed | float | 1.5 | سرعة الكشف بالكلمات في الثانية (0.3–5.0، الافتراضي 1.5). تُستخدم فقط مع text_mode=word_by_word. القيمة الموصى بها للمزامنة مع OpenAI TTS: 2.0. |
| word_anim | string | "none" | حركة ظهور كل كلمة. none (افتراضي): ظهور فوري. fade: تظهر كل كلمة جديدة بتلاشٍ خلال 0.2 ثانية مع انتقال تدريجي. يُستخدم فقط مع text_mode=word_by_word. |
معاملات options — وضع overlay_video
جميعها اختيارية. ترتيب الرفع مهم: الملف الأول هو الفيديو الرئيسي (الخلفية)، الملف الثاني هو التراكب (المقدمة). استخدم chroma_key لإزالة الخلفية الخضراء من التراكب.
| المفتاح | النوع | الافتراضي | الوصف |
|---|---|---|---|
| position | string | "bottom-right" | الركن الذي يوضع فيه التراكب: top-left، top-right، bottom-left، bottom-right، أو center. |
| scale | float | 0.30 | حجم التراكب كنسبة من عرض الفيديو الرئيسي. 0.25 = 25% من العرض. النطاق: 0.05–1.0. |
| opacity | float | 1.0 | شفافية التراكب. 1.0 = معتم تماماً، 0.0 = غير مرئي. |
| margin | int | 10 | المسافة بالبكسل بين التراكب وحافة الإطار. يُتجاهل عند position=center. النطاق: 0–200. |
| audio | string | "main" | المسار الصوتي المراد الاحتفاظ به. main: صوت الفيديو الرئيسي فقط. overlay: صوت التراكب فقط. mix: مزج المسارين. |
| chroma_key | bool | false | اضبط على true لإزالة الخلفية الخضراء (#00FF00) من التراكب — مفيد لكاميرا الويب أو الرسوم المصورة على شاشة خضراء. |
| chroma_similarity | float | 0.20 | تسامح الكروما كي. منخفض = مطابقة صارمة. مرتفع = إزالة أوسع. موصى به: 0.10–0.20 للأخضر الرقمي، 0.25–0.45 للشاشة الفعلية. النطاق: 0.01–0.60. |
معاملات options — تحرير الصوت (mix_audio)
متاح فقط مع mode=mix_audio. يُتجاهل لـ add_audio.
| المفتاح | النوع | الافتراضي | الوصف |
|---|---|---|---|
| mp3_volume | float | 1.0 | مستوى صوت MP3 المُضاف (0.0 = صامت، 1.0 = الصوت الأصلي، 2.0 = ضعفان). |
رد ناجح (HTTP 200)
{
"success": true,
"job_id": "a3f1c8d2e5b09471...",
"mode": "fusion", // "fusion" | "add_audio" | "mix_audio" | "image_to_video" | "overlay_video"
"file_count": 2,
"transition": null,
"quota_used": 1,
"quota_remaining": 9,
"status_url": "https://rapidvideomaker.com/api/v1/jobs.php?job_id=a3f1c8..."
}
مثال curl — نمط image_to_video
curl -X POST https://rapidvideomaker.com/api/v1/render.php \
-H "Authorization: Bearer rvm_your_token" \
-F "videos[]=@scene.jpg" \
-F "videos[]=@narration.mp3" \
-F "mode=image_to_video" \
-F 'options={"text":"Chapter 1","font_size":72,"text_color":"white","text_position":"bottom","box":true,"box_color":"black@0.4","fade_duration":0.5,"width":1080,"height":1920,"image_fit":"contain","bg_color":"black","enable_image_motion":true,"image_motion_effect":"ken_burns","motion_intensity":1.0,"text_effect":"slide_up","text_effect_intensity":1.0}'
# image_fit : "contain" | "cover"
# bg_color : ignored if image_fit="cover"
# enable_image_motion : true = animation on, false (default) = static image
# image_motion_effect : zoom_in | zoom_out | pan_left_to_right | pan_right_to_left | pan_top_to_bottom | pan_bottom_to_top | zoom_pan_soft | ken_burns
# motion_intensity : 0.25–2.0 — photo animation amplitude (default 1.0)
# text_effect : none | fade_in | slide_up | slide_down | slide_left | bounce (ignored if text_mode=word_by_word)
# text_effect_intensity : 0.25–2.0 — text animation intensity (default 1.0)
# text_border_width : 0–10 px — black outline around characters (0 = disabled)
# text_mode : "static" (default) | "word_by_word" — reveal words one by one
# word_reveal_speed : 0.3–5.0 w/s — speed for word_by_word mode (default 1.5, ~2.0 for OpenAI TTS)
# word_anim : "none" (default) | "fade" — fade-in crossfade on each word (word_by_word only)
مثال curl — تحرير الصوت
# Replace audio (deletes original)
curl -X POST https://rapidvideomaker.com/api/v1/render.php \
-H "Authorization: Bearer rvm_your_token" \
-F "videos[]=@my_video.mp4" \
-F "videos[]=@my_music.mp3" \
-F "mode=add_audio"
# Keep original audio + overlay MP3
curl -X POST https://rapidvideomaker.com/api/v1/render.php \
-H "Authorization: Bearer rvm_your_token" \
-F "videos[]=@my_video.mp4" \
-F "videos[]=@my_music.mp3" \
-F "mode=mix_audio" \
-F 'options={"mp3_volume":0.7}'
# mp3_volume : 0.0 (muted) → 1.0 (original volume, default) → 2.0 (amplified)
مثال curl — وضع overlay_video
curl -X POST https://rapidvideomaker.com/api/v1/render.php \
-H "Authorization: Bearer rvm_your_token" \
-F "videos[]=@main_video.mp4" \
-F "videos[]=@overlay_video.mp4" \
-F "mode=overlay_video" \
-F 'options={"position":"bottom-right","scale":0.25,"opacity":1.0,"margin":20,"audio":"main"}'
# Green screen overlay
curl -X POST https://rapidvideomaker.com/api/v1/render.php \
-H "Authorization: Bearer rvm_your_token" \
-F "videos[]=@main_video.mp4" \
-F "videos[]=@webcam_greenscreen.mp4" \
-F "mode=overlay_video" \
-F 'options={"position":"bottom-left","scale":0.35,"chroma_key":true,"chroma_similarity":0.15,"audio":"mix"}'
# position : top-left | top-right | bottom-left | bottom-right | center (default: bottom-right)
# scale : 0.05–1.0 — overlay width as fraction of main video (default 0.30)
# opacity : 0.0–1.0 — overlay transparency (default 1.0)
# margin : 0–200 px — gap from frame edge, ignored if center (default 10)
# audio : main | overlay | mix — audio to keep (default: main)
# chroma_key : true | false — remove green (#00FF00) background from overlay (default false)
# chroma_similarity : 0.01–0.60 — green screen tolerance (default 0.20)
مثال curl — دمج مقاطع الفيديو
curl -X POST https://rapidvideomaker.com/api/v1/render.php \
-H "Authorization: Bearer rvm_your_token" \
-F "videos[]=@clip1.mp4" \
-F "videos[]=@clip2.mp4" \
-F "transition_type=fade" \
-F "transition_duration=0.5"
GET
/api/v1/jobs.php?job_id=<hex32>
حالة المهمة
الحالات الممكنة
| الحالة | المعنى | حقول إضافية |
|---|---|---|
| queued | في قائمة الانتظار، لم تُعالج بعد | queue_position, queue_total, eta_minutes |
| processing | FFmpeg قيد المعالجة | — |
| ready | مكتملة — الملف متاح | download_url, created_at, expires_at |
| error | فشلت المعالجة | error (message) |
الردود حسب الحالة
queued
{
"job_id": "a3f1c8...",
"status": "queued",
"queue_position": 2,
"queue_total": 3,
"eta_minutes": 7
}
ready
{
"job_id": "a3f1c8...",
"status": "ready",
"download_url": "https://rapidvideomaker.com/api/download.php?job_id=a3f1c8...",
"created_at": "2026-06-02T10:00:00+00:00",
"expires_at": "2026-06-02T12:00:00+00:00"
}
مثال curl
curl -H "Authorization: Bearer rvm_your_token" \
"https://rapidvideomaker.com/api/v1/jobs.php?job_id=a3f1c8..."
GET
/api/v1/jobs.php
List all jobs created with this token (paginated, sorted by date desc)
المعاملات المشتركة (multipart/form-data)
| apidocs_th_param | النوع | الافتراضي | apidocs_th_desc |
|---|---|---|---|
page | integer | 1 | Page number (starts at 1) |
limit | integer | 20 | Results per page (max 50, default 20) |
الردود حسب الحالة
{
"success": true,
"jobs": [
{ "job_id": "a3f1c8...", "status": "ready", "mode": "fusion", "created_at": "2026-06-02T10:00:00+00:00", "expires_at": "2026-06-02T12:00:00+00:00", "download_url": "https://..." },
...
],
"total": 12,
"page": 1,
"limit": 20
}
POST
/api/v1/publish.php
نشر فيديو على YouTube أو TikTok
ينشر job منتهياً (status=ready) على حساب أو أكثر من الحسابات الاجتماعية. يجب أن ينتمي الـ token إلى حساب عضو (وليس token المشرف).
متطلب مسبق: يجب ربط الحسابات الاجتماعية (YouTube، TikTok) عبر OAuth في صفحة النشر بمنطقة الأعضاء قبل استخدام هذا الـ endpoint. يظهر
account_id لكل حساب هناك.المعاملات المشتركة (multipart/form-data)
| apidocs_th_param | النوع | apidocs_th_required | apidocs_th_desc |
|---|---|---|---|
job_id | string | apidocs_required | معرّف الـ job (hex 32 حرفاً) للفيديو المنتهي |
publications | array | apidocs_required | مصفوفة كائنات النشر (بحد أقصى 10) |
كائن النشر
| apidocs_th_param | النوع | apidocs_th_required | apidocs_th_desc |
|---|---|---|---|
account_id | integer | apidocs_required | معرّف الحساب الاجتماعي المرتبط — يظهر في صفحة النشر بمنطقة الأعضاء |
title | string | — | عنوان الفيديو (بحد أقصى 512 حرفاً) |
description | string | — | وصف الفيديو (بحد أقصى 5 000 حرف) |
tags | string | — | وسوم مفصولة بفواصل (بحد أقصى 1 024 حرفاً) |
visibility | string | — | public | private | unlisted — الافتراضي: public |
tiktok_mode | string | — | draft | direct — TikTok فقط — الافتراضي: direct |
tiktok_privacy | string | الوضع المباشر | TikTok فقط — مطلوب في الوضع المباشر |
allow_comment | boolean | — | TikTok فقط — السماح بالتعليقات |
allow_duet | boolean | — | TikTok فقط — السماح بالثنائيات |
allow_stitch | boolean | — | TikTok فقط — السماح بالدمج |
your_brand | boolean | — | TikTok فقط — الإفصاح عن المحتوى الترويجي العضوي ("علامتك التجارية"). |
branded_content | boolean | — | TikTok فقط — الإفصاح عن المحتوى التجاري |
tiktok_cover_ms | integer | — | TikTok فقط — الطابع الزمني للإطار الغلاف بالمللي ثانية (0–60 000، الافتراضي 1 000) |
الردود حسب الحالة
{
"success": true,
"results": [
{
"account_id": 12,
"pub_id": 47,
"status": "published",
"provider": "youtube",
"url": "https://youtu.be/abc123"
}
]
}
رموز الخطأ لكل نشر
| apidocs_th_code | المعنى |
|---|---|
job_not_ready | الـ job لم ينتهِ بعد |
mode_not_supported | لا يمكن نشر jobs الـ text_to_mp3 |
account_not_found | الحساب غير موجود أو غير متصل |
tiktok_privacy_required | مستوى الخصوصية مطلوب في الوضع المباشر |
publication_failed | أعاد المزوّد خطأً أثناء الرفع |
مثال cURL
curl -X POST https://rapidvideomaker.com/api/v1/publish.php \
-H "Authorization: Bearer rvm_your_token" \
-H "Content-Type: application/json" \
-d '{
"job_id": "a3f1c8...",
"publications": [
{
"account_id": 12,
"title": "My video",
"description": "Created with RapidVideoMaker",
"visibility": "public"
}
]
}'
GET
/api/download.php?job_id=<hex32>
تنزيل الملف النهائي
يعيد ملف MP4 النهائي كتدفق (Content-Type: video/mp4). لا يتطلب رمزاً. متاح فقط عندما تكون الحالة ready.
يُحتفظ بالملف لمدة ساعتين بعد اكتمال المهمة، ثم يُحذف. نزّله فور أن تصبح الحالة ready.
معامل اختياري
| المعامل | الوصف |
|---|---|
| filename | الاسم المقترح للملف المُنزَّل (مثلاً: my-video.mp4) |
مثال curl
curl -o "output.mp4" \
"https://rapidvideomaker.com/api/download.php?job_id=a3f1c8...&filename=output.mp4"
الـ Webhooks
الـ Webhooks بديل للاستطلاع المتكرر: بدلاً من التحقق من الحالة كل X ثوانٍ، تقدم رابطاً ويستدعيك الخادم تلقائياً عند اكتمال المهمة.
كيف يعمل
- مرر
callback_urlفي POST إلى/api/v1/render.php - يتضمن الرد
webhook_secret— احتفظ به للتحقق من التوقيعات - عندما تصل المهمة إلى
readyأوerror، يرسل الخادم JSONPOSTموقعاً إلى رابطك - تحقق من التوقيع بـ
HMAC-SHA256(webhook_secret, raw_body)
القيود: يجب أن يكون
callback_url رابطاً عاماً قابلاً للوصول (http أو https). تُحجب عناوين IP الخاصة وعناوين الاسترجاع والمحجوزة من طرف الخادم. المهلة: 10 ثوانٍ. الحمولة المُستلَمة
نجاح (ready)
{
"job_id": "a3f1c8...",
"status": "ready",
"download_url": "https://rapidvideomaker.com
/api/download.php?job_id=a3f1c8...",
"timestamp": "2026-04-04T12:00:00+00:00"
}
فشل (error)
{
"job_id": "a3f1c8...",
"status": "error",
"error": "FFmpeg xfade failed:...",
"timestamp": "2026-04-04T12:00:00+00:00"
}
الترويسات التي يرسلها الخادم
| الترويسة | القيمة |
|---|---|
| Content-Type | application/json |
| X-RVM-Signature | sha256=<hmac_hex> — توقيع HMAC-SHA256 للجسم الخام |
| X-RVM-Job-Id | job_id المعني |
التحقق من التوقيع
# Python
import hmac, hashlib
def verify_webhook(secret: str, body: bytes, signature_header: str) -> bool:
expected = "sha256=" + hmac.new(
secret.encode(), body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature_header)
# Flask/FastAPI endpoint:
sig = request.headers.get("X-RVM-Signature", "")
if not verify_webhook(WEBHOOK_SECRET, request.data, sig):
return "Invalid signature", 403
data = request.get_json()
أكواد الأخطاء
| HTTP | كود JSON | السبب |
|---|---|---|
| 401 | unauthorized | الرمز مفقود أو غير صالح أو مُلغى |
| 400 | missing_files | لم تُستلَم أي ملفات |
| 400 | too_few_files | أُرسل أقل من ملفين |
| 400 | too_many_files | أُرسل أكثر من 20 ملفاً |
| 400 | invalid_mime | ملف غير مدعوم — يُقبل MP4 وMP3 وJPG/PNG فقط |
| 400 | wrong_file_count | عدد الملفات لا يطابق النمط المختار |
| 400 | wrong_file_types | أنواع الملفات لا تطابق النمط المختار |
| 400 | invalid_file_combination | مجموعة الملفات بدون نمط محدد لا تطابق أي نمط مدعوم |
| 400 | invalid_options | حقل options ليس JSON صحيحاً |
| 400 | invalid_option | قيمة في options غير صالحة |
| 400 | file_too_large | ملف يتجاوز 500 ميجابايت |
| 400 | invalid_order | مصفوفة order ليست تبديلاً صحيحاً |
| 400 | invalid_job_id | صيغة job_id غير صحيحة (يجب أن تكون 32 حرفاً سداسياً) |
| 404 | job_not_found | المهمة غير موجودة — job_id مجهول أو لم يُنشأ قط |
| 410 | job_expired | انتهت صلاحية المهمة — وُجدت لكن نافذة الاسترداد لـ 2 ساعة انقضت |
| 429 | quota_exceeded | بلغ حد 20 مهمة ناجحة يومياً |
| 429 | rate_limited | تجاوز 12 طلباً/دقيقة على /api/v1/jobs.php |
| 500 | server_error | خطأ داخلي في الخادم |
أمثلة التكامل
أمثلة لكل نمط — ثبِّت requests بـ pip install requests.
الإعداد المشترك
import requests, time, sys, json
API_BASE = "https://rapidvideomaker.com"
API_TOKEN = "rvm_your_token_here"
HEADERS = {"Authorization": f"Bearer {API_TOKEN}"}
نمط image_to_video — صورة + صوت → فيديو
with open("scene.jpg", "rb") as fi, open("narration.mp3", "rb") as fa:
resp = requests.post(
f"{API_BASE}/api/v1/render.php",
headers=HEADERS,
files=[
("videos[]", ("scene.jpg", fi, "image/jpeg")),
("videos[]", ("narration.mp3", fa, "audio/mpeg")),
],
data={
"mode": "image_to_video",
"options": json.dumps({
"text": "Chapter 1",
"font_size": 72,
"text_color": "white",
"text_position": "bottom",
"box": True,
"box_color": "black@0.4",
"fade_duration": 0.5,
"width": 1080,
"height": 1920,
"image_fit": "contain", # "contain" | "cover"
"bg_color": "black", # ignored if image_fit="cover"
"enable_image_motion": True,
"image_motion_effect": "ken_burns",
"motion_intensity": 1.0, # 0.25–2.0 — photo animation amplitude
"text_effect": "slide_up", # none | fade_in | slide_up | slide_down | slide_left | bounce (ignored if text_mode=word_by_word)
"text_effect_intensity": 1.0, # 0.25–2.0 — text animation intensity
# word-by-word reveal (mutually exclusive with text_effect):
# "text_mode": "word_by_word", "word_reveal_speed": 2.0, "word_anim": "fade"
}),
},
)
تحرير الصوت
# Replace audio (deletes original) — mode=add_audio
with open("video.mp4", "rb") as fv, open("music.mp3", "rb") as fa:
resp = requests.post(
f"{API_BASE}/api/v1/render.php",
headers=HEADERS,
files=[
("videos[]", ("video.mp4", fv, "video/mp4")),
("videos[]", ("music.mp3", fa, "audio/mpeg")),
],
data={"mode": "add_audio"},
)
# Keep original audio + overlay MP3 — mode=mix_audio
with open("video.mp4", "rb") as fv, open("music.mp3", "rb") as fa:
resp = requests.post(
f"{API_BASE}/api/v1/render.php",
headers=HEADERS,
files=[
("videos[]", ("video.mp4", fv, "video/mp4")),
("videos[]", ("music.mp3", fa, "audio/mpeg")),
],
data={"mode": "mix_audio", "options": json.dumps({"mp3_volume": 0.7})},
# mp3_volume : 0.0 = muted, 1.0 = original volume (default), 2.0 = amplified
)
وضع overlay_video — صورة داخل صورة
with open("main.mp4", "rb") as fm, open("overlay.mp4", "rb") as fo:
resp = requests.post(
f"{API_BASE}/api/v1/render.php",
headers=HEADERS,
files=[
("videos[]", ("main.mp4", fm, "video/mp4")),
("videos[]", ("overlay.mp4", fo, "video/mp4")),
],
data={
"mode": "overlay_video",
"options": json.dumps({
"position": "bottom-right", # top-left | top-right | bottom-left | bottom-right | center
"scale": 0.25, # 0.05–1.0 — overlay width fraction
"opacity": 1.0, # 0.0–1.0 — transparency
"margin": 20, # 0–200 px — gap from frame edge
"audio": "main", # main | overlay | mix
# green screen: "chroma_key": True, "chroma_similarity": 0.15
}),
},
)
دمج مقاطع الفيديو
with open("clip1.mp4", "rb") as f1, open("clip2.mp4", "rb") as f2:
resp = requests.post(
f"{API_BASE}/api/v1/render.php",
headers=HEADERS,
files=[
("videos[]", ("clip1.mp4", f1, "video/mp4")),
("videos[]", ("clip2.mp4", f2, "video/mp4")),
],
data={"transition_type": "fade", "transition_duration": "0.5"},
)
الاستعلام + التنزيل (مشترك لجميع الأنماط)
resp.raise_for_status()
job_id = resp.json()["job_id"]
print(f"Job created: {job_id}")
for _ in range(120): # timeout 10 min (120 × 5s)
r = requests.get(
f"{API_BASE}/api/v1/jobs.php",
headers=HEADERS,
params={"job_id": job_id},
)
data = r.json()
status = data["status"]
if status == "queued":
pos = data.get("queue_position", "?")
eta = data.get("eta_minutes", "?")
print(f"Queued — position {pos}, ETA ~{eta} min")
elif status == "processing":
print("Processing…")
elif status == "ready":
download_url = data["download_url"]
break
elif status == "error":
sys.exit(f"Error: {data.get('error')}")
time.sleep(5)
else:
sys.exit("Timeout: job not completed after 10 min")
r = requests.get(download_url, stream=True)
with open("output.mp4", "wb") as f:
for chunk in r.iter_content(65536):
f.write(chunk)
print("Downloaded: output.mp4")
نهجان في n8n: الاستعلام (حلقة الحالة) أو Webhook (الخادم يستدعي n8n). يُوصى بالـ Webhook.
النهج أ — Webhook (موصى به)
3 عقد فقط، بلا حلقات.
العقدة 1 — مشغِّل Webhook
أضف عقدة Webhook كمدخل لسير العمل (الأسلوب POST).
العقدة 2 — إنشاء المهمة (طلب HTTP)
| الأسلوب | POST |
| الرابط | https://rapidvideomaker.com/api/v1/render.php |
| المصادقة | Header Auth — Authorization: Bearer rvm_… |
| نوع محتوى الجسم | Form-Data Multipart |
| Body params | حقل ثنائي videos[] لكل مقطع + حقل نصي callback_url |
احتفظ بـ webhook_secret من الرد في متغير سير العمل للتحقق من التوقيعات.
العقدة 3 — معالجة النتيجة (في سير العمل المُشغَّل بالـ Webhook)
عندما يستلم n8n POST الخادم، تكون $json.status إما ready أو error.
للتحقق من التوقيع: قارن
{{ $headers['x-rvm-signature'] }} مع HMAC-SHA256 من webhook_secret الخاص بك.النهج ب — الاستعلام (بدون Webhook)
5 عقد، حلقة حالة كل 10 ثوانٍ.
العقدة 1 — إنشاء المهمة — نفس الإعداد بدون callback_url.
العقدة 2 — انتظار — 10 ثوانٍ.
العقدة 3 — استعلام الحالة (طلب HTTP GET)
| الرابط | https://rapidvideomaker.com/api/v1/jobs.php |
| معاملات الاستعلام | job_id = {{ $('العقدة 1').item.json.job_id }} |
| المصادقة | مصادقة الترويسة — نفس الرمز |
العقدة 4 — If: {{ $json.status }} === 'ready' → صحيح: العقدة 5 / خطأ: العودة للعقدة 2.
أضف عداد تكرار في عقدة Set للخروج من الحلقة بعد 60 محاولة.
العقدة 5 — تنزيل: طلب HTTP GET على {{ $json.download_url }}.
الخطوة 1 — إنشاء المهمة (اختر نمطاً)
# fusion
JOB=$(curl -s -X POST https://rapidvideomaker.com/api/v1/render.php \
-H "Authorization: Bearer rvm_your_token" \
-F "videos[]=@clip1.mp4" -F "videos[]=@clip2.mp4")
# add_audio (replace audio)
JOB=$(curl -s -X POST https://rapidvideomaker.com/api/v1/render.php \
-H "Authorization: Bearer rvm_your_token" \
-F "videos[]=@video.mp4" -F "videos[]=@music.mp3" \
-F "mode=add_audio")
# mix_audio (overlay music at 70% volume)
JOB=$(curl -s -X POST https://rapidvideomaker.com/api/v1/render.php \
-H "Authorization: Bearer rvm_your_token" \
-F "videos[]=@video.mp4" -F "videos[]=@music.mp3" \
-F "mode=mix_audio" -F 'options={"mp3_volume":0.7}')
# image_to_video
JOB=$(curl -s -X POST https://rapidvideomaker.com/api/v1/render.php \
-H "Authorization: Bearer rvm_your_token" \
-F "videos[]=@scene.jpg" -F "videos[]=@narration.mp3" \
-F "mode=image_to_video" \
-F 'options={"text":"Chapter 1","font_size":72,"text_position":"bottom","fade_duration":0.5,"width":1080,"height":1920}')
JOB_ID=$(echo $JOB | grep -o '"job_id":"[^"]*"' | cut -d'"' -f4)
echo "Job ID: $JOB_ID"
الخطوة 2 — الاستعلام
while true; do
STATUS=$(curl -s \
-H "Authorization: Bearer rvm_your_token" \
"https://rapidvideomaker.com/api/v1/jobs.php?job_id=$JOB_ID")
STATE=$(echo $STATUS | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
echo "Status: $STATE"
[ "$STATE" = "ready" ] && break
[ "$STATE" = "error" ] && { echo "Error"; exit 1; }
sleep 10
done
الخطوة 3 — التنزيل
DOWNLOAD_URL=$(echo $STATUS | grep -o '"download_url":"[^"]*"' | cut -d'"' -f4)
curl -o output.mp4 "$DOWNLOAD_URL"
أفضل الممارسات
- تكرار الاستعلام: نقطة
/api/v1/jobs.phpمحدودة بـ 12 طلباً/دقيقة لكل رمز. انتظر 5 ثوانٍ على الأقل بين كل طلب. - المهلة: نفِّذ مهلة من طرف العميل (مثلاً 10 دقائق).
- التنزيل السريع: نزِّل الملف فور أن تصبح الحالة
ready. يُحذف بعد ساعتين من اكتمال المهمة. - إدارة الحصة: تحقق من
quota_remainingفي رد POST. - أخطاء الشبكة: عند خطأ في الشبكة أثناء الاستعلام، انتظر وأعد المحاولة.
تُحتفظ بملفات النتائج ساعتين بعد اكتمال المهمة، ثم تُحذف تلقائياً.