Compeller

Compeller MCP एंडपॉइंट (/api/mcp)

Compeller MCP एंडपॉइंट मौजूदा v1 REST API के ऊपर एक पतला JSON-RPC 2.0 रैपर के रूप में Model Context Protocol को लागू करता है। यह एजेंट इंटीग्रेटर्स (Claude Desktop, Cursor, कस्टम MCP क्लाइंट, DigiRAMP) के लिए है जो कच्चे HTTP के बजाय मूल रूप से MCP बोलते हैं।

• ट्रांसपोर्ट: स्ट्रीमेबल HTTP (प्रति HTTP POST एक JSON-RPC संदेश)।
• URL: POST https://compeller.ai/api/mcp
• प्रोटोकॉल संस्करण: 2024-11-05
• सर्वर नाम / संस्करण: compeller-mcp / initialize परिणाम देखें।
• टूल अनुबंध: नीचे दी गई टूल सूची सार्वजनिक एकीकरण अनुबंध है। तैनात सर्वर पर रनटाइम-विज्ञापित सेट के लिए tools/list का उपयोग करें।
• निर्देशिका सूचियाँ: आधिकारिक MCP रजिस्ट्री · Smithery · Glama

प्रमाणीकरण

अनाम (डिस्कवरी) विधियाँ: initialize, tools/list, ping, notifications/initialized, साथ ही अनाम टूल get_capabilities, get_pricing, list_styles।

अन्य हर टूल के लिए HTTP अनुरोध पर ही Compeller API टोकन की आवश्यकता होती है, JSON-RPC बॉडी के अंदर नहीं। दोनों में से कोई भी हेडर काम करता है:

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

