Compeller

Điểm cuối MCP Compeller (/api/mcp)

Điểm cuối MCP Compeller triển khai Giao thức Ngữ cảnh Mô hình như một lớp bọc JSON-RPC 2.0 mỏng phía trên API REST v1 hiện có. Nó dành cho các nhà tích hợp tác nhân (Claude Desktop, Cursor, máy khách MCP tùy chỉnh, DigiRAMP) sử dụng MCP một cách tự nhiên thay vì HTTP thô.

• Giao thức vận chuyển: HTTP có thể truyền phát (một thông điệp JSON-RPC trên mỗi HTTP POST).
• URL: POST https://compeller.ai/api/mcp
• Phiên bản giao thức: 2024-11-05
• Tên / phiên bản máy chủ: compeller-mcp / xem kết quả initialize.
• Hợp đồng công cụ: Danh sách công cụ bên dưới là hợp đồng tích hợp công khai. Sử dụng tools/list để lấy bộ công cụ được quảng bá khi chạy trên máy chủ đã triển khai.
• Danh bạ thư mục: Sổ đăng ký MCP chính thức · Smithery · Glama

Xác thực

Các phương thức ẩn danh (khám phá): initialize, tools/list, ping, notifications/initialized, cùng với các công cụ ẩn danh get_capabilities, get_pricing, list_styles.

Mọi công cụ khác đều yêu cầu mã thông báo API Compeller được truyền trên chính yêu cầu HTTP, không phải bên trong phần thân JSON-RPC. Một trong hai tiêu đề đều hoạt động:

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

