# Clipbeat developer docs

> Turn a song into a music video from your code or your AI agent, with the Clipbeat REST API or the remote MCP server.

Source: https://docs.clipbeat.app/

Clipbeat turns a song into a music video. You send a link to the audio, Clipbeat reads the lyrics, plans the scenes,
casts an original AI singer and renders a video that is cut to the beat and lip-synced to the vocal. The same engine
that runs [Clipbeat Studio](https://studio.clipbeat.app) is available to developers in two ways:

  ### REST API

    Plain HTTPS and JSON at `https://api.clipbeat.app/v1`. Import a song, start a video, poll its status, download the
    file. Described by an [OpenAPI 3.1 schema](https://api.clipbeat.app/v1/openapi.json).
  
  ### MCP server

    A remote Model Context Protocol server at `https://api.clipbeat.app/mcp` (Streamable HTTP). Five tools that let an
    AI assistant make a music video for its user.
  

## Who it is for

- **Developers** who want to add music videos to an app, a distribution tool or a workflow (n8n
  automations, internal tools, release scripts).
- **AI agents and assistants** that make a video when a musician asks for one, without the musician leaving the chat.
- **Musicians with a technical setup** who want to script their own releases.

## How it works

```text
your song link ──▶ POST /v1/songs ──▶ song "ready" ──▶ POST /v1/videos ──▶ poll GET /v1/videos/{id} ──▶ result.video_url
                   (rights_attestation)  (lyrics read)    (credits reserved)   (queued, running, completed)
```

1. **Import a song** from a direct audio link or a Google Drive or Dropbox share link. You confirm that you own the song
   or have the rights to use it.
2. **Start a video** in one of four tiers: `preview` (a short lip-synced chorus clip) or a full video in `standard`,
   `plus` or `premium`.
3. **Poll** until the video is `completed`, then download it from `result.video_url`.

Payment comes from the account's Clipbeat credit balance, at the same prices as Clipbeat Studio. When the balance is
too low the API answers `402` with a `topup_url` for the account owner. Card details never go through the API.

## Start here

  - [Quickstart](https://docs.clipbeat.app/quickstart/): Your first video in five minutes with curl, JavaScript or Python.
  - [Authentication](https://docs.clipbeat.app/authentication/): Create, store and revoke API keys.
  - [Connect an AI client over MCP](https://docs.clipbeat.app/mcp/clients/): Claude, Cursor, VS Code, ChatGPT, n8n and any Streamable HTTP client.
  - [API reference](https://docs.clipbeat.app/api/reference/): Every endpoint, parameter and response, generated from the OpenAPI schema.

## Good to know

- **Base URL:** `https://api.clipbeat.app` (REST under `/v1`, MCP at `/mcp`).
- **Auth:** `Authorization: Bearer cb_live_...` personal API key, created in Clipbeat Studio settings.
- **Format:** JSON in, JSON out. Field names are `snake_case`, ids are UUIDs, timestamps are ISO 8601 in UTC.
- **Long running work:** videos take minutes, not seconds. Start, then poll every 30 to 60 seconds.
- **Original AI characters only:** the lead is always an AI character. See the [content policy](https://docs.clipbeat.app/content-policy/).
- **For language models:** this site publishes [/llms.txt](https://docs.clipbeat.app/llms.txt) and [/llms-full.txt](https://docs.clipbeat.app/llms-full.txt), and every
  page is available as Markdown (use **View as Markdown** at the top of each page).
