توثيق API

مرجع كامل لواجهة Viffly.app REST API

المحتويات

المصادقة الأرصدة فيديو الذكاء الاصطناعي (Alibaba وMiniMax)صور الفيديو المصغّرة الويب هوك تكامل n8n توليد الريلز الفيديوهات خدمات الذكاء الاصطناعي مفاتيح API الوسائط الأخطاء

المصادقة

تدعم واجهة API طريقتين للمصادقة. تتطلب كلتاهما خطةBusinessأو أعلى للاستدعاءات الخارجية.

الطريقة 1: مفتاح API (موصى به)

curl -X POST https://viffly.app/api/generate-sync \
  -H "X-API-Key: vf_votre_cle_api" \
  -F "audio=@narration.mp3" \
  -F "title=Ma vidéo"

الطريقة 2: Bearer Token

# Obtenir un token via /api/login
# session : "short" (12 h) | "default" (7 j) | "long" (30 j)
curl -X POST https://viffly.app/api/login \
  -H "Content-Type: application/json" \
  -d '{"email":"vous@email.com","password":"...","session":"short"}'

# Réponse : { "token": "eyJhbG...", "expires_at": "...", "session_ttl": "12h" }

# Utiliser le token
curl -H "Authorization: Bearer eyJhbG..." \
  https://viffly.app/api/me

تنتهي صلاحية Bearer Tokens بعد12 ساعة أو 7 أيام أو 30 يوماً حسب معامل `session`. مفاتيح API (vf_...) فهي مقيّدة بصلاحيات وقابلة للإلغاء والتدوير ولها حد معدّل مستقل — وهي الطريقة المناسبة للإنتاج.

صلاحيات المفاتيح

يحمل كل مفتاح قائمة صلاحيات. أي استدعاء لنقطة نهاية غير مغطاة يُرفض برمز 403 يذكر الصلاحية الناقصة — امنح الحد الأدنى اللازم.

