API للمطورين · خادم MCP

قصّ مقاطع YouTube من كودك البرمجي.

Name: AppsGolem API & MCP
Price: 5 EUR
Availability: InStock

REST API بسيطة وخادم MCP لوكلاء AI — كل ما تقوم به أداة القص على الويب، بشكل برمجي. أرصدة مدفوعة مسبقًا، بلا اشتراك.

# one clip = 1 credit — failed cuts never billed
curl -X POST https://appsgolem.com/v1/cuts \
  -H "Authorization: Bearer ag_live_…" \
  -d '{"url":"youtu.be/…","start":"0:00",
       "end":"0:10","mode":"video"}'

كيف تعمل

جديد هنا؟ الفكرة كاملة في دقيقة واحدة.

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

1 · المصادقة

أرسل مفتاحك كـ Authorization: Bearer ag_live_… مع كل طلب.

2 · الإرسال والاستطلاع

POST /v1/cuts يُعيد معرّف المهمة; استطلع GET /v1/cuts/{id} حتى يتم إنتاجها.

3 · تنزيل

احصل على download_url من المهمة المُنتَجة — لا حاجة إلى ترويسة، فالرمز يخوّل الوصول إليه.

البدء السريع

من الصفر إلى مقطع في أربع استدعاءات.

01

أنشئ مفتاح API

Buy a credit pack (from €5), then generate a key in your dashboard. Keys look like ag_live_… and are shown once — store it somewhere safe.

02

أرسل عملية قص

curl -X POST https://appsgolem.com/v1/cuts \
  -H "Authorization: Bearer ag_live_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://youtu.be/aqz-KE-bpKQ",
       "start":"0:00","end":"0:10",
       "resolution":"1080p","mode":"video"}'

import httpx
r = httpx.post("https://appsgolem.com/v1/cuts",
  headers={"Authorization": "Bearer ag_live_…"},
  json={"url": "https://youtu.be/aqz-KE-bpKQ",
        "start": "0:00", "end": "0:10",
        "resolution": "1080p", "mode": "video"})
print(r.json())   # {"id": "…", "state": "queued"}

const r = await fetch("https://appsgolem.com/v1/cuts", {
  method: "POST",
  headers: { Authorization: "Bearer ag_live_…" },
  body: JSON.stringify({
    url: "https://youtu.be/aqz-KE-bpKQ",
    start: "0:00", end: "0:10",
    resolution: "1080p", mode: "video" }),
});
console.log(await r.json());

202 Accepted

{ "id": "e48d…b1a2", "state": "queued", "credits_reserved": 1, "poll_url": "/v1/cuts/e48d…b1a2" }

03

تحقق من رابط التنزيل

# GET /v1/cuts/{id} — repeat every few seconds until state is produced
{ "state": "produced",
  "download_url": "/v1/download/…/clip.mp4" }

تنتقل الحالات accepted → queued → produced → delivered (أو failed → refunded). عادةً ما يكون المقطع القصير جاهزًا خلال ثوانٍ; استطلع كل 3–5 ثوانٍ.

تنتهي صلاحية روابط التحميل بعد 72 ساعة من إنتاج المقطع — يجب تنزيله خلال هذه المدة.

04

نزّل المقطع

الرابط المرمّز يبث MP4 — قابل لإعادة الاستخدام حتى انتهاء صلاحيته. أداة MCP cut_youtube_video تنفّذ الخطوات 2–4 نيابةً عنك في استدعاء واحد.

لوكلاء AI · MCP

سطر واحد لـ Claude وCursor وCodex.

يعرض خادم MCP أداة القص كثلاث أدوات يمكن لأي عميل MCP استدعاءها. ثبّت باستخدام npx — لا حاجة إلى تثبيت أي شيء عالميًا.

Claude Desktop — claude_desktop_config.json

{ "mcpServers": {
  "appsgolem": {
    "command": "npx",
    "args": ["-y","appsgolem-mcp"],
    "env": { "APPSGOLEM_API_KEY":
      "ag_live_…" } } } }

Claude Code

claude mcp add appsgolem \
  -e APPSGOLEM_API_KEY=ag_live_… \
  -- npx -y appsgolem-mcp

Codex CLI — ~/.codex/config.toml

[mcp_servers.appsgolem]
command = "npx"
args = ["-y", "appsgolem-mcp"]
env = { APPSGOLEM_API_KEY = "ag_live_…" }

cut_youtube_video()

أرسل عملية قص (أي وضع، خيارات، أو مصفوفة مقاطع) واحصل على رابط تنزيل في المقابل.

get_cut_status()

تحقّق من مهمة عبر id واجلب رابط تنزيلها.

get_account_balance()

أرصدتك القابلة للإنفاق والحد الأقصى بالساعة.

ما الذي تقوله لوكيلك — كل الإمكانيات

“قص من 0:30 إلى 1:15 من فيديو بدقة 1080p”

cut_youtube_video(url, start="0:30", end="1:15", resolution="1080p")

“استخرج صوت هذا الفيديو من 2:00–5:00 كملف MP3 بمعدل 320 kbps”

