Clipbeat API and MCP for AI agents
Give your AI agent a Clipbeat key and it can turn a song into a music video for you: import the song from a link, start a preview or a full video, and check when it is ready. Use it with ChatGPT, Cursor, n8n or any other MCP client.
What your agent can do
- Import a song from a link: a direct audio link or a Google Drive or Dropbox share link. Suno links are not supported, send the audio file link.
- Check the price for that song in each tier before spending anything.
- Start a preview or a full video in Standard, Plus or Premium, in 16:9 or 9:16, with an optional style and lead character.
- Check progress and get the finished video link.
- List your videos and read your credit balance.
Updated
1. Create an API key
Sign in to Clipbeat Studio, open Settings, then Account, and choose Create key under API keys. Give it a name such as "Agent on my laptop". The key starts with cb_live_ and is shown only once, so copy it right away. You can have up to 5 active keys and revoke any of them at any time.
Treat the key like a password: anyone who has it can spend your credits. Do not put it in public code.
2. Connect over MCP
Clipbeat runs a remote MCP server at https://api.clipbeat.app/mcp (Streamable HTTP). Send your key in the header Authorization: Bearer cb_live_.... Replace YOUR_KEY below with your key.
{
"mcpServers": {
"clipbeat": {
"url": "https://api.clipbeat.app/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Tools
create_video_from_song_urlImports a song from a link and starts a video in the tier you pick.
get_video_statusProgress of a video and, when done, the link to watch and download it.
list_my_videosYour recent videos with their status.
get_pricingThe price of each tier for a song, in USD and credits.
get_balanceYour current credit balance and the link to add more.
3. Or call the REST API
Base URL https://api.clipbeat.app/v1, the same key in the Authorization header. The full schema is in the OpenAPI document, which n8n, ChatGPT actions and most HTTP tools can import.
| Endpoint | What it does |
|---|---|
POST /v1/songs | Import a song. Body: {"url": "...", "rights_attestation": true, "rights_version": "2026-11-21"}. The url can be a direct audio link or a Google Drive or Dropbox share link (Suno links are not supported). |
GET /v1/songs/{id} | Song status (processing or ready), length and lyrics status. Start a video once it is ready. |
POST /v1/videos | Start a video. Body: {"song_id": "...", "tier": "preview" | "standard" | "plus" | "premium", "style"?, "character"?, "aspect"?: "16:9" | "9:16", "title"?}. |
GET /v1/videos/{id} | Status, progress, credits and USD spent and, when done, the download link. |
GET /v1/videos | Your videos, newest first. |
GET /v1/pricing?song_id= | Price of each tier for that song. |
GET /v1/balance | Your credit and USD balance and the link to add credits. |
export CLIPBEAT_KEY="cb_live_..."
# 1. Import the song (you confirm you own it or have the rights)
curl -s https://api.clipbeat.app/v1/songs \
-H "Authorization: Bearer $CLIPBEAT_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/my-song.mp3","rights_attestation":true,"rights_version":"2026-11-21"}'
# 2. Check the song until its status is "ready" (lyrics are being read)
curl -s https://api.clipbeat.app/v1/songs/SONG_ID -H "Authorization: Bearer $CLIPBEAT_KEY"
# 3. Start a preview
curl -s https://api.clipbeat.app/v1/videos \
-H "Authorization: Bearer $CLIPBEAT_KEY" \
-H "Content-Type: application/json" \
-d '{"song_id":"SONG_ID","tier":"preview","aspect":"9:16"}'
# 4. Check every minute or so; when it is done the response has the video link
curl -s https://api.clipbeat.app/v1/videos/VIDEO_ID \
-H "Authorization: Bearer $CLIPBEAT_KEY"Rules
- Videos are paid from your Clipbeat credit balance. If the balance is too low, the API answers 402 with a topup_url; you open it and buy credits in Studio. Agents never enter card details.
- Same prices as in Studio: a preview is 5 USD (100 credits), full videos are priced by tier and song length like in Studio (see Pricing). As in Studio, the account makes its first purchase in Studio before previews can be made. Every video made through the API is paid.
- The lead is always an AI character. Real faces and photos of people are not accepted through the API.
- You must own the song or have the rights to use it. Each import confirms this with rights_attestation.
- Briefs that name real people, celebrities or brands, or ask for unsafe content, are rejected with 422.
- Rate limits per key: 60 requests per minute, 10 song imports per hour, 4 new videos per hour.
Prices for each tier are on the pricing page. Questions: [email protected].