Clip MasterClipMaster

ClipMaster API

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

تفضّل النص العادي؟ اقرأ هذه الصفحة بصيغة Markdown — مصممة للنماذج اللغوية والوكلاء. تستخدم Claude؟ اربط خادم MCP بدل استدعاء نقاط النهاية يدويًا.

نظرة عامة

استخدم ClipMaster برمجيًا بمفتاح API. كل نقطة نهاية تعمل تمامًا كما في التطبيق، ضمن مشاريعك ومقاطعك فقط. الوصول إلى API متاح في الخطط المدفوعة.

عنوان URL الأساسي:

https://api.clipmaster.app/api/v1

المصادقة

أنشئ مفتاحًا في التطبيق من الإعدادات ← الوصول إلى API. يظهر المفتاح كاملًا (cm_live_…) مرة واحدة عند إنشائه — احفظه في مكان آمن. أرسله كـ Bearer token في ترويسة Authorization:

curl https://api.clipmaster.app/api/v1/projects \
  -H "Authorization: Bearer cm_live_xxxxxxxxxxxxxxxxxxxx"
  • في الترويسة فقط. لا تُقبل المفاتيح كمعامل استعلام ?token=.
  • المفتاح مرتبط بحسابك ويتصرف باسمك، ضمن بياناتك فقط.
  • ألغِ أي مفتاح في أي وقت من الإعدادات؛ والمفتاح الملغى يتوقف عن العمل فورًا.
تبقى مسارات إدارة الحساب في التطبيق. يُرجع المفتاح 403 session_auth_required لتسجيل الدخول/OAuth، الفوترة والدفع (يُسمح بقراءة رصيد التوكن والاستخدام)، الإدارة، إدارة مفتاح API، وربط قناة اجتماعية. اربط قناتك في تطبيق الويب أولاً — كل شيء آخر قابل للبرمجة.

بعض نقاط النهاية هي ميزات خطة مدفوعة، ومُشار إليها أدناه باسم الميزة (على سبيل المثال compilation). في خطة بدونها، تُجيب 403 subscription_required مع تلك feature.

حدود الطلبات

120 طلبًا في الدقيقة لكل مفتاح. تجاوز الحد يعيد 429 مع ترويسة Retry-After.

تخضع نقاط نهاية الذكاء الاصطناعي (الاقتراحات، التحرير التلقائي، قياس الصوت، الترتيب) أيضًا لقيودها الخاصة لكل مستخدم وتجيب 429 بنفس الطريقة.

بداية سريعة

استورد فيديو من YouTube، وانتظر المعالجة، ثم اعرض المقاطع ونزّلها. اضبط هذه المتغيرات مرة واحدة في الطرفية:

KEY="cm_live_xxxxxxxxxxxxxxxxxxxx"
BASE="https://api.clipmaster.app/api/v1"
1استورد فيديو عبر الرابط

الطلب

curl -X POST "$BASE/upload/from-url" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

جسم الطلب

{
  "source_url": "https://youtube.com/watch?v=..."
}

الاستجابة

{
  "project_id": 123,
  "task_id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "message": "Processing started",
  "progress_url": "/api/v1/projects/123/status"
}
2استعلم عن الحالة حتى الاكتمال

الطلب

curl "$BASE/projects/123/status" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "project_id": 123,
  "status": "completed",
  "progress": 1.0,
  "progress_percent": 100,
  "total_clips": 6,
  "processing_complete": true
}
3اعرض المقاطع المُنشأة

الطلب

curl "$BASE/projects/123/clips" \
  -H "Authorization: Bearer $KEY"

الاستجابة

[
  {
    "clip_id": 456,
    "start_time": 0.0,
    "end_time": 42.3,
    "description": "Founder explains the pivot",
    "status": "ready"
  }
]
4صدّره ثم نزّله

الطلب

# Render it (charges tokens) -> {"export_id": 37, "status": "rendering", ...}
curl -X POST "$BASE/projects/123/clips/456/export" \
  -H "Authorization: Bearer $KEY"


# Poll until "status" is "completed"
curl "$BASE/exports/37/status" -H "Authorization: Bearer $KEY"


# The clip's exports, newest first
curl "$BASE/exports?clip_id=456" -H "Authorization: Bearer $KEY"


# Download from the newest completed export's download_url
curl -L "$DOWNLOAD_URL" -o clip.mp4

التنزيل هو دائمًا تصدير: المقطع مُصيَّرًا بترجماته وتأثيراته وقصّه المحفوظة. download_url رابط S3 موقَّع صالح حتى الساعة 00:00 UTC التالية (30 دقيقة على الأقل) — دون ترويسة مصادقة. استدعِ GET /exports مجددًا للحصول على رابط جديد.

الرفع

للملفات، استخدم تدفق التحميل ذو الخطوتين؛ لـ YouTube، استورد بواسطة URL. كلاهما يأخذ نفس الحقول الاختيارية: processing_mode (تلقائي، دلالي أو فيديو كامل)، query، min_duration، orientation، علامات التسمية التوضيحية، و compilation_format مع compilation_prompt لبناء تجميع بمجرد أن تصبح المقاطع جاهزة. يستغرق المعالجة 1 توكن لكل دقيقة مصدر.

POST/upload/from-url

استورد رابط YouTube. تبدأ المعالجة فورًا؛ استعلم عن حالة المشروع المُرجع. مدفوع: youtube_import.

الطلب

curl -X POST "$BASE/upload/from-url" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

جسم الطلب

{
  "source_url": "https://youtube.com/watch?v=...",
  "orientation": "vertical",
  "compilation_format": "auto"
}

الاستجابة

{
  "project_id": 123,
  "task_id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "message": "Processing started",
  "metadata": { "duration_sec": 212.4, "resolution": "1920x1080" },
  "progress_url": "/api/v1/projects/123/status"
}
POST/uploads/init

الخطوة 1 من رفع ملف. تعيد وجهة رفع قصيرة الصلاحية: أرسل الملف بـ POST إلى upload.url مع upload.fields المُعادة كما هي، ثم استدعِ complete.

الطلب

curl -X POST "$BASE/uploads/init" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

جسم الطلب

{
  "filename": "talk.mp4",
  "size_bytes": 94371840,
  "sha256": "e3b0c44298fc1c14...",
  "duration_sec": 693.5,
  "content_type": "video/mp4"
}

الاستجابة

{
  "project_id": 124,
  "upload": {
    "url": "https://uploads.clipmaster.app",
    "fields": {
      "...": "opaque form fields - send them back unchanged"
    }
  },
  "expires_at": "2026-08-14T21:00:00Z"
}
POST/uploads/{project_id}/complete

الخطوة 2: أكّد انتهاء الرفع وابدأ المعالجة.

الطلب

curl -X POST "$BASE/uploads/124/complete" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "project_id": 124,
  "task_id": "b2c3d4e5-...",
  "message": "Processing started",
  "progress_url": "/api/v1/projects/124/status"
}
POST/uploads/assets

حمّل شعارًا، تعليقًا صوتيًا أو ملف مشهد تجميع بدون متصفح. purpose هو logo، narration، scene_video أو scene_image (الاثنان الأخيران مدفوعان: compilation). أرسل حقول POST المُرجعة، ثم الملف أخيرًا، إلى upload.url في غضون 15 دقيقة، ثم استخدم asset_key في /users/me/logo/from-upload، /projects/{id}/clips/{clip_id}/logo/from-upload، /compilations/{id}/narration/from-upload أو /compilations/{id}/media-scenes (باسم upload_key).

