Developer API · MCP server

Cut YouTube clips from your code.

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

A simple REST API and an MCP server for AI agents — everything the web cutter does, programmatically. Prepaid credits, no subscription.

Get an API key Quickstart

API + MCP for coding agents →

# 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"}'

How it works

New here? The whole model in a minute.

You buy prepaid credits, create an API key, and call one endpoint to cut a clip. Cutting is asynchronous: you submit a job, poll until it's produced, then download the file from a tokenized URL. The MCP server wraps all of that into a single tool call for AI agents. No subscription, no seats — you pay per produced clip.

1 · Authenticate

Send your key as Authorization: Bearer ag_live_… on every request.

2 · Submit & poll

POST /v1/cuts returns a job id; poll GET /v1/cuts/{id} until it's produced.

3 · Download

Fetch the download_url from the produced job — no header needed, the token authorizes it.

Quickstart

From zero to a clip in four calls.

01

Create an API key

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

Submit a cut

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

Poll for the download URL

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

States move accepted → queued → produced → delivered (or failed → refunded). A short clip is usually ready in seconds; poll every 3–5 s.

Download links expire 72 hours after the clip is produced — fetch it within that window.

04

Download the clip

The tokenized URL streams the MP4 — reusable until it expires. The MCP tool cut_youtube_video does steps 2–4 for you in one call.

For AI agents · MCP

One line for Claude, Cursor & Codex.

The MCP server exposes the cutter as three tools any MCP client can call. Install with npx — nothing to install globally.

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()

Submit a cut (any mode, options, or a clips array) and get a download URL back.

get_cut_status()

Check a job by id and fetch its download URL.

get_account_balance()

Your spendable credits and hourly cap.

What to say to your agent — every capability

“Cut 0:30 to 1:15 of a video in 1080p”

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

“Grab that video's audio from 2:00–5:00 as a 320 kbps MP3”

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

“Export the video and an MP3 of the first 30 seconds”

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

“Make a 9:16 vertical short of the 10:00–10:45 highlight”

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

“Turn 0:05–0:12 into a GIF”

cut_youtube_video(…, mode="gif")

“Extract a contact sheet of frames every 5 seconds from 1:00–2:00”

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

“Stitch 0:10–0:20 and 1:00–1:10 into one clip”

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

“Do a fast, stream-copy cut of the first 30 seconds”

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

“Cut 0:00–0:20 at 1.5× speed, in 4K”

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

“How many API credits do I have left?”

get_account_balance()

“Check on job e48d…b1a2”

get_cut_status(job_id="e48d…b1a2")

The agent fills in the parameters from your request — you don't write JSON.

API reference

Every endpoint, with examples.

Four endpoints. The three read/write endpoints take Authorization: Bearer <key>; the download URL is authorized by its own token, so it needs no header.

POST /v1/cuts Bearer

Request · video

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

Response · 202 Accepted

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

Pass either start+end or a clips array (1–10 windows). Add an Idempotency-Key header (≤200 chars) so a retried request reuses the same job instead of charging twice.

Request body per mode

audio_onlymp3 · m4a · wav · flac

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

bothMP4 + MP3, zipped

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

short9:16 AI smart-crop

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

nosoundMP4, no audio

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

gif≤ 5 min, single clip

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

framesJPG stills · ≤ 1800

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

clips + stitch1–10 → one file

{ "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

Response · 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 is one of accepted · queued · produced · delivered · failed · refunded. download_url appears once a token is ready — if it's absent, poll again.

GET /v1/account Bearer

Response · 200

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

GET /v1/download/{token}/{file} Token in URL

Response · 200

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

No Bearer header — the token in the path authorizes it. The URL is reusable until it expires.

Errors

Every failure returns a JSON body with an error code and the HTTP status. Retry 429 after retry_after seconds; fix and resubmit on a 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

Rate limit: Only cut submissions are rate-limited — your plan's submissions/hour (see Pricing). Checking a job's progress is not rate-limited for normal use, so polling never counts against that cap. Honor poll_after in each response (and Retry-After on the rare 429); the MCP tool paces this for you with wait=true.

Capabilities

Every mode the web cutter has.

MODE video

MP4 up to 4K

144p–2160p, 60fps, no watermark.

MODE audio_only

Audio

mp3 / m4a / wav / flac, selectable bitrate.

MODE both

Video + audio

MP4 and MP3 together, as a zip.

MODE nosound

Muted video

Video with the audio track removed.

MODE short

9:16 vertical

AI smart-crop for Shorts, Reels, and TikTok; falls back to blurred letterboxing when unavailable.

MODE gif

Animated GIF

Up to 5 minutes, straight from a clip.

MODE frames

JPG frames

Every 100ms–10s, timestamps + contact sheet.

OPTION fast

Fast mode

Stream-copy, about 10× faster; keeps the source container (WebM at 1440p/2160p).

OPTION speed

Speed 0.5–2×

Re-time playback on export.

OPTION clips

Multi-clip stitch

Up to 10 windows joined into one file.

Reference

Parameters

Field

Type

Notes

url

string

YouTube watch / share / youtu.be URL.

start, end

string

"SS" / "MM:SS" / "HH:MM:SS" (≤ 300h). Omit when using clips.

resolution

enum

144p · 240p · 360p · 480p · 720p · 1080p · 1440p · 2160p (4K; total cut ≤ 60 min).

mode

enum

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

audio_format

enum

mp3 · m4a · wav · flac — for audio_only only; both is always MP3.

bitrate

enum

Lossy bitrate 320 · 256 · 192 · 128 kbps — MP3/M4A (audio_only), MP3 (both); ignored for wav/flac.

fast

boolean

Stream-copy, about 10× faster — video, nosound, both only; forces speed to 1×.

speed

number

Playback speed 0.5 · 1 · 1.25 · 1.5 · 2 — video, nosound, both, audio_only.

interval_ms

integer

Frames sampling: 100 · 500 · 1000 · 2000 · 5000 · 10000 ms; ≤ 1800 JPGs total.

burn_ts

boolean

Frames — burn the source timestamp onto each JPG.

sheet

boolean

Frames — a single contact-sheet JPG (single clip); disables burn_ts.

clips

array

1–10 {start,end} windows; set stitch to join into one file.

stitch

boolean

With clips, join them into one file — video, audio_only, both, short, nosound.

Idempotency-Key

header

Sent as an HTTP header (≤ 200 characters), not a body field — retries reuse the same job.

Endpoints: POST /v1/cuts · GET /v1/cuts/{id} · GET /v1/account — Bearer-authed.
GET /v1/download/{token}/{file} — authed by the URL token, no Bearer header.

Pricing

Pay for clips, not seats.

Prepaid credits power the AppsGolem cutter API & MCP server — one produced clip is one credit, and failed cuts are never billed. Buy a pack for occasional use, or subscribe for steady monthly volume and a higher rate limit.

№ 01 / Prepaid packs