API para desenvolvedores · servidor MCP

Corte clipes do YouTube a partir do seu código.

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

Uma API REST simples e um servidor MCP para agentes de AI — tudo o que o cortador web faz, de forma programática. Créditos pré-pagos, sem assinatura.

Obter uma chave de API Início rápido

API + MCP para agentes de código →

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

Como funciona

Novo por aqui? Todo o modelo num minuto.

Compras créditos pré-pagos, crias uma chave de API e chamas um único endpoint para cortar um clip. O corte é assíncrono: submetes um job, consultas o estado até estar produzido, depois descarregas o ficheiro a partir de um URL com token. O servidor MCP junta tudo isso numa única chamada de ferramenta para agentes de IA. Sem subscrição, sem lugares — pagas por cada clip produzido.

1 · Autenticar

Envia a tua chave como Authorization: Bearer ag_live_… em cada pedido.

2 · Submeter e consultar

POST /v1/cuts devolve um id de job; consulta GET /v1/cuts/{id} até estar produzido.

3 · Baixar

Obtém o download_url a partir do job produzido — não é necessário cabeçalho, o token autoriza-o.

Início rápido

Do zero a um clipe em quatro chamadas.

01

Crie uma chave de 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

Envie um corte

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

Consulte o URL de download

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

Os estados passam por accepted → queued → produced → delivered (ou failed → refunded). Um clip curto está normalmente pronto em segundos; consulta a cada 3–5 s.

Os links de download expiram 72 horas após a criação do clipe — baixe-o dentro desse prazo.

04

Baixe o clipe

O URL tokenizado transmite o MP4 — reutilizável até expirar. A ferramenta MCP cut_youtube_video realiza os passos 2–4 para você em uma única chamada.

Para agentes de AI · MCP

Uma linha para Claude, Cursor e Codex.

O servidor MCP expõe o cortador como três ferramentas que qualquer cliente MCP pode chamar. Instale com npx — nada a instalar globalmente.

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

Envie um corte (qualquer modo, opções ou um array clips) e receba de volta um URL de download.

get_cut_status()

Verifique uma tarefa pelo id e obtenha seu URL de download.

get_account_balance()

Os seus créditos disponíveis e o limite horário.

O que dizer ao teu agente — todas as funcionalidades

“Cortar de 0:30 a 1:15 de um vídeo em 1080p”

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

“Extrair o áudio desse vídeo de 2:00–5:00 como MP3 de 320 kbps”

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

“Exportar o vídeo e um MP3 dos primeiros 30 segundos”

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

“Criar um short vertical 9:16 do melhor momento 10:00–10:45”

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

“Transformar 0:05–0:12 num GIF”

cut_youtube_video(…, mode="gif")

“Extrair um contact sheet de fotogramas a cada 5 segundos de 1:00–2:00”

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

“Stitch 0:10–0:20 e 1:00–1:10 num único clip”

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

“Fazer um corte fast em stream-copy dos primeiros 30 segundos”

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

“Cortar 0:00–0:20 a uma velocidade de 1.5×, em 4K”

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

“Quantos créditos de API me restam?”

get_account_balance()

“Verificar o job e48d…b1a2”

get_cut_status(job_id="e48d…b1a2")

O agente preenche os parâmetros a partir do teu pedido — não escreves JSON.

Referência da API

Cada endpoint, com exemplos.

Quatro endpoints. Os três endpoints de leitura/escrita requerem Authorization: Bearer <key>; o URL de transferência é autorizado pelo seu próprio token, por isso não precisa de cabeçalho.

POST /v1/cuts Bearer

Pedido · video

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

Resposta · 202 Accepted

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

Indica start+end ou um array clips (1–10 janelas). Adiciona um cabeçalho Idempotency-Key (≤200 carateres) para que um pedido repetido reutilize o mesmo job em vez de cobrar duas vezes.

Corpo do pedido por modo

audio_onlymp3 · m4a · wav · flac

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

bothMP4 + MP3, em zip

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

short9:16 smart-crop por IA

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

nosoundMP4, sem áudio

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

gif≤ 5 min, um único clip

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

framesImagens fixas JPG · ≤ 1800

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

clips + stitch1–10 → um único ficheiro

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

Resposta · 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 é um de: accepted · queued · produced · delivered · failed · refunded. download_url aparece assim que um token está pronto — se estiver ausente, volta a consultar.

GET /v1/account Bearer

Resposta · 200

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

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

Resposta · 200

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

Sem cabeçalho Bearer — o token no caminho autoriza-o. O URL é reutilizável até expirar.

Erros

Cada falha devolve um corpo JSON com um código error e o estado HTTP. Tenta novamente um 429 após retry_after segundos; corrige e reenvia num 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