الطلب

curl -X POST "$BASE/uploads/assets" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"purpose": "logo", "content_type": "image/png", "size_bytes": 20480}'

الاستجابة

{
  "asset_key": "originals/staging/42/9f1c2b7e.png",
  "upload": {
    "url": "https://s3.amazonaws.com/...",
    "fields": { "...": "opaque form fields - send them back unchanged" }
  },
  "expires_at": "2026-09-11T21:15:00Z"
}

الحالة والمقاطع

GET/projects/{id}/status

استعلم عن تقدم المعالجة. قيمة status واحدة من: uploading، uploaded، processing، completed، failed.

الطلب

curl "$BASE/projects/123/status" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "project_id": 123,
  "status": "processing",
  "progress": 0.45,
  "progress_percent": 45,
  "current_step": "Transcription",
  "total_scenes": 8,
  "total_clips": 0,
  "processing_complete": false
}
GET/projects/{id}/clips

اعرض المقاطع المُنشأة مع بياناتها الوصفية من الذكاء الاصطناعي (الخطّاف، نوع المقطع، الثقة).

الطلب

curl "$BASE/projects/123/clips" \
  -H "Authorization: Bearer $KEY"

الاستجابة

[
  {
    "clip_id": 456,
    "start_time": 0.0,
    "end_time": 42.3,
    "description": "Founder explains the pivot",
    "display_name": null,
    "status": "ready",
    "source": "Clipmaster",
    "streaming_url": "https://clipmaster-media.s3.amazonaws.com/...mp4?...",
    "features": {
      "scene_id": 2265,
      "clip_duration": 42.3,
      "vision_analysis": {
        "hook": "The moment everything changed",
        "clip_type": "story",
        "confidence": 0.9
      }
    }
  }
]
GET/projects/{id}/clips/{clip_id}

تفاصيل كاملة لمقطع واحد — مجموعة شاملة من عنصر القائمة: كل حقل ميزة، تحليل الذكاء الاصطناعي للمشهد، حشوته، شارةه وانتشاره. كل إطار، الصوت والكلمات موجودة في GET …/analysis.

الطلب

curl "$BASE/projects/123/clips/456" \
  -H "Authorization: Bearer $KEY"

بنفس شكل عنصر القائمة أعلاه، مع كائن features كاملًا.

GET/projects

اعرض مشاريعك.

الطلب

curl "$BASE/projects" -H "Authorization: Bearer $KEY"

الاستجابة

[
  {
    "project_id": 123,
    "filename": "keynote.mp4",
    "status": "completed",
    "created_at": "2026-08-14T20:11:38Z",
    "video_metadata": {
      "duration_sec": 693.5,
      "resolution": "1920x1080",
      "detected_orientation": "horizontal"
    },
    "is_demo": false
  }
]
DELETE/projects/{id}

احذف مشروعًا مع كل مقاطعه ومشاهده وملفاته.

الطلب

curl -X DELETE "$BASE/projects/123" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "project_id": 123,
  "success": true,
  "message": "Project deleted"
}
POST/projects/{id}/transcription

أعد نسخ الفيديو بأكمله، في الخلفية. المقاطع التي تحتوي على كلماتها المحررة الخاصة بها تحتفظ بها. استعلم عن الحالة لـ project_config.transcription_rerun_status. لا توكنات؛ محدودة بمعدل.

الطلب

curl -X POST "$BASE/projects/123/transcription" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "project_id": 123,
  "status": "running",
  "progress_url": "/api/v1/projects/123/status"
}

التحليل

اقرأ التحليل، كـ JSON، لوضع تعديل على ما وجده. تستخدم مستندات المقطع وقت المشاهد — ساعة التراكبات والاقتراحات والتحرير التلقائي: ثوانٍ من بداية مشهده. يتم تشغيل المقطع من 0 إلى time.duration؛ الأوقات خارج ذلك هي المساحة المحيطة بالمشهد، حيث لا يمكن وضع التراكبات. تحتفظ قائمة اللحظات بما يتم تشغيله فقط، لذا يمكن وضع كل t كما هي؛ من تحليل المقطع الكامل، ضع الأوقات بين 0 و time.duration فقط. ثواني الفيديو = t + time.scene_start. يستخدم مستند الفيديو الثواني من بداية التحميل. الصناديق هي كسور {x, y, w, h} من الإطار. القراءة مجانية وتعمل على المشروع التجريبي.

GET/projects/{id}/clips/{clip_id}/analysis

تحليل المقطع المخزن بالكامل. الأقسام: scene (الوصف، الخطاف، الموضوع، النوع، النتيجة، الشارة، الانتشار)، layout (قصات الكاميرا، ولكل إطار، نوع اللقطة، الوجوه ولوحات الشاشة/كاميرا الويب)، audio (صوت عالٍ، هادئ، إيقاع، غناء؛ onsets=true يضيف كل ضربة)، transcript (كلمات المقطع، مع المتحدثين عند معرفتهم)، sound_events (ضحك، تصفيق، موسيقى)، video_moments، talk_scenes و auto_edit (اللقطة المخزنة، مع نطاقات سرعتها). include يختار الأقسام، مفصولة بفاصلة؛ الكل افتراضيًا.

الطلب

curl "$BASE/projects/123/clips/456/analysis?include=scene,layout,audio" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "project_id": 123,
  "clip_id": 456,
  "scene_id": 2265,
  "time": {
    "clock": "viewer",
    "unit": "seconds",
    "note": "0 = scene start, …",
    "duration": 10.0,
    "scene_start": 100.0,
    "scene_end": 110.0,
    "clip_start": -2.0,
    "clip_end": 12.0
  },
  "analyses": {
    "layout": {
      "status": "completed",
      "error": null,
      "step": null,
      "started_at": "2026-10-22T18:02:11+00:00",
      "finished_at": "2026-10-22T18:02:40+00:00",
      "what": "Faces, screen/webcam/gameplay panels, shot type per frame, camera cuts.",
      "rest": "POST /api/v1/projects/123/clips/456/layout-analysis",
      "mcp": "analyze_clip_layout",
      "cost": "Paid plans (smart crop); no tokens."
    },
    "audio_cues": { "status": "completed", "...": "same fields" },
    "auto_edit": { "status": null, "...": "same fields" }
  },
  "scene": {
    "description": "He grabs the rim and the crowd erupts",
    "hook": "The dunk nobody saw coming",
    "topic": "basketball",
    "clip_type": "reaction",
    "score": 8,
    "...": "the rest of its stored AI fields",
    "badge": { "label": "Highlight", "key": "highlight", "color": "#FF6B6B" },
    "virality": { "tier": "hot", "label": "Hot", "color": "#FF4444" }
  },
  "layout": {
    "current": true,
    "faces_placeable": true,
    "analyzed_at": "2026-10-22T18:02:40+00:00",
    "model": "gemini-3.5-flash-lite",
    "frame_interval": 2.0,
    "frame_size": { "width": 1920, "height": 1080 },
    "cuts": [4.0],
    "frames": [
      { "t": 0.0, "shot": "solo_talking_head",
        "faces": [{ "x": 0.4, "y": 0.1, "w": 0.2, "h": 0.4 }], "panels": [] },
      { "t": 4.0, "shot": "screen_share_with_webcam",
        "faces": [{ "x": 0.8, "y": 0.04, "w": 0.12, "h": 0.18 }],
        "panels": [{ "kind": "webcam_overlay", "x": 0.75, "y": 0.0, "w": 0.25, "h": 0.25,
                     "highlighted": true }] }
    ]
  },
  "audio": {
    "current": true,
    "measured_at": "2026-10-22T18:01:05+00:00",
    "has_audio": true,
    "median_active_db": -20.0,
    "loud": [{ "t": 4.0, "end": 4.5, "over_db": 9.0 }],
    "quiet": [{ "start": -2.0, "end": -0.5, "level_db": -48.0 }],
    "beat": [{ "start": 0.0, "end": 10.0, "tempo_bpm": 120.0, "first_beat": 0.1, "period": 0.5 }],
    "singing": null
  }
}

