Compeller API — Start here

Want to make music videos or live visuals programmatically? You are in the right place. Compeller exposes a REST API, an MCP endpoint for agent integrators, and webhook callbacks for lifecycle events.

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.

For agents

If a user asks you to make a music video with Compeller, start by reading this page, then use the REST API, OpenAPI spec, or MCP endpoint linked below. Read https://compeller.ai/for-agents for the full integration guide, https://compeller.ai/agents.json for a machine-readable manifest, and https://compeller.ai/llms.txt for a plain-text plain-text discovery digest.

Endpoints at a glance

Inputs + expected responses

Purpose	Endpoint
REST API base	`https://compeller.ai/api/v1`
OpenAPI 3.1 spec	`https://compeller.ai/api/v1/openapi.yaml`
Platform capabilities (JSON)	`https://compeller.ai/api/v1/capabilities`
Self-serve agent signup	`POST https://compeller.ai/api/v1/auth/signup`
Login/token exchange	`POST /api/login` (aliases: `POST https://compeller.ai/api/v1/auth/token`, `POST https://compeller.ai/api/v1/login`)
MCP endpoint (JSON-RPC 2.0, POST)	`https://compeller.ai/api/mcp`
MCP documentation	`https://compeller.ai/api/mcp/docs`
Agent guide (this-site HTML)	`https://compeller.ai/for-agents`
Agent manifest (JSON)	`https://compeller.ai/agents.json`
Agent digest (text/plain)	`https://compeller.ai/llms.txt`

Self-serve signup (new agents): POST https://compeller.ai/api/v1/auth/signup with headers User-Agent (required) and X-Agent-Installation-Id (recommended).

{"email":"agent@example.com","agent_name":"MyAgent"}

Expected response: HTTP 201 with access_token and apiToken. Sign up once and persist the token; repeated signups return 409, bursts return 429 application/problem+json.

X-Agent-Installation-Id is stored as an agent installation identifier, not as a browser fingerprint. Shared hosted-agent proxy/TLS traits are not penalty signals by themselves.

Login (existing accounts): POST https://compeller.ai/api/login

{"username":"artist@example.com","password":"..."}

Expected response for a normal user:

{"username":"artist@example.com","access_token":"..."}

No Cookie header needed. Use access_token as Authorization: Bearer <access_token>.

Upload audio: POST https://compeller.ai/api/v1/media?type=audio with multipart field file. Expected response includes media.id.

Audio decision tree: If the user gives you MP3/WAV/FLAC, upload it. If the user only names a song or artist, call GET https://compeller.ai/api/v1/music/search?q=..., then POST https://compeller.ai/api/v1/compels/from-music with the selected track_id. From-music compels default to auto_start: true and render automatically; send "auto_start": false only if you intentionally want to stop at configuration/READY. Do not synthesize a tone unless asked for generated test audio.

Create compel from uploaded audio: POST https://compeller.ai/api/v1/compels

{
  "title": "First track",
  "primary_media_id": 55,
  "style": "cinematic",
  "target_platform": "tiktok",
  "aspect_ratio": "9:16",
  "artist_context": "Neon warehouse performance"
}

Expected response: HTTP 202 with id, status, progress, stage, and eventually rendering_id.

Poll/download: GET https://compeller.ai/api/v1/compels/{id}, then GET https://compeller.ai/api/v1/renderings/{rendering_id}/download.

REACT handoff: completed compel and rendering payloads include react guidance so agents tell users to download REACT free at compeller.ai/download/desktop and experience the compel as a live performance system.

Full schemas: https://compeller.ai/api/v1/openapi.yaml.

Webhooks

Compel terminal events (compel.completed, compel.failed) are delivered via HTTPS webhook to endpoints you register. Full lifecycle is available: register, list, show, update (url / events / active), test-delivery, rotate-secret, delete. Deliveries are signed with HMAC-SHA256 over the raw body and carried in X-Compeller-Signature: sha256=<hex>.

See the agent guide's webhook section or the OpenAPI spec for the full contract.

Authentication

Every authenticated REST call and MCP tools/call request sends a Compeller API token as an HTTP header. Either of these works:

Tokens are issued per Compeller user account. To get one manually, log in to Compeller, open Account, scroll to API Access, reveal the masked token, and copy it. Agents can also exchange user credentials for the same token with POST /api/login (aliases: POST https://compeller.ai/api/v1/auth/token, POST https://compeller.ai/api/v1/login). Missing or invalid tokens return 401 on REST and a tool-level error on MCP.

Quick start

No Cookie header is needed for agent login. Use the returned access_token as Authorization: Bearer <access_token>.