Compeller

Endpoint MCP Compeller (/api/mcp)

Endpoint MCP Compeller mengimplementasikan Model Context Protocol sebagai pembungkus tipis JSON-RPC 2.0 di atas REST API v1 yang sudah ada. Ini ditujukan untuk integrator agen (Claude Desktop, Cursor, klien MCP kustom, DigiRAMP) yang berbicara MCP secara native daripada HTTP mentah.

• Transport: HTTP Streamable (satu pesan JSON-RPC per HTTP POST).
• URL: POST https://compeller.ai/api/mcp
• Versi protokol: 2024-11-05
• Nama / versi server: compeller-mcp / lihat hasil initialize.
• Kontrak alat: Daftar alat di bawah ini adalah kontrak integrasi publik. Gunakan tools/list untuk set yang diiklankan saat runtime di server yang di-deploy.
• Daftar direktori: Official MCP Registry · Smithery · Glama

Autentikasi

Metode anonim (discovery): initialize, tools/list, ping, notifications/initialized, ditambah alat anonim get_capabilities, get_pricing, list_styles.

Setiap alat lainnya memerlukan token API Compeller yang dikirimkan pada permintaan HTTP itu sendiri, bukan di dalam body JSON-RPC. Salah satu header berikut dapat digunakan:

Authorization: Bearer <api-token>
X-API-Token: <api-token>