time و analyses موجودان دائمًا. تحتوي analyses على إدخال واحد لكل تشغيل حسب الطلب (layout، audio_cues، auto_edit): status قيد التشغيل، مكتمل، فاشل، قديم (تم وضع علامة قيد التشغيل لأكثر من 30 دقيقة، لذا من المحتمل أنه توقف — تحقق مرة أخرى قبل إعادة تشغيله) أو null (لم يتم تشغيله مطلقًا)، مع error، step (الخطوة الأخيرة التي تم الوصول إليها؛ ذات معنى أثناء التشغيل)، الطوابع الزمنية ونقطة النهاية التي تبدأه. layout، audio و auto_edit هي null حتى يتم تشغيلها؛ sound_events، video_moments و talk_scenes هي [] عندما لا يتم العثور على شيء. current: false يعني أن النتيجة لم تعد تتطابق مع المقطع: تم قص ملف الفيديو الخاص به مرة أخرى منذ ذلك الحين (القص وحده لا يغيره)، بالنسبة لـ layout أيضًا عندما لم يكتمل آخر تشغيل، بالنسبة لـ audio أيضًا عندما تغير القياس نفسه. القص يجعل auto_edit current: false، نظرًا لأن أوقاته على ساعة المشهد؛ قراءة أقدم لم تسجل مشهدها current: null (غير معروف). يتم تحويل أوقات الصوت من الملف الذي تم قياسها عليه. القسم غير المعروف هو 400 unknown_section.

GET/projects/{id}/clips/{clip_id}/moments

المقطع كقائمة واحدة مرتبة زمنيًا من {t, kind, source, …}: cut، shot و faces (عندما يتغير عدد اللقطات أو الوجوه)، أدوار speaker، sound، loud، quiet، beat، singing و moments من تمرير الرؤية. يتم سرد ما يتم تشغيله فقط — تم قص الامتدادات إلى 0–time.duration، لقطة، عدد وجوه أو مجموعة متحدثين في المساحة المحيطة التي تم نقلها إلى 0، أي شيء آخر في المساحة المحيطة تم تركه — لذا فإن كل t يذهب إلى POST …/overlays كما هو. يتم حذف تحليل التخطيط أو الصوت الذي لم يعد يتطابق مع المقطع ويتم تسميته في stale. مع summary للمشهد، ما هي التحليلات available، و analyses. نفس ساعة تحليل المقطع.

الطلب

curl "$BASE/projects/123/clips/456/moments" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "project_id": 123,
  "clip_id": 456,
  "time": { "clock": "viewer", "duration": 10.0, "...": "as in …/analysis" },
  "summary": {
    "description": "He grabs the rim and the crowd erupts",
    "hook": "The dunk nobody saw coming",
    "topic": "basketball",
    "clip_type": "reaction",
    "score": 8
  },
  "available": { "layout": true, "audio": true, "transcript": true, "video_moments": true },
  "stale": [],
  "analyses": { "...": "as in …/analysis" },
  "moments": [
    { "t": 0.0, "kind": "beat", "source": "audio", "end": 10.0, "tempo_bpm": 120.0 },
    { "t": 0.0, "kind": "faces", "source": "layout", "count": 1 },
    { "t": 0.0, "kind": "shot", "source": "layout", "detail": "solo_talking_head" },
    { "t": 0.0, "kind": "speaker", "source": "transcript", "speaker": "speaker_0", "first_word": "Here" },
    { "t": 1.0, "kind": "moment", "source": "video", "end": 3.0, "detail": "action_peak",
      "score": 8, "description": "Rim grab" },
    { "t": 3.0, "kind": "sound", "source": "transcript", "end": 4.0, "detail": "laughter" },
    { "t": 4.0, "kind": "cut", "source": "layout" },
    { "t": 4.0, "kind": "loud", "source": "audio", "end": 4.5, "over_db": 9.0 },
    { "t": 4.0, "kind": "shot", "source": "layout", "detail": "screen_share_with_webcam" }
  ]
}
GET/projects/{id}/analysis

الفيديو بأكمله، على وقت الفيديو: metadata، transcript حسب المقطع مع المتحدثين، sound_events، video_moments من تمرير الرؤية و talk_scenes من تمرير النص (كل منها مع …_status وكتلة …_pass: حالة النموذج وتمريره، بالإضافة إلى خطأ ووقت تمرير الرؤية)، وكل مشهد مع خطافه ودرجته وعلامة degraded (صحيح: فشلت خطوة مشهد الذكاء الاصطناعي وهو بديل ثابت الطول غير مسجل). include يختار الأقسام؛ words (كل كلمة، مع المتحدث والثقة) يأتي فقط عند تسميته. analyses.transcription يبلغ عن إعادة النسخ.

الطلب

curl "$BASE/projects/123/analysis" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "project_id": 123,
  "time": { "clock": "video", "unit": "seconds", "note": "Seconds from the start of the upload." },
  "analyses": {
    "transcription": {
      "status": null,
      "...": "same fields as a clip's runs",
      "rest": "POST /api/v1/projects/123/transcription",
      "mcp": "transcribe_video"
    }
  },
  "metadata": { "duration_sec": 693.5, "resolution": "1920x1080", "detected_orientation": "horizontal",
                "...": "the rest of the upload's metadata" },
  "transcript": {
    "language": "english",
    "provider": "openai_whisper",
    "duration": 693.5,
    "no_audio": false,
    "speakers": [],
    "segments": [{ "start": 99.0, "end": 106.0, "text": "Here we go.", "speaker": null }]
  },
  "sound_events": [{ "t": 103.0, "end": 104.0, "kind": "laughter", "label": "[laughter]",
                     "speaker": null, "confidence": null }],
  "video_moments": [{ "start": 101.0, "end": 103.0, "type": "action_peak", "score": 8,
                      "description": "Rim grab" }],
  "video_moments_status": "ok",
  "video_moments_pass": { "status": "ok", "error": null, "model": "gemini-3.8-flash",
                          "analyzed_at": "2026-10-22T17:40:12+00:00" },
  "talk_scenes": [{ "start": 95.0, "end": 105.0, "clip_type": "story", "score": 7,
                    "hook": "Why he almost quit", "topic": "basketball",
                    "description": "He tells how the season started", "confidence": 0.8 }],
  "talk_scenes_status": "ok",
  "talk_scenes_pass": { "status": "ok", "model": "gpt-4o-mini" },
  "scenes": [{ "scene_id": 2265, "start": 100.0, "end": 110.0, "source": "merged",
               "description": "He grabs the rim and the crowd erupts",
               "hook": "The dunk nobody saw coming", "topic": "basketball",
               "clip_type": "reaction", "score": 8, "degraded": false }]
}
POST/projects/{id}/clips/{clip_id}/audio-cues

