Compeller

Compeller MCP Uç Noktası (/api/mcp)

Compeller MCP uç noktası, Model Context Protocol'ü mevcut v1 REST API'si üzerinde ince bir JSON-RPC 2.0 sarmalayıcısı olarak uygular. Ham HTTP yerine doğal olarak MCP konuşan aracı entegratörleri (Claude Desktop, Cursor, özel MCP istemcileri, DigiRAMP) için tasarlanmıştır.

• Taşıma: Akışkan HTTP (HTTP POST başına tek JSON-RPC mesajı).
• URL: POST https://compeller.ai/api/mcp
• Protokol sürümü: 2024-11-05
• Sunucu adı / sürümü: compeller-mcp / initialize sonucuna bakın.
• Araç sözleşmesi: Aşağıdaki araç listesi genel entegrasyon sözleşmesidir. Dağıtılan sunucuda çalışma zamanında tanıtılan küme için tools/list kullanın.
• Dizin listeleri: Resmi MCP Kayıt Defteri · Smithery · Glama

Kimlik Doğrulama

Anonim (keşif) yöntemleri: initialize, tools/list, ping, notifications/initialized, ayrıca anonim araçlar get_capabilities, get_pricing, list_styles.

Diğer her araç, HTTP isteğinin kendisinde iletilen bir Compeller API belirteci gerektirir, JSON-RPC gövdesinin içinde değil. Her iki başlık da çalışır:

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