Mã thông báo được cấp cho mỗi User của Compeller (cùng mã thông báo được sử dụng bởi /api/v1/*). Tác nhân có thể lấy một mã theo một trong hai cách:

1. Yêu cầu người dùng đăng nhập, mở Tài khoản → Truy cập API, hiển thị mã thông báo và dán vào kho bí mật của tác nhân.
2. Sử dụng điểm cuối đăng nhập hiện có và gửi access_token làm mã thông báo bearer. Không cần hoặc mong đợi tiêu đề Cookie:

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

Người dùng thông thường nhận username và access_token. roles chỉ xuất hiện cho các tài khoản có vai trò vượt quá ROLE_COMPELLER cơ bản; refresh_token và expires_in chỉ xuất hiện khi không rỗng.

3. Hoặc trao đổi thông tin xác thực thông qua trình trợ giúp xác thực v1, trình này trả về mã thông báo API bền vững:

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

Mã thông báo bị thiếu hoặc không hợp lệ xuất hiện dưới dạng lỗi công cụ (isError: true) với thông điệp "API token required." / "Invalid API token.", không phải là lỗi JSON-RPC, để máy khách MCP có thể nhắc người dùng cung cấp thông tin xác thực.

Phương thức JSON-RPC

Phương thức	Mục đích	Kết quả HTTP
initialize	Bắt tay năng lực. Trả về protocolVersion, serverInfo, capabilities.	Kết quả JSON-RPC 200
notifications/initialized	Xác nhận của máy khách. Không có phần thân phản hồi.	204
tools/list	Liệt kê mọi công cụ với lược đồ + mô tả.	Kết quả JSON-RPC 200
tools/call	Gọi một công cụ. params = {name, arguments}.	Kết quả JSON-RPC 200 (lỗi công cụ trả về dưới dạng {isError: true, content: [...]})
ping	Giữ kết nối không thao tác.	JSON-RPC 200 result: {}

Các phương thức không xác định trả về lỗi JSON-RPC -32601 Method not found. Tên công cụ không xác định trả về -32602 Unknown tool. Phần thân JSON sai định dạng trả về -32700 Parse error. Thiếu / sai jsonrpc hoặc thiếu method trả về -32600 Invalid Request.

Công cụ

Tất cả các công cụ trả về một mục content duy nhất của type: text có trường text là đầu ra có cấu trúc được định dạng JSON. Khi thất bại, cùng một hình dạng phản hồi được trả về với isError: true và thông điệp lỗi dễ đọc cho con người trong content[0].text — không bao giờ là error JSON-RPC.

Khám phá (không cần xác thực)

Công cụ	Đầu vào	Trả về
get_capabilities	—	productName, version, capabilities[], spec_url, enums (styles, target_platforms, aspect_ratios), auth, media_limits, rate_limits
get_pricing	—	plans[] với id, name, monthlyUsd, features[]
list_styles	—	styles[] với id, name (id là giá trị chính xác create_compel / create_compel_from_music chấp nhận cho style)

Phương tiện và âm nhạc (cần xác thực trừ khi được ghi chú)

Công cụ	Bắt buộc	Tùy chọn	Trả về
search_music	query	limit	Kết quả tìm kiếm nhạc công khai phù hợp cho create_compel_from_music. Không cần xác thực.
upload_media	—	name, mime_type, type	Hướng dẫn tải lên trỏ tới POST /api/v1/media
search_media	—	type (audio/image/video/text), limit (≤100, mặc định 20), offset	media[], paging

Compels (cần xác thực)

Công cụ	Bắt buộc	Tùy chọn	Trả về
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	—	Bắt đầu kết xuất cuối cùng khi compel đã sẵn sàng; trả về trạng thái và hành động tiếp theo.
cancel_compel	compel_id	—	Hủy một compel đang tiến hành (idempotent — đã-CANCELLED vẫn thành công); trả về compel_id, status: CANCELLED, stage.
list_compels	—	limit (≤100), offset	compels[], paging
search_compels	query	limit	compels[], count

style, target_platform, và aspect_ratio bị ràng buộc bởi enum trong lược đồ công cụ (xem get_capabilities.enums); các giá trị style đến trực tiếp từ list_styles.

Tài khoản (cần xác thực)

Công cụ	Đầu vào	Trả về
get_account_credits	—	plan, minutes_remaining, free_minutes_remaining, paid_minutes_remaining, minutes_total, quota_exceeded, api_eligible, billing_url — gọi trước khi kết xuất tốn kém để đưa ra quyết định có ý thức về chi phí.

Kết xuất (cần xác thực)

Công cụ	Bắt buộc	Trả về
list_renderings	compel_id	compel_id, renderings[] với rendering_id, status, download_url
get_rendering	rendering_id	rendering_id, compel_id, status, download_url

download_url trỏ tới GET /api/v1/renderings/{id}/download (hỗ trợ HTTP Range). Các phản hồi compel/kết xuất hoàn tất cũng bao gồm chuyển giao react với bản tải xuống REACT miễn phí (https://compeller.ai/download/desktop) và URL tìm hiểu thêm (https://compeller.ai/react) để tác nhân có thể cho người dùng biết cách trải nghiệm compel như một hệ thống biểu diễn trực tiếp.

Webhooks (cần xác thực)

Các tác nhân tích hợp với Compeller có thể tự đăng ký nhận thông báo đẩy đã ký về các sự kiện vòng đời compel thay vì thăm dò get_compel. Đăng ký compel.ready để biết thời điểm compel có thể kết xuất (sau đó gọi start_render) mà không cần thăm dò; compel.completed / compel.failed là các sự kiện kết thúc.

Công cụ	Bắt buộc	Tùy chọn	Trả về
register_webhook	url (HTTPS, ≤2048 ký tự)	events[] — mặc định là ["*"]; các giá trị đã biết: *, compel.ready, compel.completed, compel.failed	webhook_id, url, events, secret (được trả về đúng một lần), active, created_at
list_webhooks	—	—	webhooks[] — webhook_id, url, events, active, created_at, updated_at. Bí mật không bao giờ được trả về bởi công cụ này.
update_webhook	webhook_id	url, events[], active — ít nhất một	webhook_id, url, events, active, created_at, updated_at. Bí mật không bao giờ được trả về; sử dụng rotate_webhook_secret cho việc đó.
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?. Đồng bộ — công cụ chờ điểm cuối của nhà tích hợp phản hồi (tối đa 5 giây). Bí mật không bao giờ được trả về.
rotate_webhook_secret	webhook_id	—	webhook_id, url, events, active, secret (mới — được trả về đúng một lần), created_at, updated_at. Bí mật cũ bị vô hiệu hóa ngay lập tức.

Các tên sự kiện không xác định âm thầm thu gọn về ký tự đại diện *; điều này phản ánh POST /api/v1/webhooks để tác nhân không bao giờ tạo đăng ký không hoạt động.

Phân phối là ít nhất-một-lần. Mỗi sự kiện được thử ngay lập tức và, nếu điểm cuối của bạn không truy cập được hoặc trả về mã không phải 2xx, sẽ được thử lại với backoff — tối đa 6 lần thử tổng cộng (ngay lập tức, sau đó sau 1 phút, 5 phút, 30 phút, 2 giờ, 6 giờ). Mỗi lần thử mang cùng X-Compeller-Event-Id và phần thân đã ký giống hệt từng byte, vì vậy hãy loại bỏ trùng lặp trên id đó. Nếu tất cả các lần thử đều cạn kiệt, sự kiện sẽ bị loại bỏ; đối chiếu qua get_compel.

register_webhook từ chối các đích trỏ tới hạ tầng nội bộ với lỗi công cụ: loopback, dải riêng RFC1918, link-local (bao gồm cả IP siêu dữ liệu đám mây như 169.254.169.254), IPv6 ULA, CGNAT, multicast, địa chỉ không xác định và các tên máy chủ kết thúc bằng .local / .internal / .localhost. Kiểm tra tương tự được chạy lại tại thời điểm phân phối trên DNS đã phân giải cho mỗi lần thử, vì vậy tên máy chủ liên kết lại với IP bị chặn sau khi đăng ký sẽ bị bỏ qua cho lần thử đó (được ghi nhật ký); nếu vẫn bị chặn, nó chỉ tiêu thụ ngân sách thử lại và sau đó bị loại bỏ.

test_webhook_delivery gửi một sự kiện webhook.test tổng hợp với chữ ký HMAC-SHA256 và chờ đồng bộ phản hồi của điểm cuối. Nó bỏ qua events đã đăng ký của điểm cuối (luôn được phân phối) và áp dụng cùng kiểm tra an toàn URL như phân phối thực. Phản hồi không phải 2xx được hiển thị dưới dạng delivered: false nhưng bản thân lệnh gọi MCP vẫn trả về thành công — kết quả là tải trọng.

update_webhook chấp nhận bất kỳ url, events, active nào (ít nhất một). Xác thực URL phản ánh register_webhook. Bí mật không bao giờ được trả về bởi công cụ này.

rotate_webhook_secret tạo một bí mật ký hex 64 ký tự mới, trả về đúng một lần và vô hiệu hóa bí mật trước đó ngay lập tức. Lưu trữ bí mật mới khi nhận trước lần phân phối thực tiếp theo.

Mỗi lần phân phối được ký giống hệt đường dẫn REST — xem phần Webhooks của openapi.yaml để biết toàn bộ phong bì và hợp đồng tiêu đề.

Phiên ví dụ

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

Phản hồi cho bước 3 là result JSON-RPC chứa content[0].text — bản thân nó là một tài liệu JSON với webhook_id, secret, v.v. Lưu trữ secret ngay lập tức; máy chủ sẽ không trả lại lần nữa.

Mã lỗi

Mã	Ý nghĩa	Nguyên nhân
-32700	Lỗi phân tích cú pháp	Phần thân không phải JSON hợp lệ
-32600	Yêu cầu không hợp lệ	Thiếu/sai jsonrpc, thiếu method, phần thân rỗng
-32601	Không tìm thấy phương thức	Phương thức JSON-RPC không xác định
-32602	Tham số không hợp lệ	Công cụ không xác định, thiếu name của công cụ, hình dạng params sai
-32603	Lỗi nội bộ	Ngoại lệ chưa xử lý (được ghi nhật ký phía máy chủ)

Các lỗi cấp công cụ (xác thực, xác thực, không tìm thấy) được trả về bên trong phản hồi JSON-RPC thành công dưới dạng {result: {isError: true, content: [{type: "text", text: "..."}]}}. Điều này theo quy ước MCP — nó cho phép LLM nhìn thấy và hiển thị lỗi nguyên văn. Cây quyết định âm thanh của agent: nếu người dùng cung cấp MP3/WAV/FLAC, hãy sử dụng upload_media rồi đến create_compel; nếu người dùng chỉ cung cấp chuỗi tên bài hát/nghệ sĩ, hãy sử dụng search_music rồi đến create_compel_from_music; không tổng hợp âm thanh trừ khi được yêu cầu rõ ràng để tạo âm thanh kiểm thử.