قم بقياس صوت المقطع — اللحظات الصاخبة، الامتدادات الهادئة، الإيقاع والسرعة، الغناء — في الخلفية. استعلم GET …/analysis حتى يصبح analyses.audio_cues.status مكتملًا أو فاشلاً؛ النتيجة هي قسم audio الخاص به. تقترح ميزة الاقتراح والتحرير التلقائي قياسه بنفسها؛ اتصل بهذا لقراءة الصوت أولاً. 409 audio_cues_running، audio_cues_current (القياس المخزن لا يزال يتطابق مع ملف المقطع) أو clip_file_missing. مدفوع: ai_suggestions؛ لا توكنات؛ يشارك حد معدل مع اقتراح التأثيرات والتحرير التلقائي.

الطلب

curl -X POST "$BASE/projects/123/clips/456/audio-cues" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "project_id": 123,
  "clip_id": 456,
  "status": "running"
}

التحرير

كل ما يفعله المحرر داخل التطبيق قابل للبرمجة: القص، التسميات التوضيحية وترجمتها، التخطيطات، التكبير، تأثيرات الشاشة، السرعة، الإيموجي، صور GIF، الملصقات، مقاطع التفاعل، المؤثرات الصوتية، الشعار، شريط التقدم والاتجاه.

ساعتان. التراكبات التي تضيفها (POST …/overlays) وكل اقتراح يستخدم وقت المشاهد — ثوانٍ من بداية المقطع كما يتم تشغيله. تحتفظ الإعدادات المحفوظة بالأوقات مقابل ملف المقطع المبطن، أطول ببضع ثوانٍ في كل طرف؛ تقوم نقطة نهاية التراكبات بالتحويل لك.

PUT/projects/{id}/scenes/{scene_id}/boundaries

القص — حرّك بداية المقطع/نهايته. تُحدَّث كل مقاطع المشهد تلقائيًا.

الطلب

curl -X PUT "$BASE/projects/123/scenes/2265/boundaries" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

جسم الطلب

{
  "new_start_time": 12.0,
  "new_end_time": 27.5
}

الاستجابة

{
  "scene_id": 2265,
  "project_id": 123,
  "old_start_time": 0.0,
  "old_end_time": 42.3,
  "new_start_time": 12.0,
  "new_end_time": 27.5,
  "message": "Scene boundaries updated successfully."
}
GET · PUT/projects/{id}/clips/{clip_id}/settings

اقرأ أو حدّث حالة المحرر الكاملة: التسميات التوضيحية (مع secondary لسطر ثانٍ)، الإيموجي، صور GIF، الملصقات ومقاطع التفاعل (gifs، مميزة بواسطة kind)، المؤثرات الصوتية، التكبير، تأثيرات الشاشة، التأطير، الشعار، شريط التقدم، الاتجاه، speed و speedRanges. PUT يستبدل الكائن بأكمله — أعد كل ما أرجعه GET، مع تغييراتك؛ أي شيء يُترك يتم مسحه.

الطلب

curl -X PUT "$BASE/projects/123/clips/456/settings" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

جسم الطلب

{
  "orientation": "vertical",
  "captions": {
    "enabled": true,
    "style": "hormozi",
    "karaoke": true
  },
  "speed": 1.25
}

الاستجابة

{
  "clip_id": 456,
  "settings": {
    "captions": { "enabled": true, "style": "hormozi", "karaoke": true },
    "zoom": null,
    "screenEffects": null,
    "logo": null,
    "progressBar": null,
    "smartCrop": null,
    "gifs": null,
    "orientation": "vertical",
    "speed": 1.25,
    "speedRanges": null
  }
}

التكبير هو شكل واحد: {type: "zoom", start, end, scale, glide, target, center} — يدخل عند start (ثواني glide للوصول إلى هناك، 0 يلتقط)، يُحتفظ به عند scale (1.05–2.5)، يعود عند end، أو يُحتفظ به حتى نهاية المقطع عندما يكون end فارغًا. يتم تحويل التكبيرات القديمة السريعة والبطيئة.

GET · PUT/projects/{id}/clips/{clip_id}/captions

اقرأ كلمات الترجمة أو استبدلها مع توقيت كل كلمة.

الطلب

curl -X PUT "$BASE/projects/123/clips/456/captions" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

جسم الطلب

{
  "words": [
    { "text": "Use", "start": 28.06, "end": 28.14 },
    { "text": "correct", "start": 28.14, "end": 28.22 }
  ]
}

الاستجابة

{
  "words": [
    { "text": "Use", "start": 28.06, "end": 28.14, "highlight": null },
    { "text": "correct", "start": 28.14, "end": 28.22, "highlight": null }
  ]
}
PATCH/projects/{id}/clips/{clip_id}/name

أعد تسمية مقطع. النص الفارغ يعيده إلى الاسم المُنشأ تلقائيًا.

الطلب

curl -X PATCH "$BASE/projects/123/clips/456/name" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

جسم الطلب

{
  "name": "Best hook"
}

الاستجابة

{
  "clip_id": 456,
  "display_name": "Best hook"
}
POST/projects/{id}/clips/{clip_id}/transcribe

أعد نسخ صوت هذا المقطع واجعل النتيجة تسمياته التوضيحية. يستبدل الكلمات المحررة؛ يُجيب بالكلمات الجديدة. لا توكنات؛ محدودة بمعدل.

الطلب

curl -X POST "$BASE/projects/123/clips/456/transcribe" \
  -H "Authorization: Bearer $KEY"
POST/projects/{id}/clips/{clip_id}/overlays

أضف تراكبات في الوقت الذي يراه المشاهد: emojis، inline_emojis، gifs، stickers، reaction_clips، sfx، zooms، screen_effects و speed_ranges. يتم تطبيق تحويل وقت المحرر والإعدادات الافتراضية لك، ويمكن إرسال اقتراحات الذكاء الاصطناعي كما جاءت. يضيف فقط.

الطلب

curl -X POST "$BASE/projects/123/clips/456/overlays" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

جسم الطلب

{
  "emojis": [{ "emoji": "🔥", "timestamp": 12.0 }],
  "inline_emojis": [{ "emoji": "💰", "word_index": 5 }],
  "gifs": [{ "source_id": "k1", "slug": "mind-blown", "mp4_url": "https://…",
             "width": 480, "height": 270, "timestamp": 8.0 }],
  "sfx": [{ "sfx_id": 3, "timestamp": 3.0, "volume": 0.4 }],
  "zooms": [{ "start": 20.0, "length": 1.0, "scale": 1.3 }],
  "screen_effects": [{ "look": "flash", "start": 20.0 }],
  "speed_ranges": [{ "start": 31.0, "length": 2.5, "speed": 2.0 }]
}

الاستجابة

{
  "clip_id": 456,
  "settings": {
    "emojis": [
      { "type": "floating", "emoji": "🔥", "timestamp": 14.0, "duration": 1.0,
        "position": { "x": 0.5, "y": 0.694 }, "scale": 1.0 }
    ],
    "zoom": [
      { "type": "zoom", "start": 22.0, "end": 23.0, "scale": 1.3, "glide": 0,
        "target": "frame", "center": { "x": 0.5, "y": 0.5 } }
    ]
  }
}