Token diterbitkan per User Compeller (token yang sama digunakan oleh /api/v1/*). Agen dapat memperolehnya melalui salah satu dari dua cara:

1. Minta pengguna untuk login, buka Account → API Access, tampilkan token, dan tempelkan ke penyimpanan rahasia agen.
2. Gunakan endpoint login yang ada dan kirim access_token sebagai token bearer. Tidak diperlukan atau diharapkan header Cookie:

curl -s -X POST https://compeller.ai/api/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"artist@example.com","password":"..."}'

Pengguna normal menerima username dan access_token. roles hanya muncul untuk akun dengan peran di luar ROLE_COMPELLER dasar; refresh_token dan expires_in hanya muncul jika tidak kosong.

3. Atau tukarkan kredensial melalui v1 auth helper, yang mengembalikan token API persisten:

curl -s -X POST https://compeller.ai/api/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"email":"artist@example.com","password":"..."}'

Token yang hilang atau tidak valid muncul sebagai kesalahan alat (isError: true) dengan pesan "API token required." / "Invalid API token.", bukan sebagai kesalahan JSON-RPC, sehingga klien MCP dapat meminta kredensial kepada pengguna.

Metode JSON-RPC

Metode	Tujuan	Hasil HTTP
initialize	Handshake kapabilitas. Mengembalikan protocolVersion, serverInfo, capabilities.	200 hasil JSON-RPC
notifications/initialized	Pengakuan klien. Tidak ada body respons.	204
tools/list	Daftar setiap alat dengan skema + deskripsi.	200 hasil JSON-RPC
tools/call	Panggil alat. params = {name, arguments}.	200 hasil JSON-RPC (kesalahan alat kembali sebagai {isError: true, content: [...]})
ping	Keepalive no-op.	200 JSON-RPC result: {}

Metode yang tidak dikenal mengembalikan kesalahan JSON-RPC -32601 Method not found. Nama alat yang tidak dikenal mengembalikan -32602 Unknown tool. Body JSON yang cacat mengembalikan -32700 Parse error. jsonrpc yang hilang/salah atau method yang hilang mengembalikan -32600 Invalid Request.

Alat

Semua alat mengembalikan satu entri content dari type: text yang bidang text-nya adalah output terstruktur berformat JSON. Saat gagal, bentuk respons yang sama dikembalikan dengan isError: true dan pesan kesalahan yang dapat dibaca manusia di content[0].text — tidak pernah sebagai error JSON-RPC.

Discovery (tanpa auth)

Alat	Input	Mengembalikan
get_capabilities	—	productName, version, capabilities[], spec_url, enums (styles, target_platforms, aspect_ratios), auth, media_limits, rate_limits
get_pricing	—	plans[] dengan id, name, monthlyUsd, features[]
list_styles	—	styles[] dengan id, name (id adalah nilai persis yang diterima create_compel / create_compel_from_music untuk style)

Media dan musik (memerlukan auth kecuali disebutkan)

Alat	Wajib	Opsional	Mengembalikan
search_music	query	limit	Hasil pencarian musik publik yang cocok untuk create_compel_from_music. Tidak memerlukan auth.
upload_media	—	name, mime_type, type	Instruksi unggahan yang menunjuk ke POST /api/v1/media
search_media	—	type (audio/image/video/text), limit (≤100, default 20), offset	media[], paging

Compels (memerlukan auth)

Alat	Wajib	Opsional	Mengembalikan
create_compel_from_music	track_id	title, style, target_platform, aspect_ratio, artist_context	compel_id, status, next_action
create_compel	title, primary_media_id	style, target_platform, aspect_ratio, artist_context	compel_id, status: QUEUED
get_compel	compel_id	—	compel_id, title, status, progress_percent, stage, rendering_id, created_at, human_url, next_action
start_render	compel_id	—	Memulai rendering akhir saat compel siap; mengembalikan status dan tindakan selanjutnya.
cancel_compel	compel_id	—	Membatalkan compel yang sedang berlangsung (idempoten — yang sudah DIBATALKAN berhasil); mengembalikan compel_id, status: CANCELLED, stage.
list_compels	—	limit (≤100), offset	compels[], paging
search_compels	query	limit	compels[], count

style, target_platform, dan aspect_ratio dibatasi oleh enum dalam skema alat (lihat get_capabilities.enums); nilai style berasal langsung dari list_styles.

Akun (memerlukan auth)

Alat	Input	Mengembalikan
get_account_credits	—	plan, minutes_remaining, free_minutes_remaining, paid_minutes_remaining, minutes_total, quota_exceeded, api_eligible, billing_url — panggil sebelum render mahal untuk membuat keputusan yang sadar biaya.

Renderings (memerlukan auth)

Alat	Wajib	Mengembalikan
list_renderings	compel_id	compel_id, renderings[] dengan rendering_id, status, download_url
get_rendering	rendering_id	rendering_id, compel_id, status, download_url

download_url menunjuk ke GET /api/v1/renderings/{id}/download (mendukung HTTP Range). Respons compel/rendering yang selesai juga menyertakan handoff react dengan unduhan REACT gratis (https://compeller.ai/download/desktop) dan URL pelajari lebih lanjut (https://compeller.ai/react) sehingga agen dapat memberi tahu pengguna cara mengalami compel sebagai sistem pertunjukan langsung.

Webhooks (memerlukan auth)

Agen yang terintegrasi dengan Compeller dapat mendaftar sendiri untuk notifikasi push bertanda tangan dari peristiwa siklus hidup compel alih-alih melakukan polling get_compel. Berlangganan ke compel.ready untuk mengetahui saat compel dapat dirender (lalu panggil start_render) tanpa polling; compel.completed / compel.failed adalah peristiwa terminal.

Alat	Wajib	Opsional	Mengembalikan
register_webhook	url (HTTPS, ≤2048 karakter)	events[] — default ke ["*"]; nilai yang dikenal: *, compel.ready, compel.completed, compel.failed	webhook_id, url, events, secret (dikembalikan tepat sekali), active, created_at
list_webhooks	—	—	webhooks[] — webhook_id, url, events, active, created_at, updated_at. Rahasia tidak pernah dikembalikan oleh alat ini.
update_webhook	webhook_id	url, events[], active — setidaknya satu	webhook_id, url, events, active, created_at, updated_at. Rahasia tidak pernah dikembalikan; gunakan rotate_webhook_secret untuk itu.
delete_webhook	webhook_id	—	webhook_id, deleted: true
test_webhook_delivery	webhook_id	—	webhook_id, event_id, event_type: "webhook.test", delivered, response_status?, response_body_preview?, latency_ms, error?. Sinkron — alat menunggu respons endpoint integrator (maks 5 detik). Rahasia tidak pernah dikembalikan.
rotate_webhook_secret	webhook_id	—	webhook_id, url, events, active, secret (baru — dikembalikan tepat sekali), created_at, updated_at. Rahasia lama langsung tidak berlaku.

Nama peristiwa yang tidak dikenal secara diam-diam diciutkan ke wildcard *; ini mencerminkan POST /api/v1/webhooks sehingga agen tidak pernah membuat langganan no-op.

Pengiriman bersifat setidaknya sekali. Setiap peristiwa dicoba segera dan, jika endpoint Anda tidak dapat dijangkau atau mengembalikan non-2xx, dicoba ulang dengan backoff — hingga total 6 percobaan (segera, lalu setelah 1m, 5m, 30m, 2j, 6j). Setiap percobaan membawa X-Compeller-Event-Id yang sama dan body bertanda tangan yang identik byte, jadi deduplikasi pada id tersebut. Jika semua percobaan habis, peristiwa dihapus; rekonsiliasi melalui get_compel.

register_webhook menolak tujuan yang menunjuk ke infrastruktur internal dengan kesalahan alat: loopback, rentang privat RFC1918, link-local (termasuk IP metadata cloud seperti 169.254.169.254), IPv6 ULA, CGNAT, multicast, alamat tidak ditentukan, dan nama host yang berakhiran .local / .internal / .localhost. Pemeriksaan yang sama dijalankan ulang saat pengiriman terhadap DNS yang diselesaikan pada setiap percobaan, sehingga nama host yang mengikat ulang ke IP yang diblokir setelah pendaftaran dilewati untuk percobaan itu (dicatat); jika tetap diblokir, ia hanya menghabiskan anggaran coba ulangnya dan kemudian dihapus.

test_webhook_delivery mengirim peristiwa webhook.test sintetis dengan tanda tangan HMAC-SHA256 dan menunggu secara sinkron respons endpoint. Ini mengabaikan events yang dilanggan endpoint (selalu dikirim) dan menerapkan pemeriksaan keamanan URL yang sama seperti pengiriman nyata. Respons non-2xx muncul sebagai delivered: false tetapi panggilan MCP itu sendiri tetap berhasil — hasilnya adalah payload.

update_webhook menerima salah satu dari url, events, active (setidaknya satu). Validasi URL mencerminkan register_webhook. Rahasia tidak pernah dikembalikan oleh alat ini.

rotate_webhook_secret mencetak rahasia penandatanganan hex 64 karakter baru, mengembalikannya tepat sekali, dan langsung membatalkan rahasia sebelumnya. Simpan rahasia baru saat diterima sebelum pengiriman nyata berikutnya.

Setiap pengiriman ditandatangani persis seperti jalur REST — lihat bagian Webhooks openapi.yaml untuk kontrak envelope dan header lengkap.

Contoh sesi

# 1. Handshake
curl -s https://compeller.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

# 2. List tools
curl -s https://compeller.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. Register a webhook (auth required)
curl -s https://compeller.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <api-token>' \
  -d '{
        "jsonrpc":"2.0",
        "id":3,
        "method":"tools/call",
        "params":{
          "name":"register_webhook",
          "arguments":{
            "url":"https://hooks.my-agent.io/compeller",
            "events":["compel.completed","compel.failed"]
          }
        }
      }'

Respons untuk langkah 3 adalah result JSON-RPC yang berisi content[0].text — itu sendiri adalah dokumen JSON dengan webhook_id, secret, dll. Simpan secret segera; server tidak akan mengembalikannya lagi.

Kode kesalahan

Kode	Arti	Penyebab
-32700	Kesalahan parse	Body bukan JSON yang valid
-32600	Permintaan Tidak Valid	jsonrpc hilang/salah, method hilang, body kosong
-32601	Metode tidak ditemukan	Metode JSON-RPC tidak dikenal
-32602	Parameter tidak valid	Alat tidak dikenal, name alat hilang, bentuk params buruk
-32603	Kesalahan internal	Pengecualian tidak tertangani (dicatat di sisi server)

Kegagalan tingkat alat (validasi, auth, tidak ditemukan) dikembalikan di dalam respons JSON-RPC yang berhasil sebagai {result: {isError: true, content: [{type: "text", text: "..."}]}}. Ini sesuai konvensi MCP — memungkinkan LLM melihat dan menampilkan kegagalan secara verbatim. Pohon keputusan audio agen: jika pengguna menyediakan MP3/WAV/FLAC, gunakan upload_media lalu create_compel; jika pengguna hanya menyediakan string lagu/artis, gunakan search_music lalu create_compel_from_music; jangan mensintesis nada kecuali secara eksplisit diminta untuk menghasilkan audio uji.