टोकन प्रति Compeller User जारी किए जाते हैं (वही टोकन जो /api/v1/* द्वारा उपयोग किए जाते हैं)। एजेंट इन्हें दो तरीकों में से किसी एक से प्राप्त कर सकते हैं:

1. उपयोगकर्ता से लॉग इन करने के लिए कहें, खाता → API एक्सेस खोलें, टोकन प्रकट करें, और इसे एजेंट के सीक्रेट स्टोर में पेस्ट करें।
2. मौजूदा लॉगिन एंडपॉइंट का उपयोग करें और access_token को बियरर टोकन के रूप में भेजें। कोई Cookie हेडर आवश्यक या अपेक्षित नहीं है:

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

सामान्य उपयोगकर्ताओं को username और access_token प्राप्त होते हैं। roles केवल बेसलाइन ROLE_COMPELLER से परे भूमिकाओं वाले खातों के लिए दिखाई देता है; refresh_token और expires_in केवल तभी दिखाई देते हैं जब वे खाली न हों।

3. या v1 auth सहायक के माध्यम से क्रेडेंशियल का आदान-प्रदान करें, जो स्थायी API टोकन लौटाता है:

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

गुम या अमान्य टोकन एक टूल त्रुटि (isError: true) के रूप में संदेश "API token required." / "Invalid API token." के साथ दिखाई देता है, न कि JSON-RPC त्रुटि के रूप में, ताकि MCP क्लाइंट उपयोगकर्ता से क्रेडेंशियल मांग सकें।

JSON-RPC विधियाँ

विधि	उद्देश्य	HTTP परिणाम
initialize	क्षमता हैंडशेक। protocolVersion, serverInfo, capabilities लौटाता है।	200 JSON-RPC परिणाम
notifications/initialized	क्लाइंट स्वीकृति। कोई प्रतिक्रिया बॉडी नहीं।	204
tools/list	स्कीमा + विवरण के साथ हर टूल सूचीबद्ध करें।	200 JSON-RPC परिणाम
tools/call	टूल लागू करें। params = {name, arguments}।	200 JSON-RPC परिणाम (टूल त्रुटियाँ {isError: true, content: [...]} के रूप में वापस आती हैं)
ping	नो-ऑप कीपअलाइव।	200 JSON-RPC result: {}

अज्ञात विधियाँ JSON-RPC त्रुटि -32601 Method not found लौटाती हैं। अज्ञात टूल नाम -32602 Unknown tool लौटाते हैं। गलत JSON बॉडी -32700 Parse error लौटाती है। गुम / गलत jsonrpc या गुम method -32600 Invalid Request लौटाता है।

टूल

सभी टूल content की एकल type: text प्रविष्टि लौटाते हैं जिसका text फ़ील्ड JSON-प्रारूपित संरचित आउटपुट है। विफलता पर, वही प्रतिक्रिया आकार isError: true और content[0].text में मानव-पठनीय त्रुटि संदेश के साथ लौटाया जाता है — कभी भी JSON-RPC error के रूप में नहीं।

डिस्कवरी (कोई प्रमाणीकरण नहीं)

टूल	इनपुट	रिटर्न
get_capabilities	—	productName, version, capabilities[], spec_url, enums (styles, target_platforms, aspect_ratios), auth, media_limits, rate_limits
get_pricing	—	plans[] के साथ id, name, monthlyUsd, features[]
list_styles	—	styles[] के साथ id, name (id सटीक मान है जिसे create_compel / create_compel_from_music style के लिए स्वीकार करते हैं)

मीडिया और संगीत (प्रमाणीकरण आवश्यक जब तक अन्यथा नोट न किया गया हो)

टूल	आवश्यक	वैकल्पिक	रिटर्न
search_music	query	limit	create_compel_from_music के लिए उपयुक्त सार्वजनिक संगीत खोज परिणाम। कोई प्रमाणीकरण आवश्यक नहीं।
upload_media	—	name, mime_type, type	POST /api/v1/media की ओर इशारा करते अपलोड निर्देश
search_media	—	type (audio/image/video/text), limit (≤100, डिफ़ॉल्ट 20), offset	media[], paging

कॉम्पेल (प्रमाणीकरण आवश्यक)

टूल	आवश्यक	वैकल्पिक	रिटर्न
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	—	जब कॉम्पेल तैयार हो तो अंतिम रेंडरिंग शुरू करता है; स्थिति और अगली कार्रवाई लौटाता है।
cancel_compel	compel_id	—	प्रगति पर कॉम्पेल रद्द करता है (इडेम्पोटेंट — पहले से CANCELLED सफल होता है); compel_id, status: CANCELLED, stage लौटाता है।
list_compels	—	limit (≤100), offset	compels[], paging
search_compels	query	limit	compels[], count

style, target_platform, और aspect_ratio टूल स्कीमा में enum द्वारा सीमित हैं (get_capabilities.enums देखें); style मान सीधे list_styles से आते हैं।

खाता (प्रमाणीकरण आवश्यक)

टूल	इनपुट	रिटर्न
get_account_credits	—	plan, minutes_remaining, free_minutes_remaining, paid_minutes_remaining, minutes_total, quota_exceeded, api_eligible, billing_url — लागत-जागरूक निर्णय लेने के लिए महंगे रेंडर से पहले कॉल करें।

रेंडरिंग (प्रमाणीकरण आवश्यक)

टूल	आवश्यक	रिटर्न
list_renderings	compel_id	compel_id, renderings[] के साथ rendering_id, status, download_url
get_rendering	rendering_id	rendering_id, compel_id, status, download_url

download_url GET /api/v1/renderings/{id}/download की ओर इशारा करता है (HTTP Range का समर्थन करता है)। पूर्ण कॉम्पेल/रेंडरिंग प्रतिक्रियाओं में मुफ्त REACT डाउनलोड (https://compeller.ai/download/desktop) और अधिक-जानें URL (https://compeller.ai/react) के साथ एक react हैंडऑफ़ भी शामिल है ताकि एजेंट उपयोगकर्ताओं को बता सकें कि कॉम्पेल को लाइव प्रदर्शन प्रणाली के रूप में कैसे अनुभव किया जाए।

वेबहुक (प्रमाणीकरण आवश्यक)

Compeller के साथ एकीकृत एजेंट get_compel को पोल करने के बजाय कॉम्पेल जीवनचक्र घटनाओं के हस्ताक्षरित पुश सूचनाओं के लिए स्व-पंजीकरण कर सकते हैं। कॉम्पेल के रेंडरेबल होने के क्षण को जानने के लिए compel.ready की सदस्यता लें (फिर start_render कॉल करें) बिना पोलिंग के; compel.completed / compel.failed टर्मिनल घटनाएँ हैं।

टूल	आवश्यक	वैकल्पिक	रिटर्न
register_webhook	url (HTTPS, ≤2048 वर्ण)	events[] — डिफ़ॉल्ट ["*"]; ज्ञात मान: *, compel.ready, compel.completed, compel.failed	webhook_id, url, events, secret (ठीक एक बार लौटाया गया), active, created_at
list_webhooks	—	—	webhooks[] — webhook_id, url, events, active, created_at, updated_at। सीक्रेट इस टूल द्वारा कभी नहीं लौटाए जाते।
update_webhook	webhook_id	url, events[], active — कम से कम एक	webhook_id, url, events, active, created_at, updated_at। सीक्रेट कभी नहीं लौटाए जाते; उसके लिए rotate_webhook_secret का उपयोग करें।
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?। सिंक्रोनस — टूल इंटीग्रेटर के एंडपॉइंट के जवाब की प्रतीक्षा करता है (अधिकतम 5 सेकंड)। सीक्रेट कभी नहीं लौटाए जाते।
rotate_webhook_secret	webhook_id	—	webhook_id, url, events, active, secret (नया — ठीक एक बार लौटाया गया), created_at, updated_at। पुराना सीक्रेट तुरंत अमान्य हो जाता है।

अज्ञात घटना नाम चुपचाप वाइल्डकार्ड * में बदल जाते हैं; यह POST /api/v1/webhooks को दर्शाता है ताकि एजेंट कभी भी नो-ऑप सदस्यता न बनाए।

डिलीवरी कम से कम एक बार होती है। प्रत्येक घटना तुरंत प्रयास की जाती है और, यदि आपका एंडपॉइंट अप्राप्य है या गैर-2xx लौटाता है, तो बैकऑफ़ के साथ पुनः प्रयास किया जाता है — कुल 6 प्रयासों तक (तुरंत, फिर 1 मिनट, 5 मिनट, 30 मिनट, 2 घंटे, 6 घंटे के बाद)। प्रत्येक प्रयास में समान X-Compeller-Event-Id और बाइट-समान हस्ताक्षरित बॉडी होती है, इसलिए उस आईडी पर डीडुप करें। यदि सभी प्रयास समाप्त हो जाते हैं तो घटना छोड़ दी जाती है; get_compel के माध्यम से समाधान करें।

register_webhook आंतरिक बुनियादी ढांचे की ओर इशारा करने वाले गंतव्यों को टूल त्रुटि के साथ अस्वीकार करता है: लूपबैक, RFC1918 निजी रेंज, लिंक-लोकल (क्लाउड मेटाडेटा IP जैसे 169.254.169.254 सहित), IPv6 ULA, CGNAT, मल्टीकास्ट, अनिर्दिष्ट पता, और .local / .internal / .localhost में समाप्त होने वाले होस्टनाम। वही जाँच डिलीवरी समय पर हर प्रयास पर हल किए गए DNS के खिलाफ फिर से चलती है, इसलिए एक होस्टनाम जो पंजीकरण के बाद अवरुद्ध IP पर रीबाइंड होता है, उस प्रयास के लिए छोड़ दिया जाता है (लॉग किया गया); यदि यह अवरुद्ध रहता है तो यह अपना पुनः प्रयास बजट खर्च करता है और फिर छोड़ दिया जाता है।

test_webhook_delivery HMAC-SHA256 हस्ताक्षर के साथ एक सिंथेटिक webhook.test घटना भेजता है और एंडपॉइंट की प्रतिक्रिया के लिए सिंक्रोनस रूप से प्रतीक्षा करता है। यह एंडपॉइंट की सदस्यता ली गई events को अनदेखा करता है (हमेशा वितरित) और वास्तविक डिलीवरी के समान URL सुरक्षा जाँच लागू करता है। गैर-2xx प्रतिक्रिया delivered: false के रूप में दिखाई देती है लेकिन MCP कॉल स्वयं अभी भी सफलतापूर्वक लौटता है — परिणाम पेलोड है।

update_webhook url, events, active में से कोई भी स्वीकार करता है (कम से कम एक)। URL सत्यापन register_webhook को दर्शाता है। सीक्रेट इस टूल द्वारा कभी नहीं लौटाए जाते।

rotate_webhook_secret एक नया 64-वर्ण हेक्स हस्ताक्षर सीक्रेट बनाता है, इसे ठीक एक बार लौटाता है, और पिछले सीक्रेट को तुरंत अमान्य कर देता है। अगली वास्तविक डिलीवरी से पहले प्राप्ति पर नया सीक्रेट संग्रहीत करें।

प्रत्येक डिलीवरी REST पथ की तरह ही हस्ताक्षरित होती है — पूर्ण लिफाफा और हेडर अनुबंध के लिए openapi.yaml का Webhooks अनुभाग देखें।

उदाहरण सत्र

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

चरण 3 की प्रतिक्रिया एक JSON-RPC result है जिसमें content[0].text होता है — स्वयं एक JSON दस्तावेज़ जिसमें webhook_id, secret, आदि होते हैं। secret तुरंत संग्रहीत करें; सर्वर इसे फिर से नहीं लौटाएगा।

त्रुटि कोड

कोड	अर्थ	कारण
-32700	पार्स त्रुटि	बॉडी मान्य JSON नहीं है
-32600	अमान्य अनुरोध	गुम/गलत jsonrpc, गुम method, खाली बॉडी
-32601	विधि नहीं मिली	अज्ञात JSON-RPC विधि
-32602	अमान्य पैरामीटर	अज्ञात टूल, गुम टूल name, गलत params आकार
-32603	आंतरिक त्रुटि	अनहैंडल किया गया अपवाद (सर्वर-साइड लॉग किया गया)

टूल-स्तरीय विफलताएँ (सत्यापन, प्रमाणीकरण, नहीं-मिला) एक सफल JSON-RPC प्रतिक्रिया के अंदर {result: {isError: true, content: [{type: "text", text: "..."}]}} के रूप में लौटाई जाती हैं। यह MCP परंपरा के अनुसार है — यह LLM को विफलता को शब्दशः देखने और सतह पर लाने देता है। एजेंट ऑडियो निर्णय वृक्ष: यदि उपयोगकर्ता MP3/WAV/FLAC प्रदान करता है, तो upload_media का उपयोग करें और फिर create_compel का; यदि उपयोगकर्ता केवल एक गीत/कलाकार स्ट्रिंग प्रदान करता है, तो search_music का उपयोग करें और फिर create_compel_from_music का; जब तक स्पष्ट रूप से उत्पन्न परीक्षण ऑडियो के लिए न कहा जाए, तब तक कोई स्वर संश्लेषित न करें।