يحتوي المقطع على ما يصل إلى 5 صور متحركة، 5 ملصقات و 5 مقاطع رد فعل. spot على إيموجي أو ملصق يتبع الوجه الرئيسي، و target: "face" على تكبير يركز عليه — مدفوع (smart_crop)، بعد تحليل تخطيط المقطع.

GET · POST/projects/{id}/clips/{clip_id}/translations

سطر تسمية توضيحية ثانٍ بلغة أخرى. GET يسرد اللغات التي يمتلكها هذا المقطع بالفعل واللغات المدعومة؛ POST {"language": "es"} يترجمه — 1 توكن، مجاني عندما يمتلكه المقطع بالفعل. مدفوع: caption_translation. يظهر بمجرد تعيين captions.secondary في الإعدادات.

الطلب

curl -X POST "$BASE/projects/123/clips/456/translations" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"language": "es"}'

الاستجابة

{
  "project_id": 123,
  "language": "es",
  "lines": [{ "text": "Usa la palabra correcta", "start": 28.06, "end": 29.4 }],
  "created": true,
  "tokens_charged": 1
}
POST/projects/{id}/clips/{clip_id}/layout-analysis

تحليل ما يظهره كل لحظة من المقطع — أنواع اللقطات، الوجوه، لوحات الشاشة وكاميرا الويب — في الخلفية. مطلوب قبل أن تتمكن التراكبات من تتبع الوجه. استعلم عن المقطع لـ features.vision_analysis.layout_rerun_status، أو GET …/analysis لـ analyses.layout.status؛ كل إطار هو قسم layout الخاص به. مدفوع: smart_crop؛ لا توكنات.

الطلب

curl -X POST "$BASE/projects/123/clips/456/layout-analysis" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "project_id": 123,
  "clip_id": 456,
  "status": "running"
}
POST · DELETE/projects/{id}/clips/{clip_id}/logo

حمّل (متعدد الأجزاء، حقل file) أو أزل شعارًا لكل مقطع. بدون متصفح، قم بتجهيزه باستخدام POST /uploads/assets وارفقه في …/logo/from-upload.

الطلب

curl -X POST "$BASE/projects/123/clips/456/logo/from-upload" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset_key": "originals/staging/42/9f1c2b7e.png"}'

اقتراحات الذكاء الاصطناعي والتعديل التلقائي

الاقتراحات للقراءة فقط: تُرجع مواضع في وقت المشاهد، جاهزة للإرسال إلى POST …/overlays كما جاءت. مدفوعة: ai_suggestions. لا توكنات؛ محدودة بمعدل.

POST/projects/{id}/clips/{clip_id}/{kind}/suggest

اقتراحات لمقطع واحد. kind هو gifs، stickers، reaction-clips، emojis، sfx، effects (وصفات التكبير وتأثيرات الشاشة) أو speed (الهواء الميت مسرع، حركة بطيئة). معلمة الاستعلام max_suggestions.

الطلب

curl -X POST "$BASE/projects/123/clips/456/gifs/suggest?max_suggestions=3" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "clip_id": 456,
  "suggestions": [
    {
      "source_id": "k1",
      "slug": "mind-blown",
      "title": "Mind Blown",
      "mp4_url": "https://…",
      "width": 480,
      "height": 270,
      "preview_url": "https://…",
      "timestamp": 8.0,
      "duration": 2.0,
      "query": "mind blown",
      "reason": "Reacts to the reveal"
    }
  ]
}

تُجيب effects و speed بـ audio_cues_ready: false بينما لا يزال صوت المقطع قيد القياس — اسأل مرة أخرى بعد بضع ثوانٍ. اقتراح السرعة هو {start, end, speed}: أرسله بـ length = end − start.

POST/projects/{id}/clips/{clip_id}/auto-edit

خطط لتعديل كامل للمقطع — تكبيرات، تأثيرات الشاشة، ملصقات، أصوات ونطاقات سرعة — في الخلفية. استعلم عن المقطع لـ features.vision_analysis.auto_edit_rerun_status؛ التعديل هو features.vision_analysis.auto_edit ({effects, stickers, sfx, speed}، وأيضًا قسم auto_edit من GET …/analysis). لا يتم تطبيق أي شيء: أرسل أجزائه إلى POST …/overlays. مدفوع: ai_suggestions؛ لا توكنات.

الطلب

curl -X POST "$BASE/projects/123/clips/456/auto-edit" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "project_id": 123,
  "clip_id": 456,
  "status": "running"
}

التصدير

POST/projects/{id}/clips/{clip_id}/export

صدّر مقطعًا بإعداداته المحفوظة. يعيد معرّف تصدير للاستعلام عنه؛ ويخصم توكنات.

الطلب

curl -X POST "$BASE/projects/123/clips/456/export" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "export_id": 37,
  "status": "rendering",
  "message": "Export render triggered"
}
GET/exports/{export_id}/status

استعلم عن حالة تصدير. عند اكتماله، يكون download_url رابطًا مؤقتًا تنتهي صلاحيته — نزّل الملف سريعًا.

الطلب

curl "$BASE/exports/37/status" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "export_id": 37,
  "status": "completed",
  "download_url": "https://clipmaster-media.s3.amazonaws.com/...mp4?...&Expires=...",
  "created_at": "2026-08-14T21:47:35Z",
  "completed_at": "2026-08-14T21:48:42Z"
}
GET/exports

يسرد تصديراتك، الأحدث أولًا. صفِّ النتائج بـ clip_id أو project_id. هكذا تنزّل مقطعًا: خذ أحدث تصدير بحالة completed ونزّل download_url الخاص به.

الطلب

curl "$BASE/exports?clip_id=456" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "exports": [
    {
      "export_id": 37,
      "clip_id": 456,
      "project_id": 123,
      "status": "completed",
      "progress": null,
      "export_number": 2,
      "tokens_charged": 1,
      "clip_duration_sec": 42.3,
      "download_url": "https://clipmaster-media.s3.amazonaws.com/...mp4?...&Expires=...",
      "created_at": "2026-08-14T21:47:35Z",
      "completed_at": "2026-08-14T21:48:42Z"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}

التجميعات

التجميع هو تعديل واحد مبني من مقاطع من أي من فيديوهاتك. إنشاء، ترتيب وتصدير واحد مدفوع: compilation.

GET/compilations

اعرض تجميعاتك (مجموعات مقاطع من مشاريع مختلفة).

الطلب

curl "$BASE/compilations" -H "Authorization: Bearer $KEY"

الاستجابة

{
  "items": [
    {
      "id": 10,
      "name": "Funny Personal Anecdotes",
      "clip_count": 5,
      "total_duration_sec": 149.9,
      "output": { "width": 1920, "height": 1080, "fps": 30 },
      "format": null,
      "latest_export": null,
      "created_at": "2026-08-10T19:05:41Z"
    }
  ]
}
POST/compilations

أنشئ تجميعًا فارغًا. مدفوع: compilation.

الطلب

curl -X POST "$BASE/compilations" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

جسم الطلب

{
  "name": "Best of March",
  "output": { "width": 1080, "height": 1920, "fps": 30 }
}
GET · PATCH/compilations/{id}

اقرأ تجميعًا واحدًا — مقاطعه، estimated_tokens للتصدير، خطة التعديل في arrangement_metadata.edit_plan والملفات التي يتم تشغيلها في media — أو غيّر name، output، logo_config أو progress_bar_config.

الطلب

curl "$BASE/compilations/10" -H "Authorization: Bearer $KEY"
GET/compilations/{id}/deletion-preview

ما سيتم حذفه مع الحذف: التحميلات الموجودة فقط لهذا التجميع، والمنشورات المعلقة.

الطلب

curl "$BASE/compilations/10/deletion-preview" -H "Authorization: Bearer $KEY"

الاستجابة

{
  "compilation_id": 10,
  "source_project_ids": [],
  "scheduled_posts_pending": 0
}
DELETE/compilations/{id}

احذف تجميعًا؛ يتم إلغاء منشوراته المعلقة. delete_sources=true يحذف أيضًا التحميلات من المعاينة؛ مررها كـ expected_project_ids ويتم رفض الحذف (409) إذا تغيرت هذه المجموعة.

الطلب

curl -X DELETE "$BASE/compilations/10" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "compilation_id": 10,
  "deleted_project_ids": [],
  "scheduled_posts_cancelled": 0
}
GET/compilations/available-clips

