توثيق API

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

المحتويات

المصادقة الأرصدة فيديو الذكاء الاصطناعي (LTX/Wan)تكامل 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
curl -X POST https://viffly.app/api/login \
  -H "Content-Type: application/json" \
  -d '{"email":"vous@email.com","password":"..."}'

# Réponse : { "token": "eyJhbG..." }

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

تنتهي صلاحية Bearer Tokens بعد7 أيام. مفاتيح API (vf_...) لها مدة صلاحية قابلة للضبط وهي موصى بها للإنتاج.

نظام الأرصدة

تستهلك كل عملية ذكاء اصطناعي أرصدة (تكلفة ثابتة للوظائف العادية، وبحسب المدة لفيديو الذكاء الاصطناعي). العمليات المجانية (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": 150 }, ...
  ],
  "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, ... }
}

توليد الفيديو بالذكاء الاصطناعي (LTX 2.3 / Wan 2.2)

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

⚡ LTX 2.3 (افتراضي)

سريع (~30-60 ثانية/مقطع)، MP4 + صوت أصلي.model: "ltx"

🎬 Wan 2.2

أكثر سينمائية (~3-5 دقائق/مقطع)، ×2 رصيد.model: "wan22"

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

GET/api/ltx/pricing

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

الاستجابة

{
  "tiers": [
    { "id": "tier1", "label": "480p · 5s",  "resolution": "480p",  "seconds": 5,  "credits": 5 },
    { "id": "tier2", "label": "720p · 5s",  "resolution": "720p",  "seconds": 5,  "credits": 10 },
    { "id": "tier3", "label": "720p · 10s", "resolution": "720p",  "seconds": 10, "credits": 15 },
    { "id": "tier4", "label": "720p · 15s", "resolution": "720p",  "seconds": 15, "credits": 22 },
    { "id": "tier5", "label": "720p · 20s", "resolution": "720p",  "seconds": 20, "credits": 30 },
    { "id": "tier6", "label": "1080p · 10s","resolution": "1080p", "seconds": 10, "credits": 32 },
    { "id": "tier7", "label": "1080p · 15s","resolution": "1080p", "seconds": 15, "credits": 48 },
    { "id": "tier8", "label": "1080p · 20s","resolution": "1080p", "seconds": 20, "credits": 65 }
  ],
  "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…tier8 (الدقة × المدة). الافتراضي: tier2
model	string	"ltx" (افتراضي، سريع) أو "wan22" (سينمائي، ×2 cr.)
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": "ltx",
    "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": "wan22",
    "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":"ltx","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.

تكامل 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": "ltx",
  "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" لتعليق ElevenLabs الصوتي (+4 cr.)
voice_id	string	معرّف صوت ElevenLabs
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.مصادقة

يولّد موسيقى خلفية عبر Suno AI.

جسم الطلب

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

الاستجابة

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

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

GET/api/elevenlabs/voicesمصادقة

يسرد أصوات ElevenLabs المتاحة (تخزين مؤقت لمدة ساعة).

الاستجابة

{ "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مصادقة

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

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 عمليات متزامنة كحد أقصى لكل حساب