COMPELLER.AI

Compeller for Agents

Compeller turns music into visuals for live performance and promo content via a patent-pending real-time audio-driven show pipeline. This page is a self-contained integration guide for autonomous agents, LLMs, and integrator tooling.

What is a compel?

A Compel is a music-driven video/visual project.

To make a video for a song: create or select a Compel, configure the style and treatment, generate scenes and renderings, then download the result or receive webhook callbacks.

New here?

The short orientation page at https://compeller.ai/api is a faster entry point — one screen with the five links you need. This page goes deeper.

What you can do

Upload audio media and create a compel (a music-video generation job).
Poll the compel status or subscribe to signed webhook notifications.
Download finished renderings with HTTP Range support.
List and search past compels and renderings on the caller's account.
Register, update, rotate, test, and delete webhook endpoints for push delivery.

Discovery links

REST API base — https://compeller.ai/api/v1 — open
OpenAPI 3.1 spec — https://compeller.ai/api/v1/openapi.yaml — open
MCP endpoint — https://compeller.ai/api/mcp (POST JSON-RPC 2.0)
LLM-oriented digest — https://compeller.ai/llms.txt — open llms.txt
Machine manifest — https://compeller.ai/agents.json — open agents.json

REST API

REST API base: https://compeller.ai/api/v1. Full OpenAPI 3.1 specification: https://compeller.ai/api/v1/openapi.yaml. All resources are JSON; errors follow RFC 7807 (application/problem+json).

Method	Path	Purpose
GET	`/api/v1/capabilities`	Platform capabilities summary
POST	`/api/v1/media`	Upload audio or reference media
POST	`/api/v1/compels`	Create a compel from uploaded media
GET	`/api/v1/compels/{id}`	Get compel status and progress
POST	`/api/v1/compels/{id}/cancel`	Cancel an in-flight compel
GET	`/api/v1/compels/{id}/renderings`	List renderings for a compel
GET	`/api/v1/renderings/{id}/download`	Download the rendered video (supports Range)

MCP endpoint

Compeller exposes a Model Context Protocol server over HTTP at https://compeller.ai/api/mcp. Transport is Streamable HTTP: one JSON-RPC 2.0 message per HTTP POST. Protocol version 2024-11-05.

Supported methods: initialize, tools/list, tools/call, ping, notifications/initialized. See the MCP documentation for the complete tool catalogue and example session.

Tool groups: discovery (get_capabilities, get_pricing, list_styles), media (upload_media, search_media), compels (create_compel, get_compel, list_compels, search_compels), renderings (list_renderings, get_rendering), webhooks (register_webhook, list_webhooks, update_webhook, delete_webhook, test_webhook_delivery, rotate_webhook_secret).

Webhooks

Register an HTTPS endpoint to receive signed push notifications for compel terminal events. The signing secret is returned exactly once at registration and can be rotated later. Deliveries are signed with HMAC-SHA256 over the raw request body, carried in the X-Compeller-Signature header as sha256=<hex>.

Method	Path	Purpose
POST	`/api/v1/webhooks`	Register endpoint; returns `secret` exactly once
GET	`/api/v1/webhooks`	List endpoints for the caller's account
GET	`/api/v1/webhooks/{id}`	Show one endpoint (secret redacted)
PATCH	`/api/v1/webhooks/{id}`	Update `url`, `events`, or `active`
DELETE	`/api/v1/webhooks/{id}`	Remove endpoint
POST	`/api/v1/webhooks/{id}/test`	Synthetic `webhook.test` delivery, returns result synchronously
POST	`/api/v1/webhooks/{id}/rotate-secret`	Mint a new signing secret; invalidates the old one immediately

Event types published today: compel.completed, compel.failed. A synthetic webhook.test event is available on demand via the test endpoint (not subscribable).

Authentication

Every authenticated REST call and MCP tools/call requires a Compeller API token on the HTTP request itself (not inside the JSON-RPC body). Either header works:

Authorization: Bearer <your-api-token>

X-API-Token: <your-api-token>

Tokens are issued per Compeller user account and scope every request to that account. Missing or invalid tokens return 401 on REST and a tool-level error on MCP.

Quick start

1. Inspect the OpenAPI spec

curl -s https://compeller.ai/api/v1/openapi.yaml

2. Create a compel (REST)

curl -s -X POST https://compeller.ai/api/v1/compels \\
  -H 'Authorization: Bearer <your-api-token>' \\
  -H 'Content-Type: application/json' \\
  -d '{"title":"First track","primary_media_id":42}'

3. MCP handshake + tool list

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

curl -s https://compeller.ai/api/mcp \\
  -H 'Content-Type: application/json' \\
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

4. Register a webhook endpoint (MCP)

curl -s https://compeller.ai/api/mcp \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer <your-api-token>' \\
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"register_webhook","arguments":{"url":"https://hooks.my-agent.example/compeller","events":["compel.completed","compel.failed"]}}}'

Store the returned secret immediately — it will not be returned again.

Self-description served at https://compeller.ai/for-agents. See also https://compeller.ai/llms.txt (plain text digest) and https://compeller.ai/agents.json (machine manifest).