مقاطعك من كل الفيديوهات، لإضافتها. معايير الاستعلام q, limit, offset.

الطلب

curl "$BASE/compilations/available-clips?q=pivot&limit=50" \
  -H "Authorization: Bearer $KEY"
POST · DELETE/compilations/{id}/clips

أضف مقطعًا (clip_id، position اختياري). DELETE /compilations/{id}/clips/{compilation_clip_id} لإزالة مقطع واحد.

الطلب

curl -X POST "$BASE/compilations/10/clips" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"clip_id": 456}'
POST/compilations/{id}/clips/suggest

المزيد من المقاطع من مكتبتك التي تناسب هذا التجميع، الأفضل أولاً.

الطلب

curl -X POST "$BASE/compilations/10/clips/suggest" \
  -H "Authorization: Bearer $KEY"
POST/compilations/suggest

أفكار تجميع من مكتبتك لملخص. حوّل إحداها إلى تجميع باستخدام POST /compilations/from-suggestion (name, clip_ids).

الطلب

curl -X POST "$BASE/compilations/suggest" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "funny moments", "max_suggestions": 3}'

الاستجابة

{
  "suggestions": [
    {
      "theme": "Funny moments",
      "reason": "Five clips where the audience laughs",
      "clip_ids": [456, 457, 461],
      "total_duration_sec": 94.2
    }
  ]
}
POST/compilations/{id}/export

اعرض التجميع. يخصم توكنز لثواني المصدر التي يتم تشغيلها (estimated_tokens على التجميع).

الطلب

curl -X POST "$BASE/compilations/10/export" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "export_id": 5,
  "compilation_id": 10,
  "status": "pending",
  "estimated_tokens": 3,
  "message": "Export started"
}
GET/compilations/{id}/exports/{export_id}/status

استعلم عن حالة تصدير التجميع؛ download_url يعمل كما هو الحال لتصدير المقطع. GET /compilations/{id}/exports يسردها.

الطلب

curl "$BASE/compilations/10/exports/5/status" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "export_id": 5,
  "compilation_id": 10,
  "status": "completed",
  "progress": null,
  "download_url": "https://clipmaster-media.s3.amazonaws.com/...mp4?...&Expires=...",
  "created_at": "2026-08-14T21:47:35Z",
  "completed_at": "2026-08-14T21:50:02Z"
}

تعديل التجميعات

التجميع هو خطة تحرير: مشاهد من لوحة واحدة إلى ثلاث لوحات (مقطع أو ملف) مع انتقالات وبطاقات نصية، بالإضافة إلى تراكبات وموسيقى وتعليق صوتي على التعديل بأكمله. الأوقات هي ثوانٍ في التجميع.

POST/compilations/{id}/arrange

أعد قص التجميع بالذكاء الاصطناعي إلى خطة مشاهد جديدة. format: مخصص (مونتاج؛ يحتاج prompt)، الأفضل، عد تنازلي، إعلان تشويقي، خطاف_حلقة، تعليمي، أبرز_أسئلة_وأجوبة أو تلقائي. يستبدل المشاهد والإيموجي والصور المتحركة المثبتة عليها؛ تبقى التسميات التوضيحية والموسيقى والتعليق الصوتي.

الطلب

curl -X POST "$BASE/compilations/10/arrange" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

جسم الطلب

{
  "format": "hook_loop"
}

الاستجابة

{
  "id": 10,
  "name": "Funny Personal Anecdotes",
  "format": "hook_loop",
  "total_duration_sec": 58.2,
  "estimated_tokens": 1,
  "clips": [
    { "compilation_clip_id": 88, "position": 0, "clip_id": 456, "duration_sec": 12.4, "missing": false }
  ],
  "arrangement_metadata": {
    "resolved_format": "hook_loop",
    "degraded": false,
    "edit_plan": {
      "version": "2.0",
      "scenes": [
        {
          "id": "1",
          "layout": "full",
          "sources": [
            { "clip_id": 456, "slot": 0, "audio": "primary",
              "start_offset_sec": 3.0, "end_offset_sec": 9.5, "speed": 1.0 }
          ],
          "text": []
        }
      ]
    }
  }
}

degraded: true يعني أن خطوة الذكاء الاصطناعي فشلت وتم الاحتفاظ بالمقاطع بالترتيب.

POST/compilations/{id}/plan/undo · reset · place-added-clips

plan/undo يعود إلى ما قبل آخر ترتيب أو إعادة تعيين أو وضع (يعيد التنفيذ مرة أخرى)؛ plan/reset ينشئ قصًا عاديًا، كل مقطع كامل؛ plan/place-added-clips يعمل على المقاطع المضافة منذ التعديل بالذكاء الاصطناعي. لا يوجد نص.

الطلب

curl -X POST "$BASE/compilations/10/plan/undo" \
  -H "Authorization: Bearer $KEY"
POST/compilations/{id}/scenes/{scene_id}/regenerate

أعد قص مشهد واحد بالذكاء الاصطناعي، مع ترك الباقي. prompt اختياري. معرفات المشاهد نصية.

الطلب

curl -X POST "$BASE/compilations/10/scenes/3/regenerate" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "use the boat clip instead"}'
PUT/compilations/{id}/scenes/{scene_id}/beat-pattern

يمنح مشهدًا واحدًا نمط إيقاع: تكرارات قصيرة صامتة لمقطعه على إيقاع الموسيقى، قبله مباشرة. pattern: stutter أو quick_stutter أو build_up أو jump_cut أو teaser، أو null لإزالته. يتطلب موسيقى مقيسة (409 music_not_measured حتى ذلك الحين).

الطلب

curl -X PUT "$BASE/compilations/10/scenes/3/beat-pattern" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"pattern": "stutter"}'
PUT/compilations/{id}/plan

استبدل خطة التعديل. التخطيطات: full (لوحة واحدة)، stack2 / cols2 / pip (2)، stack3 / cols3 (3). المصدر يشغل clip_id أو media_key؛ إزاحاته هي بداية ونهاية النافذة بالثواني في مشهد المقطع؛ مصدر واحد على الأكثر لكل مشهد هو صوت primary. الانتقالات: قص، تلاشي، انزلاق، مسح. التراكبات المتروكة تبقى؛ الموسيقى music المتروكة تُزال.

الطلب

curl -X PUT "$BASE/compilations/10/plan" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

جسم الطلب