cut_youtube_video(…, mode="audio_only", audio_format="mp3", bitrate="320")

“صدّر الفيديو وملف MP3 لأول 30 ثانية”

cut_youtube_video(…, end="0:30", mode="both")

“أنشئ مقطعًا عموديًا 9:16 من أبرز لحظة بين 10:00–10:45”

cut_youtube_video(…, start="10:00", end="10:45", mode="short")

“حوّل 0:05–0:12 إلى GIF”

cut_youtube_video(…, mode="gif")

“استخرج لوحة صور مصغّرة (sheet) بإطار كل 5 ثوانٍ من 1:00–2:00”

cut_youtube_video(…, mode="frames", interval_ms=5000, sheet=true)

“ادمج (stitch) 0:10–0:20 و1:00–1:10 في مقطع واحد”

cut_youtube_video(url, clips=[…], stitch=true)

“نفّذ قصًا سريعًا (fast) بطريقة stream-copy لأول 30 ثانية”

cut_youtube_video(…, end="0:30", fast=true)

“قص 0:00–0:20 بسرعة ×1.5، بدقة 4K”

cut_youtube_video(…, speed=1.5, resolution="2160p")

“كم عدد أرصدة API المتبقية لدي؟”

get_account_balance()

“تحقّق من المهمة e48d…b1a2”

get_cut_status(job_id="e48d…b1a2")

يملأ الوكيل المعطيات من طلبك — أنت لا تكتب JSON.

مرجع API

كل نقطة نهاية، مع أمثلة.

أربع نقاط نهاية. نقاط القراءة/الكتابة الثلاث تتطلب Authorization: Bearer <key>; أما رابط التنزيل فيُخوَّل برمزه الخاص، لذا لا يحتاج إلى ترويسة.

POST /v1/cuts Bearer

الطلب · video

{ "url": "https://youtu.be/aqz-KE-bpKQ",
  "start": "0:00", "end": "0:10",
  "resolution": "1080p", "mode": "video" }

الاستجابة · 202 Accepted

{ "id": "e48db1a2-…", "state": "queued", "credits_reserved": 1, "poll_url": "/v1/cuts/e48db1a2-…" }

مرّر إما start+end أو مصفوفة clips (1–10 نطاقات). أضف ترويسة Idempotency-Key (≤200 حرفًا) حتى يعيد الطلب المُكرَّر استخدام نفس المهمة بدلاً من الدفع مرتين.

محتوى الطلب حسب النمط

audio_onlymp3 · m4a · wav · flac

{ "url":"youtu.be/…", "start":"2:00", "end":"5:00",
  "mode":"audio_only",
  "audio_format":"mp3", "bitrate":"320" }

bothMP4 + MP3، مضغوطان معًا

{ "url":"youtu.be/…", "start":"0:00", "end":"0:30",
  "mode":"both", "resolution":"1080p" }

shortقص ذكي بالذكاء الاصطناعي 9:16

{ "url":"youtu.be/…", "start":"10:00", "end":"10:45",
  "mode":"short" }

nosoundMP4، بدون صوت

{ "url":"youtu.be/…", "start":"0:00", "end":"0:15",
  "mode":"nosound", "fast":true }

gif≤ 5 دقائق، مقطع واحد

{ "url":"youtu.be/…", "start":"0:05", "end":"0:12",
  "mode":"gif" }

framesصور ثابتة JPG · ≤ 1800

{ "url":"youtu.be/…", "start":"1:00", "end":"2:00",
  "mode":"frames", "interval_ms":5000,
  "sheet":true }

clips + stitch1–10 → ملف واحد

{ "url":"youtu.be/…", "mode":"video",
  "clips":[{"start":"0:10","end":"0:20"},
          {"start":"1:00","end":"1:10"}],
  "stitch":true }

speed · 4K0.5–2× · 2160p

{ "url":"youtu.be/…", "start":"0:00", "end":"0:20",
  "mode":"video", "speed":1.5,
  "resolution":"2160p" }

GET /v1/cuts/{id} Bearer

الاستجابة · 200 · produced

{ "id": "e48db1a2-…", "state": "produced", "credits_reserved": 1,
  "created_at": "2026-08-22T12:00:00+00:00",
  "download_url": "/v1/download/…/clip.mp4" }

state تكون واحدة من accepted · queued · produced · delivered · failed · refunded. يظهر download_url بمجرد جاهزية الرمز — إن لم يكن موجودًا، استطلع مرة أخرى.

GET /v1/account Bearer

الاستجابة · 200

{ "balance": 412, "hourly_cap": 60 }

GET /v1/download/{token}/{file} الرمز في الرابط

الاستجابة · 200

# streams the file
Content-Type: video/mp4
Content-Disposition: attachment; filename="clip.mp4"

لا حاجة إلى ترويسة Bearer — فالرمز الموجود في المسار يخوّل الوصول. الرابط قابل لإعادة الاستخدام حتى انتهاء صلاحيته.

الأخطاء

يُعيد كل فشل محتوى JSON يتضمن رمز error وحالة HTTP. أعد المحاولة عند 429 بعد retry_after ثانية; أصلح الطلب وأعد إرساله عند 400.