Belirteçler, Compeller User başına verilir (/api/v1/* tarafından kullanılan belirteçlerle aynı). Aracılar bunu iki yoldan biriyle edinebilir:

1. Kullanıcıdan giriş yapmasını isteyin, Hesap → API Erişimi'ni açın, belirteci gösterin ve aracının gizli depolama alanına yapıştırın.
2. Mevcut giriş uç noktasını kullanın ve taşıyıcı belirteç olarak access_token gönderin. Cookie başlığı gerekmez veya beklenmez:

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

Normal kullanıcılar username ve access_token alır. roles yalnızca temel ROLE_COMPELLER ötesinde rollere sahip hesaplar için görünür; refresh_token ve expires_in yalnızca boş olmadıklarında görünür.

3. Veya kalıcı API belirtecini döndüren v1 kimlik doğrulama yardımcısı aracılığıyla kimlik bilgilerini değiştirin:

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

Eksik veya geçersiz bir belirteç, JSON-RPC hatası olarak değil, "API token required." / "Invalid API token." mesajıyla bir araç hatası (isError: true) olarak yüzeye çıkar; böylece MCP istemcileri kullanıcıdan kimlik bilgileri isteyebilir.

JSON-RPC Yöntemleri

Yöntem	Amaç	HTTP sonucu
initialize	Yetenek el sıkışması. protocolVersion, serverInfo, capabilities döndürür.	200 JSON-RPC sonucu
notifications/initialized	İstemci onayı. Yanıt gövdesi yok.	204
tools/list	Şema + açıklama ile her aracı listeler.	200 JSON-RPC sonucu
tools/call	Bir aracı çağırır. params = {name, arguments}.	200 JSON-RPC sonucu (araç hataları {isError: true, content: [...]} olarak geri gelir)
ping	No-op canlı tutma.	200 JSON-RPC result: {}

Bilinmeyen yöntemler JSON-RPC hatası -32601 Method not found döndürür. Bilinmeyen araç adları -32602 Unknown tool döndürür. Hatalı biçimlendirilmiş bir JSON gövdesi -32700 Parse error döndürür. Eksik / yanlış jsonrpc veya eksik method -32600 Invalid Request döndürür.

Araçlar

Tüm araçlar, text alanı JSON biçimli yapılandırılmış çıktı olan tek bir type: text girdisinin content değerini döndürür. Hata durumunda, aynı yanıt şekli isError: true ve content[0].text içinde insan tarafından okunabilir bir hata mesajıyla döndürülür — asla JSON-RPC error olarak değil.

Keşif (kimlik doğrulama yok)

Araç	Girdiler	Döndürür
get_capabilities	—	productName, version, capabilities[], spec_url, enums (styles, target_platforms, aspect_ratios), auth, media_limits, rate_limits
get_pricing	—	id, name, monthlyUsd, features[] ile plans[]
list_styles	—	id, name ile styles[] (id, style için create_compel / create_compel_from_music kabul eden tam değerdir)

Medya ve müzik (aksi belirtilmedikçe kimlik doğrulama gerekli)

Araç	Zorunlu	İsteğe bağlı	Döndürür
search_music	query	limit	create_compel_from_music için uygun genel müzik arama sonuçları. Kimlik doğrulama gerekmez.
upload_media	—	name, mime_type, type	POST /api/v1/media işaret eden yükleme talimatları
search_media	—	type (audio/image/video/text), limit (≤100, varsayılan 20), offset	media[], paging

Compeller'lar (kimlik doğrulama gerekli)

Araç	Zorunlu	İsteğe bağlı	Döndürür
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	—	Compeller hazır olduğunda son işlemeyi başlatır; durumu ve sonraki eylemi döndürür.
cancel_compel	compel_id	—	Devam eden bir compeller'ı iptal eder (idempotent — zaten-İPTAL başarılı olur); compel_id, status: CANCELLED, stage döndürür.
list_compels	—	limit (≤100), offset	compels[], paging
search_compels	query	limit	compels[], count

style, target_platform ve aspect_ratio, araç şemalarındaki enum tarafından kısıtlanır (bkz. get_capabilities.enums); style değerleri doğrudan list_styles'den gelir.

Hesap (kimlik doğrulama gerekli)

Araç	Girdiler	Döndürür
get_account_credits	—	plan, minutes_remaining, free_minutes_remaining, paid_minutes_remaining, minutes_total, quota_exceeded, api_eligible, billing_url — pahalı bir işlemeden önce maliyet bilinçli kararlar vermek için çağırın.

İşlemeler (kimlik doğrulama gerekli)

Araç	Zorunlu	Döndürür
list_renderings	compel_id	compel_id, rendering_id, status, download_url ile renderings[]
get_rendering	rendering_id	rendering_id, compel_id, status, download_url

download_url, GET /api/v1/renderings/{id}/download işaret eder (HTTP Range destekler). Tamamlanan compeller/oluşturma yanıtları ayrıca, aracıların kullanıcılara compeller'ı canlı bir performans sistemi olarak nasıl deneyimleyeceklerini söyleyebilmesi için ücretsiz REACT indirmesi (https://compeller.ai/download/desktop) ve daha fazla bilgi URL'si (https://compeller.ai/react) ile bir react devir teslimi içerir.

Web kancaları (kimlik doğrulama gerekli)

Compeller ile entegre olan aracılar, get_compel yoklamak yerine compeller yaşam döngüsü olaylarının imzalı push bildirimleri için kendi kendine kayıt olabilir. Bir compeller'ın işlenebilir olduğu anı öğrenmek için compel.ready abone olun (sonra start_render çağırın) yoklama yapmadan; compel.completed / compel.failed terminal olaylardır.

Araç	Zorunlu	İsteğe bağlı	Döndürür
register_webhook	url (HTTPS, ≤2048 karakter)	events[] — varsayılan ["*"]; bilinen değerler: *, compel.ready, compel.completed, compel.failed	webhook_id, url, events, secret (yalnızca bir kez döndürülür), active, created_at
list_webhooks	—	—	webhooks[] — webhook_id, url, events, active, created_at, updated_at. Sırlar bu araç tarafından asla döndürülmez.
update_webhook	webhook_id	url, events[], active — en az biri	webhook_id, url, events, active, created_at, updated_at. Sırlar asla döndürülmez; bunun için rotate_webhook_secret kullanın.
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?. Senkron — araç, entegratörün uç noktasının yanıt vermesini bekler (maks 5 sn). Sırlar asla döndürülmez.
rotate_webhook_secret	webhook_id	—	webhook_id, url, events, active, secret (yeni — yalnızca bir kez döndürülür), created_at, updated_at. Eski sır hemen geçersiz kılınır.

Bilinmeyen olay adları sessizce joker karakter *'ye daralır; bu POST /api/v1/webhooks yansıtır, böylece bir aracı asla no-op abonelik oluşturmaz.

Teslimat en az bir kezdir. Her olay hemen denenir ve uç noktanız ulaşılamazsa veya 2xx olmayan bir yanıt döndürürse, geri çekilme ile yeniden denenir — toplam 6 denemeye kadar (hemen, sonra 1dk, 5dk, 30dk, 2sa, 6sa sonra). Her deneme aynı X-Compeller-Event-Id ve bayt-özdeş imzalı gövdeyi taşır, bu nedenle bu kimlik üzerinde yinelenenleri ayıklayın. Tüm denemeler tükenirse olay bırakılır; get_compel aracılığıyla uzlaştırın.

register_webhook, iç altyapıyı işaret eden hedefleri bir araç hatasıyla reddeder: geri döngü, RFC1918 özel aralıklar, bağlantı-yerel (bulut meta veri IP'leri gibi 169.254.169.254 dahil), IPv6 ULA, CGNAT, çok noktaya yayın, belirtilmemiş adres ve .local / .internal / .localhost ile biten ana bilgisayar adları. Aynı kontrol, her denemede çözümlenen DNS'e karşı teslimat zamanında yeniden çalışır; bu nedenle kayıttan sonra engellenen bir IP'ye yeniden bağlanan bir ana bilgisayar adı o deneme için atlanır (günlüğe kaydedilir); engellenmeye devam ederse, yalnızca yeniden deneme bütçesini tüketir ve sonra bırakılır.

test_webhook_delivery, HMAC-SHA256 imzasıyla sentetik bir webhook.test olayı gönderir ve uç noktanın yanıtı için senkron olarak bekler. Uç noktanın abone olduğu events yok sayar (her zaman teslim edilir) ve gerçek teslimatlarla aynı URL güvenlik kontrolünü uygular. 2xx olmayan bir yanıt delivered: false olarak yüzeye çıkar, ancak MCP çağrısının kendisi yine de başarıyla döner — sonuç yüktür.

update_webhook, url, events, active (en az biri) kabul eder. URL doğrulaması register_webhook yansıtır. Sırlar bu araç tarafından asla döndürülmez.

rotate_webhook_secret, taze bir 64 karakterlik onaltılık imzalama sırrı üretir, yalnızca bir kez döndürür ve önceki sırrı hemen geçersiz kılar. Bir sonraki gerçek teslimattan önce yeni sırrı alındığında saklayın.

Her teslim, REST yoluyla tam olarak aynı şekilde imzalanır — tam zarf ve başlık sözleşmesi için openapi.yaml'nın Webhooks bölümüne bakın.

Örnek oturum

# 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. adıma yanıt, content[0].text içeren bir JSON-RPC result'dir — kendisi webhook_id, secret vb. içeren bir JSON belgesidir. secret hemen saklayın; sunucu onu tekrar döndürmez.

Hata kodları

Kod	Anlam	Neden
-32700	Ayrıştırma hatası	Gövde geçerli JSON değil
-32600	Geçersiz İstek	Eksik/yanlış jsonrpc, eksik method, boş gövde
-32601	Yöntem bulunamadı	Bilinmeyen JSON-RPC yöntemi
-32602	Geçersiz parametreler	Bilinmeyen araç, eksik araç name, hatalı params şekli
-32603	İç hata	İşlenmemiş özel durum (sunucu tarafında günlüğe kaydedilir)

Araç düzeyindeki hatalar (doğrulama, kimlik doğrulama, bulunamadı), başarılı bir JSON-RPC yanıtının içinde {result: {isError: true, content: [{type: "text", text: "..."}]}} olarak döndürülür. Bu, MCP kuralı gereğidir — LLM'in hatayı görmesine ve olduğu gibi yüzeye çıkarmasına olanak tanır. Ajan ses karar ağacı: kullanıcı MP3/WAV/FLAC sağlarsa, upload_media ardından create_compel kullanın; kullanıcı yalnızca bir şarkı/sanatçı dizesi sağlarsa, search_music ardından create_compel_from_music kullanın; açıkça üretilmiş test sesi istenmedikçe bir ton sentezlemeyin.