{
  "version": "2.0",
  "scenes": [
    {
      "id": "1",
      "layout": "full",
      "sources": [{ "clip_id": 456, "audio": "primary",
                    "start_offset_sec": 2.0, "end_offset_sec": 14.5 }],
      "text": [{ "text": "Day one", "role": "title", "start_ms": 0, "duration_ms": 2000 }]
    },
    {
      "id": "2",
      "layout": "stack2",
      "transition_in": { "kind": "fade", "duration_ms": 400 },
      "sources": [
        { "clip_id": 457, "slot": 0, "audio": "primary", "speed": 1.5 },
        { "clip_id": 458, "slot": 1 }
      ]
    }
  ],
  "music": { "track_id": "a1b2c3", "volume": 0.3 }
}
POST · PATCH/compilations/{id}/plan/overlays

POST يضيف إيموجي، صور متحركة، ملصقات، تكبيرات، تأثيرات شاشة وتأثيرات صوتية على المونتاج بأكمله، بأشكال تراكبات المقطع. PATCH يستبدل مجموعة مخزنة بالكامل بدلاً من ذلك (captions, emojis, gifs, screenEffects, zoom, sfx)؛ ما ترسله فقط هو الذي يتغير.

الطلب

curl -X POST "$BASE/compilations/10/plan/overlays" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

جسم الطلب

{
  "emojis": [{ "emoji": "🎉", "timestamp": 3.0 }],
  "screen_effects": [{ "look": "bw", "start": 10.0, "length": 2.0 }]
}

الاستجابة

{
  "id": 10,
  "arrangement_metadata": {
    "edit_plan": {
      "emojis": [
        { "type": "floating", "emoji": "🎉", "timestamp": 3.0, "duration": 1.0,
          "position": { "x": 0.5, "y": 0.694 }, "scale": 1.0 }
      ]
    }
  }
}
POST/compilations/{id}/auto-edit

حرر التجميعة بأكملها دفعة واحدة وطبقها، مع ملء ما هو فارغ فقط: كيفية ظهور كل مشهد (أي انتقال متاح)، بطاقات نصية (كلمات، خط، حجم، موضع، توقيت)، مقطع صوتي من المكتبة، نطاقات سرعة على المقاطع بالسرعة العادية وشريط التقدم، بالإضافة إلى تكبيرات، تأثيرات الشاشة، ملصقات، صور GIF، إيموجي، مؤثرات صوتية وما يصل إلى مشهدين من مقاطع التفاعل. direction (اختياري، حتى 300 حرف) يوجه كل ذلك ويتم الاحتفاظ به للتشغيل التالي. أرسل take المعادة إلى …/auto-edit/undo لإزالتها، أو أعدها هنا كـ replace_take لتبديلها بواحدة جديدة. مدفوع: compilation؛ لا توجد توكنات.

الطلب

curl -X POST "$BASE/compilations/10/auto-edit" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"direction": "hype energy, big bold text"}'

الاستجابة

{
  "compilation": { "id": 10, "...": "as GET /compilations/{id}" },
  "take": {
    "scene_ids": ["r1"],
    "effect_ids": ["e1", "e2"],
    "sticker_ids": ["g1"],
    "emoji_ids": ["m1"],
    "zoom_ids": ["z1"],
    "sfx_ids": ["s1"],
    "transitions": [{ "scene_id": "2", "kind": "slide", "duration_ms": 400 }],
    "text_cards": [{ "scene_id": "1", "text": "Best of the year" }],
    "music_track_id": "lib-42",
    "speed_ranges": [{ "scene_id": "2", "slot": 0, "start": 24.0, "end": 25.2, "speed": 0.5 }],
    "progress_bar": true
  },
  "counts": { "effects": 2, "stickers": 0, "gifs": 1, "emojis": 1,
              "reaction_clips": 1, "zooms": 1, "sounds": 1, "transitions": 1,
              "texts": 1, "music": 1, "speed_ranges": 1, "progress_bar": 1 }
}
GET/compilations/{id}/audio

صوت المونتاج المقاس على توقيته الخاص: إيقاع الموسيقى (أو إيقاع مقطع مسموع)، اللحظات الصاخبة، الفترات الهادئة والغناء؛ onsets=true يضيف كل بداية صوتية. يُقاس كل صوت مرة واحدة في الخلفية، أول مرة يُقرأ فيها أو ينضم إلى المونتاج — sources يبيّن ما تم قياسه، ويبقى measuring صحيحًا حتى يُقاس الكل. تأخذ أضواء الحفلة beat_first وbeat_period وbeat_clock منه. مدفوع: compilation؛ لا توجد توكنات.

الطلب

curl "$BASE/compilations/10/audio" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "compilation_id": 10,
  "duration_sec": 37.4,
  "measuring": false,
  "sources": [
    { "kind": "music", "status": "measured", "track_id": "lib-42" },
    { "kind": "clip", "status": "measured", "scene_id": "1", "clip_id": 1621 }
  ],
  "beat": [{ "start": 12.0, "end": 37.4, "first_beat": 12.02, "period": 0.38,
             "tempo_bpm": 157.9, "clock": "edit" }],
  "loud": [{ "t": 33.0, "end": 33.4, "over_db": 11.0 }],
  "quiet": [{ "start": 3.4, "end": 9.0, "level_db": -38.0 }],
  "singing": [],
  "onsets": null
}
POST/compilations/{id}/media-scenes

أضف مشهدًا يشغل ملفًا بدلاً من مقطع: مقطع رد فعل Klipy (klipy) أو فيديو أو صورة تم تحميلها (upload_key). يأتي بعد after_scene_id، أو أخيرًا؛ into_scene_id يجعله لوحة إضافية بجانب مقاطع هذا المشهد. الفيديو المحمل يُحسب ضمن توكنز التصدير؛ مقاطع رد الفعل والصور مجانية. مدفوع: compilation.

الطلب

curl -X POST "$BASE/compilations/10/media-scenes" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

جسم الطلب

{
  "klipy": { "source_id": "c3", "slug": "emotional-damage",
             "title": "Emotional Damage", "mp4_url": "https://…" },
  "after_scene_id": "2"
}
POST · PATCH · DELETE/compilations/{id}/narration

تعليق صوتي على المونتاج بأكمله، منسوخ للتسميات التوضيحية. POST يحمله (متعدد الأجزاء، حقل file) أو يرفق واحدًا مُجهزًا في …/narration/from-upload؛ PATCH يضبط volume و duck؛ DELETE يزيله.

الطلب

curl -X POST "$BASE/compilations/10/narration/from-upload" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset_key": "originals/staging/42/5d8e1a.mp3"}'

الاستجابة

{
  "url": "https://clipmaster-media.s3.amazonaws.com/...mp3?...",
  "volume": 1.0,
  "duck": true,
  "duration_sec": 61.4,
  "word_count": 152
}
POST/compilations/{id}/music/suggest

مقاطع صوتية تناسب المونتاج، كل منها مع سبب. اختر واحدًا باستخدام POST /music/tracks/{track_id}/select، ثم اضبط music.track_id في الخطة.

الطلب

curl -X POST "$BASE/compilations/10/music/suggest" \
  -H "Authorization: Bearer $KEY"
POST/compilations/{id}/{kind}/suggest

اقتراحات للمونتاج بأكمله، في ثوانيه الخاصة: kind هو gifs، stickers أو emojis. أرسلها إلى POST …/plan/overlays. مدفوع: compilation.

الطلب

