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، وتستدعي نقطة نهاية واحدة لقص المقطع. القطع غير متزامن: تقدم مهمة، تقوم بالاستطلاع حتى يتم إنتاجها، ثم تحميل الملف من URL مميز. خادم MCP يجمع كل ذلك في أداة واحدة لمكالمة وكلاء الذكاء الاصطناعي. لا اشتراك، لا مقاعد — تدفع لكل مقطع منتج.

1 · المصادقة

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

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

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

3 · تنزيل

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

البدء السريع

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

01

أنشئ مفتاح API

اشترِ حزمة رصيد (ابتداءً من €5)، ثم أنشئ مفتاحًا في لوحة التحكم الخاصة بك. تبدو المفاتيح على شكل ag_live_… وتُعرض مرة واحدة فقط — احتفظ بها في مكان آمن.

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

استطلاع للتحميل URL

# 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

نزّل المقطع

URL المرمز يبث 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()

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

get_cut_status()

تحقق من وظيفة حسب التعريف واحصل على URL تحميلها.

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

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

أربع نقاط نهاية. تأخذ نقاط النهاية الثلاث للقراءة والكتابة <span class="font-mono text-ink">التفويض: حامل <مفتاح>; يتم تفويض URL التحميل بواسطة رمزه الخاص، لذا لا يحتاج إلى رأس.

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} رمز في URL

الاستجابة · 200

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

لا يوجد رأس حامل — الرمز في المسار يسمح بذلك. URL قابل لإعادة الاستخدام حتى ينتهي صلاحيته.

الأخطاء

يُعيد كل فشل محتوى 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 URL.

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 / حزم مدفوعة مسبقًا