API توسعه‌دهنده · سرور MCP

کلیپ‌های YouTube را از طریق کد خود برش دهید.

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

یک REST API ساده و یک سرور MCP برای عامل‌های AI — هر کاری که ابزار برش وب انجام می‌دهد، به‌صورت برنامه‌نویسی. اعتبار پیش‌پرداخت، بدون اشتراک.

دریافت کلید API شروع سریع

API + MCP برای عامل‌های کدنویسی →

# 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 می‌سازید، و یک نقطه پایانی را برای برش یک کلیپ فراخوانی می‌کنید. برش ناهمگام (asynchronous) است: کاری ارسال می‌کنید، تا تولید شدنش وضعیت را بررسی می‌کنید، سپس فایل را از یک URL نشانه‌دار دانلود می‌کنید. سرور 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

پایش 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()

یک برش ارسال کنید (هر حالتی، گزینه‌ها یا آرایه clips) و یک URL دانلود دریافت کنید.

get_cut_status()

یک کار را بر اساس id بررسی کنید و 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

هر نقطه پایانی، همراه با مثال.

چهار نقطه پایانی. سه نقطه پایانی خواندن/نوشتن به Authorization: Bearer <key> نیاز دارند; 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"

بدون هدر Bearer — توکن موجود در مسیر دسترسی را مجاز می‌کند. این 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 پایبند باشید (و در موارد نادر 429 به Retry-After)؛ ابزار 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

URL از نوع watch / share / youtu.be در YouTube.

start, end

string

"SS" / "MM:SS" / "HH:MM:SS" (≤ 300h). در صورت استفاده از clips، حذف کنید.

resolution

enum

144p · 240p · 360p · 480p · 720p · 1080p · 1440p · 2160p (4K; مجموع مدت برش ≤ 60 min).

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 / بسته‌های پیش‌پرداخت