Compeller MCP Server

chính thức

Tạo video nhạc AI và hình ảnh phản ứng theo âm thanh từ các bài hát thông qua MCP.

Tài liệu

Điểm cuối MCP của Compeller (`/api/mcp`)

Điểm cuối MCP của Compeller triển khai Giao thức Ngữ cảnh Mô hình dưới dạng một lớp bọc JSON-RPC 2.0 mỏng trên API REST v1 hiện có. Nó dành cho các nhà tích hợp tác tử (Claude Desktop, Cursor, các 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ô.

Phương thức truyền tải: HTTP có thể truyền trực tuyến (một thông điệp JSON-RPC cho mỗi POST HTTP).
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ụ dưới đây là hợp đồng tích hợp công khai. Sử dụng tools/list cho tập hợp được quảng cáo trong thời gian chạy trên máy chủ đã triển khai.
Danh sách 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 yêu cầu một 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 Compeller (cùng mã thông báo được sử dụng bởi /api/v1/*). Các tác tử có thể lấy mã theo một trong hai cách:

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 nó vào kho lưu trữ bí mật của tác tử.
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":"[email protected]","password":"..."}'

Người dùng bình thường nhận được 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 trống.

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ả về mã thông báo API cố định:

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

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

Các phương thức JSON-RPC

Phương thức	Mục đích	Kết quả HTTP
`initialize`	Bắt tay khả năng. Trả về `protocolVersion`, `serverInfo`, `capabilities`.	200 JSON-RPC result
`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ả.	200 JSON-RPC result
`tools/call`	Gọi một công cụ. `params = {name, arguments}`.	200 JSON-RPC result (lỗi công cụ trả về dưới dạng `{isError: true, content: [...]}`)
`ping`	Tín hiệu duy trì kết nối không hoạt động.	200 JSON-RPC `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 không đúng đị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 nhập content duy nhất của type: text có trường text là đầu ra có cấu trú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 báo lỗi mà con người có thể đọc được 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 mà `create_compel` / `create_compel_from_music` chấp nhận cho `style`)

Phương tiện và âm nhạc (yêu cầu 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 yêu cầu xác thực.
`upload_media`	—	`name`, `mime_type`, `type`	Hướng dẫn tải lên trỏ đến `POST /api/v1/media`
`search_media`	—	`type` (`audio`/`image`/`video`/`text`), `limit` (≤100, mặc định 20), `offset`	`media[]`, `paging`

Yêu cầu (yêu cầu 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 yêu cầu đã sẵn sàng; trả về trạng thái và hành động tiếp theo.
`cancel_compel`	`compel_id`	—	Hủy bỏ một yêu cầu đang tiến hành (lũy đẳng — đã HỦY 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 (yêu cầu 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 nhận biết chi phí.

Kết xuất (yêu cầu 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ỏ đến GET /api/v1/renderings/{id}/download (hỗ trợ HTTP Range). Các phản hồi yêu cầu/kết xuất đã hoàn thành cũng bao gồm một bà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) để các tác tử có thể cho người dùng biết cách trải nghiệm yêu cầu như một hệ thống biểu diễn trực tiếp.

Webhook (yêu cầu xác thực)

Các tác tử 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 yêu cầu thay vì thăm dò get_compel. Đăng ký compel.ready để biết thời điểm yêu cầu 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 cuối cùng.

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` (chỉ 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ờ phản hồi từ điểm cuối của nhà tích hợp (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 — chỉ 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 sẽ tự động thu gọn thành ký tự đại diện *; điều này phản ánh POST /api/v1/webhooks để một tác tử không bao giờ tạo ra đăng ký không hoạt động.

Việc gử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 thể truy cập hoặc trả về mã không phải 2xx, sẽ được thử lại với độ trễ tăng dần — tổng cộng tối đa 6 lần thử (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 một X-Compeller-Event-Id và một phần thân đã ký giống hệt byte, vì vậy hãy loại bỏ trùng lặp dựa trên id đó. Nếu tất cả các lần thử đều hết, sự kiện sẽ bị loại bỏ; hãy đối chiếu thông qua get_compel.

register_webhook từ chối các đích đến trỏ đến cơ sở hạ tầng nội bộ với lỗi công cụ: loopback, dải địa chỉ riêng RFC1918, liên kết cục bộ (bao gồm cá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à 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 gửi dựa 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 nó vẫn bị chặn, nó chỉ đơn giản là 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 từ điểm cuối. Nó bỏ qua events đã đăng ký của điểm cuối (luôn được gửi) và áp dụng kiểm tra an toàn URL giống như các lần gửi thực. Phản hồi không phải 2xx được hiển thị dưới dạng delivered: false nhưng chính cuộc 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 ra một bí mật ký hex 64 ký tự mới, trả về nó đú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 được trước lần gửi thực tiếp theo.

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

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à một result JSON-RPC chứa content[0].text — chính 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 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 là 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 trố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ông cụ, hình dạng `params` không tốt
`-32603`	Lỗi nội bộ	Ngoại lệ chưa được 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 một 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 cho tác nhân: nếu người dùng cung cấp MP3/WAV/FLAC, hãy dùng upload_media rồi create_compel; nếu người dùng chỉ cung cấp chuỗi bài hát/nghệ sĩ, hãy dùng search_music rồi 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 tra.