402 insufficient_credits

{ "error":"insufficient_credits",
  "message":"need 2 credits", "balance":1 }

429 rate_limited

{ "error":"rate_limited",
  "retry_after":12 }

400 invalid_*

{ "error":"invalid_resolution",
  "message":"resolution must be…" }

401 · 404

{ "error":"invalid_api_key" }  // 401
{ "error":"not_found" }        // 404

حد المعدل: يخضع لحدّ المعدّل طلبات القصّ فقط — عدد الطلبات في الساعة حسب باقتك (راجع قسم التسعير). التحقّق من تقدّم المهمة لا يخضع لحدّ المعدّل في الاستخدام العادي، لذا لا يُحتسب الاستطلاع الدوري (polling) ضمن هذا الحد أبدًا. التزم بـ poll_after في كل استجابة (وبـ Retry-After في حالات 429 النادرة)؛ وتضبط أداة MCP هذا الإيقاع نيابةً عنك باستخدام wait=true.

الإمكانات

كل وضع تدعمه أداة القص على الويب.

MODE video

MP4 حتى 4K

144p–2160p، 60fps، بدون علامة مائية.

MODE audio_only

الصوت

mp3 / m4a / wav / flac، معدل بت قابل للاختيار.

MODE both

فيديو + صوت

MP4 وMP3 معًا، كملف zip.

MODE nosound

فيديو صامت

فيديو بدون المسار الصوتي.

MODE short

9:16 عمودي

اقتصاص ذكي بواسطة AI لـ Shorts وReels وTikTok; يتحول إلى أشرطة ضبابية عند عدم التوفر.

MODE gif

GIF متحرك

حتى 5 دقائق، مباشرة من مقطع.

MODE frames

إطارات JPG

كل 100ms–10s، طوابع زمنية + ورقة الاتصال.

OPTION fast

الوضع السريع

نسخ تدفقي (Stream-copy)، أسرع بحوالي 10×؛ يحافظ على حاوية المصدر (WebM بدقة 1440p/2160p).

OPTION speed

السرعة 0.5–2×

أعد ضبط توقيت التشغيل عند التصدير.

OPTION clips

دمج مقاطع متعددة

حتى 10 نوافذ زمنية مدمجة في ملف واحد.

المرجع

المعاملات

الحقل

النوع

ملاحظات

url

string

رابط YouTube بصيغة مشاهدة / مشاركة / youtu.be.

start, end

string

"SS" / "MM:SS" / "HH:MM:SS" (≤ 300h). يُحذف عند استخدام المقاطع.

resolution

enum

144p · 240p · 360p · 480p · 720p · 1080p · 1440p · 2160p (4K; إجمالي مدة القص ≤ 60 دقيقة).

mode

enum

video · audio_only · both · nosound · short · gif · frames.

audio_format

enum

mp3 · m4a · wav · flac — لـ audio_only فقط; يكون both دائمًا MP3.

bitrate

enum

معدل البت الفاقد 320 · 256 · 192 · 128 kbps — MP3/M4A (audio_only), MP3 (both); يُتجاهل لـ wav/flac.

fast

boolean

Stream-copy، أسرع بنحو 10× — video, nosound, both فقط; يفرض السرعة على 1×.

speed

number

سرعة التشغيل 0.5 · 1 · 1.25 · 1.5 · 2 — video, nosound, both, audio_only.

interval_ms

integer

أخذ عينات الإطارات: 100 · 500 · 1000 · 2000 · 5000 · 10000 ms; ≤ 1800 JPG إجمالاً.

burn_ts

boolean

الإطارات — يطبع الطابع الزمني للمصدر على كل JPG.

sheet

boolean

الإطارات — ورقة مصغّرات JPG واحدة (مقطع واحد); يعطّل burn_ts.

clips

array

1–10 نوافذ {start,end}; اضبط stitch لربطها في ملف واحد.

stitch

boolean

مع clips، يتم دمجها في ملف واحد — video, audio_only, both, short, nosound.

Idempotency-Key

header

يُرسَل كرأس HTTP (≤ 200 حرف)، وليس كحقل في نص الطلب — تُعيد المحاولات استخدام المهمة نفسها.

نقاط النهاية: POST /v1/cuts · GET /v1/cuts/{id} · GET /v1/account — مصادقة عبر Bearer.
GET /v1/download/{token}/{file} — مصادقة عبر رمز URL، بدون رأس Bearer.

التسعير

ادفع مقابل المقاطع، لا مقابل المقاعد.

تُشغّل الأرصدة المدفوعة مسبقًا واجهة برمجة تطبيقات (API) أداة القص الخاصة بـ AppsGolem & خادم MCP — كل مقطع يتم إنتاجه يعادل رصيدًا واحدًا، ولا تُفرض رسوم أبدًا على عمليات القص الفاشلة. اشترِ باقة للاستخدام العرضي، أو اشترك للحصول على حجم شهري ثابت وحد معدل أعلى.

№ 01 / حزم مدفوعة مسبقًا