Compeller

공식

MCP를 통해 노래로 AI 뮤직 비디오와 오디오 반응형 비주얼을 제작합니다.

Compeller MCP(으)로 무엇을 할 수 있나요?

플랫폼 기능 탐색 — 어시스턴트에게 get_capabilities 및 get_pricing을 통해 Compeller가 제공하는 기능(스타일, 요금제, 미디어 제한 포함)을 확인하도록 요청하세요.
음악에서 컴펠 생성 — 어시스턴트에게 search_music으로 트랙을 검색하게 한 다음, 선호하는 스타일과 플랫폼으로 create_compel_from_music을 사용하여 컴펠을 생성하세요.
컴펠 진행 상황 추적 — 어시스턴트에게 get_compel을 사용하여 컴펠의 상태와 렌더링 단계를 모니터링하도록 요청하고, 준비되면 start_render로 최종 렌더링을 시작하세요.
웹훅 알림 관리 — 어시스턴트에게 compel.ready 이벤트에 대해 register_webhook으로 웹훅을 등록하도록 지시하여, 폴링 없이 알림을 받으세요.
계정 크레딧 확인 — 비용이 많이 드는 렌더링을 시작하기 전에 어시스턴트에게 get_account_credits로 남은 시간(분)을 확인하도록 요청하여 할당량 초과를 방지하세요.

문서

Compeller MCP 엔드포인트 (`/api/mcp`)

Compeller MCP 엔드포인트는 기존 v1 REST API 위에 얇은 JSON-RPC 2.0 래퍼로 Model Context Protocol을 구현합니다. 원시 HTTP 대신 MCP를 기본적으로 지원하는 에이전트 통합자(Claude Desktop, Cursor, 커스텀 MCP 클라이언트, DigiRAMP)를 대상으로 합니다.

전송: Streamable 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.

그 외 모든 도구는 JSON-RPC 본문이 아닌 HTTP 요청 자체에 전달되는 Compeller API 토큰이 필요합니다. 다음 헤더 중 하나가 작동합니다:

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

토큰은 Compeller User별로 발급됩니다(/api/v1/*에서 사용하는 것과 동일한 토큰). 에이전트는 다음 두 가지 방법 중 하나로 토큰을 얻을 수 있습니다:

사용자에게 로그인을 요청하고 계정 → API 액세스를 열어 토큰을 공개한 후 에이전트의 비밀 저장소에 붙여넣습니다.
기존 로그인 엔드포인트를 사용하고 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는 비어 있지 않은 경우에만 나타납니다.

또는 지속적 API 토큰을 반환하는 v1 인증 헬퍼를 통해 자격 증명을 교환합니다:

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

누락되거나 잘못된 토큰은 JSON-RPC 오류가 아닌 도구 오류(isError: true)로 "API token required." / "Invalid API token." 메시지와 함께 표시되므로 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`	No-op keepalive.	200 JSON-RPC `result: {}`

알 수 없는 메서드는 JSON-RPC 오류 -32601 Method not found을 반환합니다. 알 수 없는 도구 이름은 -32602 Unknown tool을 반환합니다. 잘못된 형식의 JSON 본문은 -32700 Parse error을 반환합니다. 누락/잘못된 jsonrpc 또는 누락된 method은 -32600 Invalid Request을 반환합니다.

도구

모든 도구는 text 필드가 JSON 형식의 구조화된 출력인 단일 type: text 항목의 content을 반환합니다. 실패 시 동일한 응답 형태가 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`	—	`id`, `name`, `monthlyUsd`, `features[]`이 포함된 `plans[]`
`list_styles`	—	`id`, `name`이 포함된 `styles[]` (`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을 취소합니다(멱등 — 이미 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`	`rendering_id`, `status`, `download_url`이 포함된 `compel_id`, `renderings[]`
`get_rendering`	`rendering_id`	`rendering_id`, `compel_id`, `status`, `download_url`

download_url은 GET /api/v1/renderings/{id}/download을 가리킵니다(HTTP Range 지원). 완료된 compel/렌더링 응답에는 무료 REACT 다운로드(https://compeller.ai/download/desktop) 및 자세히 알아보기 URL(https://compeller.ai/react)이 포함된 react 핸드오프도 포함되어 에이전트가 사용자에게 compel을 라이브 공연 시스템으로 경험하는 방법을 알려줄 수 있습니다.

웹훅(인증 필요)

Compeller와 통합하는 에이전트는 get_compel을 폴링하는 대신 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을 반영하므로 에이전트가 no-op 구독을 만들지 않습니다.

전달은 최소 한 번(at-least-once)입니다. 각 이벤트는 즉시 시도되고 엔드포인트에 연결할 수 없거나 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자 16진수 서명 비밀을 생성하고 정확히 한 번 반환하며 이전 비밀을 즉시 무효화합니다. 다음 실제 전달 전에 수신 시 새 비밀을 저장하세요.

모든 전달은 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단계에 대한 응답은 content[0].text을 포함하는 JSON-RPC result입니다 — 자체적으로 webhook_id, secret 등을 포함하는 JSON 문서입니다. 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를 사용합니다. 명시적으로 생성된 테스트 오디오를 요청하지 않는 한 톤을 합성하지 마세요.