الصلاحية	نقاط النهاية المغطاة
generate	/api/ltx/* · /api/generate · /api/generate-sync · talking-head · restyle · montage · longshort · loop-assemble · director · slideshow · reframe · autocut · audio-clean · watermark · voiceover · media-jobs
ai_images	/api/image-jobs · /api/generate-images · /api/images/edit · /api/characters/*
ai_script	/api/ai/*
videos	/api/videos
credits	/api/me · /api/credits/*

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

دورة حياة المفاتيح

5 مفاتيح كحد أقصى لكل حساب. يُعرض السر الكامل عند الإنشاء فقط ولا يمكن عرضه مجدداً.
حد معدّل قابل للضبط لكل مفتاح (60 طلباً/دقيقة افتراضياً، 1000 كحد أقصى). التجاوز يعيد 429 مع ترويسة Retry-After.
انتهاء صلاحية باختيارك: 7 أو 30 أو 90 أو 365 يوماً أو أبداً. المفتاح المنتهي يُرفض دون حذفه.
التدوير: سر جديد يحل محل القديم فوراً مع حفظ الاسم والصلاحيات والحدود. استخدمه فور احتمال تسريب مفتاح.

# Renouveler le secret d'une clé (nom, scopes et limites conservés)
curl -X POST https://viffly.app/api/keys/{id}/rotate \
  -H "Authorization: Bearer eyJhbG..."

# Déconnecter tous les autres appareils
curl -X POST https://viffly.app/api/account/revoke-sessions \
  -H "Authorization: Bearer eyJhbG..."

نظام الأرصدة

تستهلك كل عملية ذكاء اصطناعي أرصدة (تكلفة ثابتة للوظائف العادية، وبحسب المدة لفيديو الذكاء الاصطناعي). العمليات المجانية (Pexels، Whisper) لا تستهلك شيئًا.

🎬

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

5 cr.

📝

نص بالذكاء الاصطناعي

1 cr.

🎙️

صوت بالذكاء الاصطناعي

4 cr.

🖼️

صورة بالذكاء الاصطناعي (×1)

2 cr.

🎵

موسيقى بالذكاء الاصطناعي

5 cr.

💡

موجّهات الصور

مجاني

📷

صور Pexels

مجاني

💬

النسخ النصي

مجاني

أمثلة:فيديو اقتصادي (صوتك + Pexels) =5 cr.| فيديو قياسي (نص + صوت بالذكاء الاصطناعي) =10 cr.| فيديو كامل بالذكاء الاصطناعي (تلقائي بالكامل) =21 cr.

GET/api/credits/costs

يُرجع تكلفة كل عملية بالأرصدة، والخطط المتاحة، وسيناريوهات الاستخدام.

الاستجابة

{
  "costs": { "render": 5, "ai_script": 1, "ai_voice": 4, "ai_image": 2, "ai_music": 5, "pexels": 0 },
  "packages": [
    { "slug": "free", "label": "Free", "monthlyCredits": 15 },
    { "slug": "pro", "label": "Pro", "monthlyCredits": 200 }, ...
  ],
  "scenarios": [ { "name": "Budget", "credits": 5 }, ... ]
}

GET/api/meمصادقة

يُرجع معلومات الحساب، بما في ذلك رصيد الأرصدة.

الاستجابة

{
  "id": "abc123",
  "client_email": "vous@email.com",
  "package": "pro",
  "creditsTotal": 142,
  "creditsMonthly": 130,
  "creditsPack": 12,
  "monthlyAllowance": 150,
  "packageLabel": "Pro",
  "creditCosts": { "render": 5, "ai_voice": 4, ... }
}

توليد الفيديو بالذكاء الاصطناعي (MiniMax / Alibaba)

يولّد فيديو مننص(t2v) أو منصورة(i2v) عبر نماذج الذكاء الاصطناعي. هذه هي الواجهة التي يجب استخدامها من n8n. التدفقغير متزامن: تُرسل مهمة، ثم تستعلم عن حالتها حتىdone.

🌊 Hailuo 2.3 (MiniMax)

MiniMax Hailuo 2.3 · model: "hailuo23"

🎬 Wan 2.2

Alibaba Wan 2.7 · model: "wan27"

يتطلب خطةProأو أعلى. المصادقة عبرX-API-Key.

GET/api/ltx/pricing

يسرد الفئات (الدقة × المدة)، ونسب الأبعاد، والسيناريوهات. لا حاجة للمصادقة — مفيد لملء واجهة أو اختيار tier_id.

الاستجابة

{
  "tiers": [
    { "id": "tier1", "label": "720p · 5s",  "resolution": "720p",  "seconds": 5,  "credits": 10 },
    { "id": "tier2", "label": "720p · 5s",  "resolution": "720p",  "seconds": 5,  "credits": 10 },
    { "id": "tier3", "label": "720p · 10s", "resolution": "720p",  "seconds": 10, "credits": 20 },
    { "id": "tier6", "label": "1080p · 5s", "resolution": "1080p", "seconds": 5,  "credits": 10 },
    { "id": "tier7", "label": "1080p · 10s","resolution": "1080p", "seconds": 10, "credits": 20 }
  ],
  "models": [
    { "id": "wan27", "provider": "dashscope_wan", "tiers": [...] },
    { "id": "hailuo23", "provider": "minimax_hailuo", "tiers": [...] }
  ],
  "aspects": [ { "id": "9:16" }, { "id": "1:1" }, { "id": "16:9" } ],
  "scenarios": [ { "id": "cinematic" }, { "id": "product" }, ... ],
  "default_negative": "ugly, blurry, low quality, ..."
}

POST/api/ltx/generate10 cr.مصادقة

يُرسل مهمة توليد فيديو. يُرجع job_id فورًا (دون حجب). الجسم بصيغة JSON.

جسم الطلب

الحقل	النوع	الوصف
mode*	string	"t2v" (نص←فيديو) أو "i2v" (صورة←فيديو)
prompt*	string	وصف الفيديو (≥ 3 أحرف)
tier_id	string	tier1 أو tier2 أو tier3 أو tier6 أو tier7. راجع /pricing للخيارات الخاصة بكل محرك.
model	string	"hailuo23" (MiniMax)، "happyhorse" أو "wan27" (Alibaba)
image_base64	string	الصورة الأولية بترميز base64 (مطلوبة إذا كان mode=i2v). بدون بادئة data:
image_url	string	بديل: رابط HTTPS عام للصورة الأولية (i2v)
negative	string	موجّه سلبي (الافتراضي: انظر /api/ltx/pricing)
aspect	string	"9:16" (افتراضي)، "1:1"، "16:9"
scenario_type	string	التوجيه الإبداعي (انظر /api/ltx/pricing)
fps	number	إطارات/ثانية (الافتراضي: 24)
seed	number	البذرة (قابلية التكرار). عشوائية إذا حُذفت
audio_on	boolean	الاحتفاظ بمسار الصوت المُولّد (الافتراضي: true)

الاستجابة

{
  "job_id": "915c93ea-58b7-4808-a83f-5dfa98ee1ef5",
  "status": "processing",
  "tier": { "id": "tier2", "label": "720p · 5s", "credits": 10 }
}

مثال — نص ← فيديو:

curl -X POST https://viffly.app/api/ltx/generate \
  -H "X-API-Key: vf_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "t2v",
    "model": "hailuo23",
    "prompt": "a sports car drifting on a coastal road at sunset, cinematic",
    "tier_id": "tier2",
    "aspect": "9:16"
  }'

مثال — صورة ← فيديو:

curl -X POST https://viffly.app/api/ltx/generate \
  -H "X-API-Key: vf_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "i2v",
    "model": "wan27",
    "prompt": "slow cinematic push in, gentle motion",
    "tier_id": "tier2",
    "image_base64": "'"$(base64 -w0 photo.jpg)"'"
  }'

POST/api/ltx/generate-sync10 cr.مصادقة

النسخة المتزامنة: تُرسل، وتنتظر المعالجة داخليًا، ثم تُرجع الفيديو — في استدعاء واحد فقط (بدون حلقة انتظار/استعلام). مثالية لعقدة n8n واحدة. اضبط مهلة طويلة (مثلاً 1200000 مللي ثانية).

جسم الطلب

الحقل	النوع	الوصف
(مطابق لـ /api/ltx/generate)*	json	mode, prompt, tier_id, model, image_base64/image_url, aspect…

الاستجابة

// Par défaut → renvoie le FICHIER MP4 (binaire). Dans n8n : Response Format = File.
// Avec ?format=json → renvoie l'URL à la place :
{
  "status": "done",
  "job_id": "915c93ea-...",
  "output_url": "/videos/ltx_915c93ea-....mp4",
  "url": "https://viffly.app/videos/ltx_915c93ea-....mp4"
}

# Récupère directement le MP4 (sortie binaire)
curl -X POST https://viffly.app/api/ltx/generate-sync \
  -H "X-API-Key: vf_votre_cle" -H "Content-Type: application/json" \
  -d '{"mode":"t2v","model":"hailuo23","prompt":"...","tier_id":"tier2"}' \
  --max-time 1200 -o video.mp4

# Ou récupère juste l'URL (JSON)
curl -X POST "https://viffly.app/api/ltx/generate-sync?format=json" \
  -H "X-API-Key: vf_votre_cle" -H "Content-Type: application/json" \
  -d '{"mode":"t2v","prompt":"...","tier_id":"tier2"}'

GET/api/ltx/status/:idمصادقة

(الوضع غير المتزامن) يستعلم عن حالة مهمة. استدعِه في حلقة (كل ~5-10 ثوانٍ) حتى تصبح الحالة done أو error. غير ضروري إذا كنت تستخدم /generate-sync.

الاستجابة

// en cours
{ "id": "915c93ea-...", "status": "processing", "progress": 50 }

// terminé
{
  "id": "915c93ea-...",
  "status": "done",
  "output_url": "/videos/ltx_915c93ea-....mp4",  // relatif → préfixer https://viffly.app
  "progress": 100
}

// échec (crédits remboursés)
{ "id": "915c93ea-...", "status": "error", "error": "..." }

output_urlهونسبي. رابط التنزيل الكامل =https://viffly.app+output_url.

صور مصغّرة ذكية

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

16:9 · 9:16 · 1:1 · 4:5قص ذكي لكل وجهة

1–6 × formatلحظات مختلفة فعلاً

Async · n8n readyمهام دائمة مع تتبع التقدم

POST/api/thumbnails5 cr.مصادقة

ابدأ مهمة من رابط فيديو أو مصدر S3 مصرح به أو ملف مستضاف مسبقاً في Viffly.

جسم الطلب

الحقل	النوع	الوصف
source_url*	string	URL HTTPS publique, s3:// autorisé ou /videos/...
count	number	1 à 6 variantes par format (défaut : 3)
formats	string[]	auto, 16:9, 9:16, 1:1, 4:5
visual_mode	string	frames (défaut), enhance ou generate
ai_quality	string	standard (2 cr./image) ou premium (5 cr./image)
image_prompt	string	Direction facultative pour la retouche ou la génération
language	string	Langue du titre automatique : auto, fr, en, ar, es, de ou pt
title	string	Titre optionnel ; généré depuis le contenu si omis
subtitle	string	Sous-titre optionnel
style	string	editorial, bold, clean, minimal
tone	string	auto, warm, cool, mono
smart	boolean	Analyse visuelle + transcription + point focal
include_text	boolean	Ajouter ou non la composition typographique
accent	string	Couleur hexadécimale, ex. #6D4AFF

الاستجابة

{
  "job_id": "53a9c34d-...",
  "status": "processing",
  "cost": 11,
  "visual_mode": "generate",
  "cost_breakdown": { "composition": 5, "ai_images": 6 },
  "outputs_planned": 3,
  "status_url": "/api/thumbnails/53a9c34d-..."
}

curl -X POST https://viffly.app/api/thumbnails \
  -H "X-API-Key: vf_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://cdn.exemple.com/video.mp4",
    "count": 3,
    "formats": ["16:9", "9:16"],
    "visual_mode": "generate",
    "ai_quality": "standard",
    "language": "fr",
    "image_prompt": "documentary editorial visual, authentic texture, no text",
    "style": "editorial",
    "smart": true
  }'

POST/api/thumbnails/upload5 cr.مصادقة

رفع multipart مناسب لـ n8n وللملفات حتى 200 ميغابايت.

جسم الطلب

الحقل	النوع	الوصف
video*	file	MP4, MOV, M4V, MKV, WebM, AVI ou MPEG · 200 Mo max
formats	string	Tableau JSON ou liste séparée par des virgules
count	number	1 à 6 variantes par format
visual_mode	string	frames, enhance ou generate
ai_quality	string	standard ou premium
image_prompt	string	Direction facultative pour l’IA
language	string	Langue du titre automatique : auto, fr, en, ar, es, de ou pt
style	string	editorial, bold, clean, minimal

الاستجابة

{ "job_id": "53a9c34d-...", "status": "processing", "status_url": "/api/thumbnails/53a9c34d-..." }

curl -X POST https://viffly.app/api/thumbnails/upload \
  -H "X-API-Key: vf_votre_cle" \
  -F "video=@episode.mp4" \
  -F 'formats=["16:9","9:16"]' \
  -F "count=3" \
  -F "visual_mode=enhance" \
  -F "ai_quality=standard" \
  -F "language=fr" \
  -F "image_prompt=cinematic light, cleaner background" \
  -F "style=editorial"

GET/api/thumbnails/:idمصادقة

تتبّع المهمة واسترجع التحليل والإطارات المصدر وكل الصور النهائية.

الاستجابة

{
  "job_id": "53a9c34d-...",
  "status": "done",
  "progress": 100,
  "analysis": { "summary": "..." },
  "visual_mode": "enhance",
  "outputs": [
    { "url": "/videos/thumb_....jpg", "format": "16:9", "source_kind": "enhanced", "master_url": "/videos/mmedit_....png", "raw_frame_url": "/videos/thumb_..._frame_1.jpg", "width": 1280, "height": 720, "timestamp": 42.1, "score": 91 }
  ]
}

n8n

السلسلة المقترحة: HTTP Request POST ← انتظار 3 ثوانٍ ← HTTP Request GET ← شرط status = done. أعد الحلقة إلى الانتظار ما دام status يساوي processing.

GET https://viffly.app/api/thumbnails/{{ $('Viffly · Miniatures').item.json.job_id }}

الويب هوك — إشعار عند انتهاء المعالجة

أضف callback_url إلى أي طلب إنشاء مهمة: بدلاً من الاستعلام المتكرر عن الحالة، يرسل Viffly طلب POST فور اكتمال المعالجة. لن يبقى تنفيذ n8n أو Make معلّقًا لدقائق.

POST /api/ltx/generate
{
  "mode": "i2v",
  "prompt": "…",
  "callback_url": "https://votre-domaine.com/viffly-hook"
}

يجب أن يكون العنوان بروتوكول HTTPS ومتاحًا للعموم. تُرفض العناوين الخاصة وlocalhost وHTTP العادي عند الإنشاء، قبل خصم أي رصيد.

ما ستستقبله

{
  "event": "job.completed",      // ou "job.failed"
  "job_id": "3f2a…",
  "kind": "video",
  "status": "done",              // ou "error"
  "output_url": "/videos/ltx_3f2a….mp4",
  "error": null,
  "delivered_at": "2026-07-27T19:44:12.031Z"
}

الترويسات

X-Viffly-Eventاسم الحدث، مطابق لحقل event في الجسم

X-Viffly-Deliveryمعرّف فريد للتسليم — استخدمه لتجاهل التكرار

X-Viffly-Timestampطابع زمني unix بالثواني، يدخل في حساب التوقيع

X-Viffly-Signature‎sha256=…‎ — توقيع HMAC للجسم، يتيح التحقق من أن الطلب صادر منّا فعلاً

التحقق من التوقيع

احسب HMAC-SHA256 لـ «الطابع الزمني.الجسم» بمفتاحك السري وقارنه بالترويسة. استخدم الجسم الخام للطلب: إعادة ترميز JSON تغيّر المسافات وتُفسد المقارنة.

const crypto = require('crypto');

function verifie(req, secret) {
  const ts   = req.headers['x-viffly-timestamp'];
  const recu = req.headers['x-viffly-signature'];
  const attendu = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(ts + '.' + req.rawBody)   // corps BRUT, non re-sérialisé
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(recu), Buffer.from(attendu));
}

عند الفشل، تصل المحاولات إلى ٤ متباعدة (فورية، ‎+٢ ث، +١٥ ث، +٦٠ ث). يُعتبر الرد 4xx رفضًا نهائيًا ولا يُعاد. أعد 2xx عند الاستلام.

تكامل n8n — عقدة HTTP Request

تدفق الفيديو غير متزامن. في n8n، النمط هو:إرسال→انتظار→التحقق من الحالة→ التكرار طالما ≠done.

① HTTP Request (POST /generate)② Wait 10s③ HTTP Request (GET /status)④ IF status = done ?→ لا: العودة إلى ②→ نعم: تنزيل

أداة إنشاء عقدة n8n

اضبط الخيارات أدناه ثم أنشئ JSON الخاص بعقدة HTTP Request — انسخه والصقه مباشرة في لوحة n8n (Ctrl+V)، أو نزّل الملف.

نوع العقدةمفتاح APIتبويب «API» في لوحة التحكم

الوضعالنموذجنسبة الأبعاد

الفئة (الدقة × المدة)مصدر الموجّه

FPSSeed (اختياري)الصوت

موجّه سلبي (اختياري)

أو اضبط العقد يدويًا:

NODE 1إرسال المهمة — HTTP Request

Method	POST
URL	https://viffly.app/api/ltx/generate
Authentication	None (نمرّر المفتاح في الترويسة أدناه)
Send Headers	ON → Name: X-API-Key \| Value: vf_votre_cle
Send Body	ON → Body Content Type: JSON
Specify Body	Using JSON

Body (JSON)

{
  "mode": "i2v",
  "model": "hailuo23",
  "prompt": "{{ $json.prompt }}",
  "tier_id": "tier2",
  "aspect": "9:16",
  "image_base64": "{{ $binary.data.data }}"
}

i2v: إذا كانت الصورة تأتي من عقدة سابقة (مثل Telegram أو Read Binary File)، فأشر إلى بياناتها الثنائية base64 باستخدام{{ $binary.data.data }}. بالنسبة لـ t2v، احذفimage_base64واضبط"mode": "t2v".

NODE 2 + 3الانتظار ثم التحقق من الحالة

Node 2 — Wait: 10 ثوانٍ.Node 3 — HTTP Request(استعلام):

Method	GET
URL	https://viffly.app/api/ltx/status/{{ $('NODE 1').item.json.job_id }}
Send Headers	ON → X-API-Key: vf_votre_cle

NODE 4التكرار — IF status = done ?

العقدةIF— الشرط (String):{{ $json.status }} equals done.

false(ليس جاهزًا بعد) → اربط المخرج بـNode 2 (Wait): تستمر الحلقة.
true(اكتمل) → تابع. الرابط النهائي =https://viffly.app{{ $json.output_url }}

تنزيل الفيديو (HTTP Request)

Method	GET
URL	https://viffly.app{{ $json.output_url }}
Response Format	File / Binary

نصائح n8n

لتجنّب حلقة لا نهائية: أضف عدّادًا (عقدة Set + IF على حدّ أقصى من التكرارات، مثلاً 60 ≈ 10 دقائق).
يستغرق Wan 2.2 من 3 إلى 5 دقائق: اضبط Wait على 15-20 ثانية لتقليل عدد الاستدعاءات.
تُخصم التكلفة مرة واحدة عند الإطلاق وتُعاد تلقائيًاإذا فشلت المعالجة.
لا يوجد webhook وارد: إنه استعلام دوري. مفتاح APIvf_…(تبويب «API») يكفي.

توليد الريلز (صوت + صور)

POST/api/generate-sync5 cr.مصادقة

يولّد فيديو وينتظر النتيجة (مهلة 20 دقيقة). يُرجع رابط التنزيل.

جسم الطلب

الحقل	النوع	الوصف
audio*	file	ملف صوتي MP3 للتعليق الصوتي
images	file[]	صور (من 1 إلى 4 ملفات). بديل: image_url
image_url	string	رابط صورة (بديل عن images)
image_url_0..N	string	روابط صور مفهرسة، بدون حد 3 (حتى 30 وسيطًا). رابط .mp4/.mov هنا يُشغَّل كمقطع فيديو في ذلك الموضع.
media	string[]	مصفوفة JSON مرتبة تمزج الصور والفيديوهات — ترتيب المصفوفة = ترتيب العرض. تُكتشف الفيديوهات من الامتداد (.mp4، .mov، .webm…).
format	string	تنسيق الإخراج: 9:16 (افتراضي)، 16:9، 1:1، 4:5، 4:3
title	string	العنوان المعروض في المقدمة
source	string	المصدر / اسم الموقع
script_text	string	نص السكربت للترجمات
template	string	32 templates : default, bold, clean, news, minimal, highlight, cinematic, neon, retro, gaming, story, meme, comic, glitch, noir, vaporwave, duotone, matrix, ticker…
caption_style	string	karaoke, glow, outline, neon, block, shadow, gradient, typewriter
caption_size	string	S, M, L, XL
caption_position	string	top, center, bottom
language	string	fr, en, ar, es, de, it, pt
profile	string	اسم ملف المعالجة (مثل shadesplays)
music_url	string	رابط موسيقى الخلفية (تتكرر تلقائيًا إذا كان الفيديو أطول من المقطوعة)
music_start_at	number	إزاحة بدء الموسيقى (ثوانٍ)
voice_type	string	"ai" لتعليق MiniMax الصوتي (+4 cr.)
voice_id	string	معرف صوت MiniMax
outro_text	string	نص شاشة النهاية
outro_sub	string	العنوان الفرعي لشاشة النهاية

الاستجابة

{
  "videoId": "7865aac1-c301-4060-bd6e-6ca4fe3f6859",
  "url": "https://s3.eu-west-3.amazonaws.com/.../render.mp4",
  "thumbnail": "https://s3.eu-west-3.amazonaws.com/.../thumb.jpg",
  "duration": 27.5,
  "size": 8542190
}

مثال كامل:

curl -X POST https://viffly.app/api/generate-sync \
  -H "X-API-Key: vf_votre_cle" \
  -F "audio=@narration.mp3" \
  -F "format=16:9" \
  -F 'media=["https://cdn.exemple.com/clip.mp4","https://cdn.exemple.com/photo1.jpg","https://cdn.exemple.com/photo2.jpg"]' \
  -F "title=Mon titre" \
  -F "source=MonSite.com" \
  -F "template=gaming" \
  -F "caption_style=karaoke" \
  -F "caption_size=L" \
  -F "script_text=Voici le texte des sous-titres" \
  -F "profile=shadesplays"

POST/api/generate5 cr.مصادقة

يبدأ التوليد في الخلفية. يُرجع jobId لتتبّع التقدّم عبر SSE.

الاستجابة

{ "jobId": "e9e2d4f9-..." }

تتبّع التقدّم:GET /api/videos/events?jobId=...(Server-Sent Events)

الفيديوهات

GET/api/videosمصادقة

يسرد جميع فيديوهات الحساب، مرتبة تنازليًا حسب التاريخ.

الاستجابة

[
  {
    "id": "7865aac1-...",
    "title": "Mon titre",
    "status": "done",
    "url": "https://...",
    "thumbnail": "https://...",
    "size": 8542190,
    "duration": 27.5,
    "created": "2026-03-28T..."
  }, ...
]

GET/api/videos/:id.mp4مصادقة

تنزيل ملف MP4 لفيديو.

DELETE/api/videos/:idمصادقة

حذف فيديو وملفاته المرتبطة.

خدمات الذكاء الاصطناعي

POST/api/ai/script1 cr.مصادقة

يولّد نص تعليق صوتي محسّنًا للانتشار.

جسم الطلب

الحقل	النوع	الوصف
prompt*	string	الموضوع أو التعليمات
existing	string	نص موجود لتحسينه
context	string	سياق إضافي (محتوى الويب)
language	string	اللغة المستهدفة (fr, en, ar...)

الاستجابة

{ "script": "Saviez-vous que...", "charsUsed": 342, "charsMax": 700 }

POST/api/generate-images2 cr.مصادقة

يولّد صورًا عبر FAL Flux 2 Pro.

جسم الطلب

الحقل	النوع	الوصف
prompt*	string	وصف الصورة
count	number	عدد الصور (1-3، الافتراضي: 3)

الاستجابة

{ "images": ["https://fal.media/...", ...] }

التكلفة: 2 رصيد × عدد الصور

POST/api/ai/image-promptمصادقة

يولّد 3 موجّهات صور محسّنة لموضوع معيّن.

جسم الطلب

الحقل	النوع	الوصف
topic*	string	موضوع الفيديو
style	string	النمط البصري المطلوب

الاستجابة

{ "prompts": ["A cinematic...", "An aerial...", "A close-up..."] }

POST/api/generate-music5 cr.مصادقة

يولد موسيقى خلفية عبر MiniMax Music.

جسم الطلب

الحقل	النوع	الوصف
prompt	string	وصف النمط الموسيقي
style	string	النوع الموسيقي (pop, electronic, cinematic...)
instrumental	boolean	موسيقى فقط بدون كلمات (الافتراضي: true)
title	string	عنوان المقطوعة

الاستجابة

{ "taskId": "abc123", "status": "pending" }

التحقق من الحالة:GET /api/generate-music/:taskId

GET/api/voicesمصادقة

يسرد أصوات MiniMax المتاحة.

الاستجابة

{ "voices": [{ "voice_id": "pNInz6ob...", "name": "Adam", "labels": {...} }, ...] }

إدارة مفاتيح API

GET/api/keysمصادقة

يسرد جميع مفاتيح API الخاصة بك.

الاستجابة

[{
  "id": "uuid", "name": "Production", "key_prefix": "vf_a1b2c3d4",
  "scopes": ["generate","videos"], "rate_limit": 60,
  "expires_at": null, "last_used_at": "2026-03-28T...",
  "usage_count": 42, "is_active": true
}]

POST/api/keysمصادقة

ينشئ مفتاح API جديدًا. لا يُرجع المفتاح الكامل إلا عند الإنشاء.

جسم الطلب

الحقل	النوع	الوصف
name	string	اسم المفتاح (مثل Production)
scopes	string[]	الأذونات: generate, videos, credits, ai_script, ai_images, ai_music
rate_limit	number	الطلبات في الدقيقة (1-1000، الافتراضي: 60)
expires_in_days	number	الأيام قبل انتهاء الصلاحية (null = أبدًا)

الاستجابة

{
  "id": "uuid",
  "key": "vf_a1b2c3d4e5f6...",  // ⚠️ Affiché UNE SEULE FOIS
  "name": "Production",
  "scopes": ["generate", "videos", "credits"]
}

PATCH/api/keys/:idمصادقة

تعديل مفتاح (الاسم، الأذونات، حد المعدل، التفعيل/التعطيل).

جسم الطلب

الحقل	النوع	الوصف
name	string	اسم جديد
is_active	boolean	تفعيل/تعطيل
scopes	string[]	أذونات جديدة
rate_limit	number	حد معدل جديد

DELETE/api/keys/:idمصادقة

يحذف مفتاح API نهائيًا.

مكتبة الوسائط

GET/api/musicمصادقة

يسرد مكتبة الموسيقى (المقاطع المرفوعة + MiniMax).

GET/api/pexels/imagesمصادقة

البحث عن صور Pexels.

جسم الطلب

الحقل	النوع	الوصف
q	query	مصطلح البحث
page	query	الصفحة (الافتراضي: 1)
per_page	query	النتائج لكل صفحة (الافتراضي: 20)

GET/api/pexels/videosمصادقة

البحث عن فيديوهات Pexels.

رموز الأخطاء

الرمز	المعنى	الإجراء
401	رمز غير صالح أو منتهي الصلاحية	جدّد الرمز أو أنشئ مفتاح API جديدًا
402	أرصدة غير كافية	اشترِ حزمة أو ارتقِ إلى خطة أعلى
403	خطة غير كافية (يتطلب Business+)	الترقية إلى Business أو Agency
429	تم تجاوز حد المعدل	انتظر دقيقة واحدة أو زِد حد المعدل
500	خطأ في الخادم	أعد المحاولة أو تواصل مع الدعم

تنسيق الخطأ القياسي

{
  "error": "Message descriptif de l'erreur",
  "creditsNeeded": 5  // (optionnel) crédits nécessaires
}

تحديد المعدل (Rate limiting)

الحدود الافتراضية هي:

مفاتيح API: قابلة للضبط لكل مفتاح (1-1000 طلب/دقيقة، الافتراضي 60)
Bearer Token: 100 طلب/دقيقة إجمالي
نقاط الذكاء الاصطناعي (النص، الصور، الموسيقى): 10 طلبات/دقيقة
توليد الفيديو: 3 عمليات متزامنة كحد أقصى لكل حساب