Compeller

Endpoint MCP Compeller (/api/mcp)

Endpoint MCP Compeller mengimplementasikan Model Context Protocol sebagai pembungkus JSON-RPC 2.0 tipis di atas API REST 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: Streamable HTTP (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 kumpulan yang diiklankan saat runtime di server yang digunakan.
• Daftar direktori: Registry MCP Resmi · Smithery · Glama

Autentikasi

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

Setiap alat lain memerlukan token API Compeller yang diteruskan pada permintaan HTTP itu sendiri, bukan di dalam badan JSON-RPC. Salah satu header 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 dengan salah satu dari dua cara:

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

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 tukar kredensial melalui pembantu auth v1, 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	Jabat tangan kemampuan. Mengembalikan protocolVersion, serverInfo, capabilities.	200 hasil JSON-RPC
notifications/initialized	Pengakuan klien. Tidak ada badan respons.	204
tools/list	Daftar setiap alat dengan skema + deskripsi.	200 hasil JSON-RPC
tools/call	Memanggil alat. params = {name, arguments}.	200 hasil JSON-RPC (kesalahan alat kembali sebagai {isError: true, content: [...]})
ping	Keepalive tanpa operasi.	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. Badan JSON yang salah format 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 keluaran 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.

Penemuan (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 create_compel / create_compel_from_music terima untuk style)

Media dan musik (auth diperlukan kecuali disebutkan)

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

Compels (auth diperlukan)

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 berikutnya.
cancel_compel	compel_id	—	Membatalkan compel yang sedang berjalan (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 di skema alat (lihat get_capabilities.enums); nilai style berasal langsung dari list_styles.

Akun (auth diperlukan)

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 rendering yang mahal untuk membuat keputusan yang sadar biaya.

Rendering (auth diperlukan)

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.

Webhook (auth diperlukan)

Agen yang terintegrasi dengan Compeller dapat mendaftar sendiri untuk notifikasi push yang ditandatangani tentang 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 diketahui: *, 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 endpoint integrator merespons (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 dinonaktifkan.

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

Pengiriman bersifat setidaknya-sekali. Setiap peristiwa dicoba segera dan, jika endpoint Anda tidak dapat dijangkau atau mengembalikan non-2xx, dicoba ulang dengan backoff — hingga 6 percobaan total (segera, lalu setelah 1 menit, 5 menit, 30 menit, 2 jam, 6 jam). Setiap percobaan membawa X-Compeller-Event-Id yang sama dan badan bertanda tangan yang identik byte, jadi deduplikasi pada id tersebut. Jika semua percobaan habis, peristiwa dibuang; 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 yang tidak ditentukan, dan nama host yang diakhiri dengan .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 percobaan ulangnya dan kemudian dibuang.

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 masih 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 menonaktifkan rahasia sebelumnya. Simpan rahasia baru saat diterima sebelum pengiriman nyata berikutnya.

Setiap pengiriman ditandatangani persis seperti jalur REST — lihat bagian Webhooks dari openapi.yaml untuk kontrak amplop 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 dokumen JSON dengan webhook_id, secret, dll. Simpan secret segera; server tidak akan mengembalikannya lagi.

Kode kesalahan

Kode	Arti	Penyebab
-32700	Kesalahan parse	Badan bukan JSON yang valid
-32600	Permintaan tidak valid	jsonrpc hilang/salah, method hilang, badan 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 yang tidak ditangani (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 — ini 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 audio uji yang dihasilkan.