curl -X POST "$BASE/compilations/10/emojis/suggest" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "compilation_id": 10,
  "suggestions": [
    { "emoji": "😂", "timestamp": 14.2, "duration": 1.5, "reason": "The punchline lands" }
  ]
}
POST/compilations/{id}/scenes/{scene_id}/text/suggest

أسطر العنوان والتسمية لمشهد واحد.

الطلب

curl -X POST "$BASE/compilations/10/scenes/1/text/suggest" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "suggestions": [
    { "text": "Day one", "role": "title" }
  ]
}

الجدولة

انشر المقاطع والتجميعات على قناة مربوطة. تتطلب الجدولة صلاحية الجدولة على المنصات.

GET/social/accounts

قنواتك المربوطة. اربطها من تطبيق الويب أولًا.

الطلب

curl "$BASE/social/accounts" -H "Authorization: Bearer $KEY"

الاستجابة

{
  "platforms_available": ["youtube"],
  "accounts": [
    {
      "id": 2,
      "platform": "youtube",
      "account_name": "MyChannel",
      "status": "active"
    }
  ]
}
POST/scheduled-posts

جدول نشر تصدير مقطع أو تجميعة. آمن للتكرار — إعادة المحاولة بالحساب والتصدير والوقت نفسها تعيد المنشور الموجود.

الطلب

curl -X POST "$BASE/scheduled-posts" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

جسم الطلب

{
  "social_account_id": 2,
  "clip_id": 456,
  "export_id": 37,
  "scheduled_at": "2026-08-20T16:00:00Z",
  "title": "The pivot that saved us",
  "hashtags": ["startup", "founder"],
  "privacy": "public"
}

الاستجابة

{
  "id": 12,
  "clip_id": 456,
  "export_id": 37,
  "social_account_id": 2,
  "platform": "youtube",
  "account_name": "MyChannel",
  "status": "scheduled",
  "scheduled_at": "2026-08-20T16:00:00",
  "title": "The pivot that saved us"
}
GET/scheduled-posts?from_date=&to_date=

نطاق تقويمي للمنشورات المجدولة والمنشورة.

الطلب

curl "$BASE/scheduled-posts?from_date=2026-08-01T00:00:00Z&to_date=2026-08-31T23:59:59Z" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "posts": [
    {
      "id": 12,
      "status": "scheduled",
      "scheduled_at": "2026-08-20T16:00:00",
      "title": "The pivot that saved us"
    }
  ]
}
PATCH · DELETE/scheduled-posts/{id}

أعد توقيت أو عدّل منشورًا قبل نشره (scheduled_at, title, description, hashtags, privacy)، أو ألغه.

الطلب

curl -X PATCH "$BASE/scheduled-posts/12" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduled_at": "2026-08-21T16:00:00Z"}'
POST/scheduled-posts/metadata-suggest

عنوان ووصف وهاشتاجات بالذكاء الاصطناعي من نص مقطع.

الطلب

curl -X POST "$BASE/scheduled-posts/metadata-suggest" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"clip_id": 456, "platform": "youtube"}'

الاستجابة

{
  "title": "The pivot that saved us",
  "description": "How one decision turned the company around.",
  "hashtags": ["startup", "founder"]
}
DELETE/social/accounts/{id}

افصل قناة. سجل منشوراتها، المعلقة والمنشورة، يذهب معها.

الطلب

curl -X DELETE "$BASE/social/accounts/2" \
  -H "Authorization: Bearer $KEY"

المكتبة

GET/export/styles

اعرض أنماط الترجمة الـ 15 وقيمها الافتراضية.

الطلب

curl "$BASE/export/styles" \
  -H "Authorization: Bearer $KEY"

الاستجابة

[
  {
    "key": "clean",
    "name": "Clean",
    "category": "social",
    "fontFamily": "Inter",
    "fontSize": 56,
    "color": "#FFFFFF",
    "highlightColor": "#9DC34F"
  }
]
GET/sfx

مكتبة المؤثرات الصوتية؛ معرفاتها تذهب في تراكبات sfx. category اختياري.

الطلب

curl "$BASE/sfx" -H "Authorization: Bearer $KEY"
GET/gifs/search · /gifs/trending

ابحث في Klipy، أو اسرد ما هو شائع. kind هو gif، sticker أو clip (مقاطع رد الفعل). ضع نتيجة باستخدام id كـ source_id و mp4.url كـ mp4_url؛ الملصق يحتاج أيضًا image.url كـ image_url.

الطلب

curl "$BASE/gifs/search?q=mind%20blown&kind=sticker&per_page=10" \
  -H "Authorization: Bearer $KEY"

الاستجابة

{
  "items": [
    {
      "id": "s9",
      "slug": "mind-blown-sticker",
      "title": "Mind Blown",
      "kind": "sticker",
      "mp4": { "url": "https://….webm", "width": 320, "height": 320 },
      "preview": { "url": "https://….webp", "width": 160, "height": 160 },
      "image": { "url": "https://….webp", "width": 320, "height": 320 }
    }
  ],
  "page": 1,
  "per_page": 10,
  "has_next": true
}
GET/music/search

ابحث عن موسيقى خلفية. genre, duration_min, duration_max اختياري.

الطلب

curl "$BASE/music/search?q=upbeat" -H "Authorization: Bearer $KEY"
POST/music/tracks/{track_id}/select

خذ مقطعًا صوتيًا إلى مكتبتك حتى يتمكن التجميع من استخدامه.

الطلب

curl -X POST "$BASE/music/tracks/a1b2c3/select" \
  -H "Authorization: Bearer $KEY"

الحساب

GET/billing/balance

رصيد التوكنز الخاص بك: الإجمالي، المحجوز بواسطة المهام الجارية، والمتاح.

الطلب

curl "$BASE/billing/balance" -H "Authorization: Bearer $KEY"

الاستجابة

{
  "balance": 120,
  "reserved": 3,
  "available": 117,
  "total_purchased": 200,
  "total_spent": 80
}
GET/billing/usage?period=30

ما استخدمته خلال الأيام period الماضية (1–365).

الطلب

curl "$BASE/billing/usage?period=30" -H "Authorization: Bearer $KEY"

الاستجابة

{
  "period_days": 30,
  "tokens_spent": 42,
  "tokens_purchased": 0,
  "uploads_count": 6,
  "exports_count": 11,
  "minutes_processed": 38.5,
  "minutes_exported": 7.9
}

الأخطاء

تحمل الأخطاء رمزًا قابلًا للقراءة آليًا:

{
  "detail": {
    "error": "insufficient_tokens",
    "message": "Not enough tokens for this operation"
  }
}

الرموز الشائعة: api_access_required / session_auth_required (403)، subscription_required (403، تسمي الخطة feature)، insufficient_tokens (402)، export_in_progress / export_expired (409). مفتاح سيء أو ملغى يُرجع 401؛ تجاوز حد المعدل يُرجع 429.

تكلفة التوكنات

يتم احتسابه بدقة مثل التطبيق — 1 توكن = 1 دقيقة مصدر لمعالجة تحميل أو استيراد YouTube؛ تفرض الصادرات رسومًا وفقًا لقواعد التطبيق (تجميع حسب ثواني المصدر التي يتم تشغيلها)؛ ترجمة تسمية توضيحية للمقطع تكلف 1 توكن. الاقتراحات، التحرير التلقائي، الترتيب، تحليل التخطيط، قياس الصوت وإعادة النسخ لا تستهلك توكنات. لا توجد فاتورة API منفصلة.