Compeller

Compeller MCP 端点（/api/mcp）

Compeller MCP 端点将模型上下文协议实现为现有 v1 REST API 之上的轻量 JSON-RPC 2.0 封装。它面向原生使用 MCP 而非原始 HTTP 的代理集成方（Claude Desktop、Cursor、自定义 MCP 客户端、DigiRAMP）。

• 传输方式： 流式 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 作为 Bearer 令牌发送。不需要也不期望 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 认证辅助工具交换凭据，该工具返回持久 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

Compels（需要认证）

工具	必需	可选	返回
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	—	当 compel 就绪时开始最终渲染；返回状态和下一步操作。
cancel_compel	compel_id	—	取消进行中的 compel（幂等——已取消的也成功）；返回 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）。已完成的 compel/渲染响应还包括 react 交接，包含免费 REACT 下载（https://compeller.ai/download/desktop）和了解更多 URL（https://compeller.ai/react），以便代理告知用户如何将 compel 作为现场表演系统体验。

Webhooks（需要认证）

与 Compeller 集成的代理可以自行注册以接收 compel 生命周期事件的签名推送通知，而不是轮询 get_compel。订阅 compel.ready 以在 compel 可渲染时立即获知（然后调用 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 和字节相同的签名请求体，因此请基于该 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 能够逐字查看并呈现失败信息。 Agent 音频决策树：如果用户提供 MP3/WAV/FLAC 文件，则使用 upload_media 然后使用 create_compel；如果用户仅提供歌曲/艺术家字符串，则使用 search_music 然后使用 create_compel_from_music；除非明确要求生成测试音频，否则不要合成音调。