Limite de taxa: Apenas os envios de corte estão sujeitos a limite de frequência — os envios/hora do seu plano (ver Preços). Verificar o progresso de uma tarefa não está sujeito a limite em uso normal, portanto as consultas periódicas nunca contam para esse limite. Respeite o poll_after em cada resposta (e o Retry-After no raro caso de um 429); a ferramenta MCP regula esse ritmo por você com wait=true.

Recursos

Todos os modos que o cortador web oferece.

MODE video

MP4 até 4K

144p–2160p, 60fps, sem marca d'água.

MODE audio_only

Áudio

mp3 / m4a / wav / flac, taxa de bits selecionável.

MODE both

Vídeo + áudio

MP4 e MP3 juntos, em um zip.

MODE nosound

Vídeo sem áudio

Vídeo sem a faixa de áudio.

MODE short

9:16 vertical

Recorte inteligente com AI para Shorts, Reels e TikTok; recorre a barras pretas desfocadas quando não disponível.

MODE gif

GIF animado

Até 5 minutos, direto de um clipe.

MODE frames

Quadros JPG

A cada 100ms–10s, marcas de tempo + folha de contato.

OPTION fast

Modo rápido

Cópia direta do stream (stream-copy), cerca de 10× mais rápida; mantém o contêiner de origem (WebM em 1440p/2160p).

OPTION speed

Velocidade 0.5–2×

Reajuste a velocidade de reprodução na exportação.

OPTION clips

União de vários clipes

Até 10 janelas unidas em um único arquivo.

Referência

Parâmetros

Campo

Tipo

Observações

url

string

URL do YouTube watch / share / youtu.be.

start, end

string

"SS" / "MM:SS" / "HH:MM:SS" (≤ 300h). Omita ao usar clips.

resolution

enum

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

mode

enum

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

audio_format

enum

mp3 · m4a · wav · flac — apenas para audio_only; both é sempre MP3.

bitrate

enum

Taxa de bits com perdas 320 · 256 · 192 · 128 kbps — MP3/M4A (audio_only), MP3 (both); ignorada para wav/flac.

fast

boolean

Stream-copy, cerca de 10× mais rápido — apenas video, nosound, both; força speed para 1×.

speed

number

Velocidade de reprodução 0.5 · 1 · 1.25 · 1.5 · 2 — video, nosound, both, audio_only.

interval_ms

integer

Amostragem de fotogramas: 100 · 500 · 1000 · 2000 · 5000 · 10000 ms; ≤ 1800 JPG no total.

burn_ts

boolean

Fotogramas — sobrepõe a marca temporal de origem a cada JPG.

sheet

boolean

Fotogramas — uma única folha de contactos em JPG (clipe único); desativa burn_ts.

clips

array

1–10 janelas {start,end}; defina stitch para unir em um único arquivo.

stitch

boolean

Com clips, junta-os num único ficheiro — video, audio_only, both, short, nosound.

Idempotency-Key

header

Enviado como cabeçalho HTTP (≤ 200 caracteres), não como campo do corpo — as repetições reutilizam a mesma tarefa.

Endpoints: POST /v1/cuts · GET /v1/cuts/{id} · GET /v1/account — Autenticado via Bearer.
GET /v1/download/{token}/{file} — autenticado pelo token da URL, sem cabeçalho Bearer.

Preços

Pague por clipes, não por licenças.

Os créditos pré-pagos alimentam a API de corte da AppsGolem & o servidor MCP — cada clipe produzido equivale a um crédito, e os cortes falhados nunca são cobrados. Compre um pacote para uso ocasional, ou assine para um volume mensal constante e um limite de pedidos mais alto.

№ 01 / Pacotes pré-pagos

Pague conforme o uso.

Compra única, sem renovação. Os créditos permanecem válidos por 12 meses.

Pacote Starter

€5 pagamento único

25 créditos · ≈ 25 clipes padrão

Válido por 12 meses

Comece agora

Pacote PAYG Melhor custo-benefício

€25 pagamento único

150 créditos · ≈ 150 clipes padrão

Válido por 12 meses · €0,17 / crédito

Comece agora

№ 02 / Subscrições

Corte todos os meses.

Os créditos são renovados a cada período e o seu limite de pedidos aumenta. Cancele quando quiser.

Starter

€19 / mês

ou €190 / ano · 2 meses grátis

250 créditos / mês

30 pedidos / hora
Os créditos são renovados mensalmente
Cancele quando quiser

Comece agora

★ Mais popular Pro

€49 / mês

ou €490 / ano · 2 meses grátis

1000 créditos / mês

60 pedidos / hora
Os créditos são renovados mensalmente
Cancele quando quiser

Comece agora

Escala

€149 / mês

ou €1490 / ano · 2 meses grátis

5000 créditos / mês

120 pedidos / hora
Os créditos são renovados mensalmente
Cancele quando quiser

Comece agora

As assinaturas concedem antecipadamente os créditos de todo o período e aumentam o seu limite de pedidos/hora. Os planos anuais cobram 10 meses por 12.

№ 03 / Como funcionam os créditos