Quickstart
This guide takes you from zero to a finished preview video: get a key, check the price, import a song, start a preview
and poll until the video is ready. Every step has a curl, JavaScript (fetch, Node 18 or newer) and Python
(requests) version.
Before you start
Section titled “Before you start”- A Clipbeat account at studio.clipbeat.app with credits. The account makes its first purchase in Studio before previews can be made through the API.
- A song you own or have the rights to use, reachable as a direct audio link (
.mp3,.m4a,.wav) or a Google Drive or Dropbox share link. The song must be at least 20 seconds long.
-
Create an API key
Section titled “Create an API key”In Clipbeat Studio, open Settings, go to the Developers section and choose Create key under API keys. Copy the key right away: it starts with
cb_live_and is shown only once.Put it in an environment variable so it never ends up in your code:
Terminal window export CLIPBEAT_API_KEY="cb_live_..."More in Authentication.
-
Check the balance and prices
Section titled “Check the balance and prices”Terminal window curl -s https://api.clipbeat.app/v1/balance \-H "Authorization: Bearer $CLIPBEAT_API_KEY"curl -s https://api.clipbeat.app/v1/pricing \-H "Authorization: Bearer $CLIPBEAT_API_KEY"const API = 'https://api.clipbeat.app/v1';const headers = { Authorization: `Bearer ${process.env.CLIPBEAT_API_KEY}` };const balance = await fetch(`${API}/balance`, { headers }).then((r) => r.json());const pricing = await fetch(`${API}/pricing`, { headers }).then((r) => r.json());console.log(balance.usd, pricing.tiers.map((t) => `${t.tier}: $${t.usd}`));import osimport requestsAPI = "https://api.clipbeat.app/v1"headers = {"Authorization": f"Bearer {os.environ['CLIPBEAT_API_KEY']}"}balance = requests.get(f"{API}/balance", headers=headers, timeout=30).json()pricing = requests.get(f"{API}/pricing", headers=headers, timeout=30).json()print(balance["usd"], [(t["tier"], t["usd"]) for t in pricing["tiers"]])The balance response looks like this:
{ "credits": 400, "usd": 20, "credits_per_usd": 20, "topup_url": "https://studio.clipbeat.app/credits" } -
Import the song
Section titled “Import the song”Send the link and confirm your rights.
rights_attestationmust betrueandrights_versionmust be the current version,2026-11-21(see Rights declaration).Terminal window curl -s https://api.clipbeat.app/v1/songs \-H "Authorization: Bearer $CLIPBEAT_API_KEY" \-H "Content-Type: application/json" \-d '{"url":"https://example.com/my-song.mp3","rights_attestation":true,"rights_version":"2026-11-21"}'const API = 'https://api.clipbeat.app/v1';const headers = { Authorization: `Bearer ${process.env.CLIPBEAT_API_KEY}`, 'Content-Type': 'application/json' };const song = await fetch(`${API}/songs`, {method: 'POST',headers,body: JSON.stringify({ url: 'https://example.com/my-song.mp3', rights_attestation: true, rights_version: '2026-11-21' }),}).then((r) => r.json());console.log(song.id, song.status);import osimport requestsAPI = "https://api.clipbeat.app/v1"headers = {"Authorization": f"Bearer {os.environ['CLIPBEAT_API_KEY']}"}song = requests.post(f"{API}/songs",headers=headers,json={"url": "https://example.com/my-song.mp3", "rights_attestation": True, "rights_version": "2026-11-21"},timeout=120,).json()print(song["id"], song["status"])The response is the song object.
201means a new import,200means this account already imported the same audio and you get the existing song back.{"id": "8c5d2f9e-2a51-4f0e-9a43-1f4f3b0d6a21","title": "My Song","duration_sec": 184.3,"status": "processing","lyrics_status": "processing","created_at": "2026-11-22T09:14:03.000Z"}Lyrics are read in the background. Poll
GET /v1/songs/{id}untilstatusisready(usually under a minute). -
Start a preview
Section titled “Start a preview”A preview is a short lip-synced clip of the chorus with an original AI singer.
styleandcharacterare optional and describe the world of the video and the lead.Terminal window curl -s https://api.clipbeat.app/v1/videos \-H "Authorization: Bearer $CLIPBEAT_API_KEY" \-H "Content-Type: application/json" \-d '{"song_id":"SONG_ID","tier":"preview","aspect":"9:16","style":"neon-lit rooftop at night, light rain"}'const API = 'https://api.clipbeat.app/v1';const headers = { Authorization: `Bearer ${process.env.CLIPBEAT_API_KEY}`, 'Content-Type': 'application/json' };const res = await fetch(`${API}/videos`, {method: 'POST',headers,body: JSON.stringify({ song_id: 'SONG_ID', tier: 'preview', aspect: '9:16', style: 'neon-lit rooftop at night, light rain' }),});const video = await res.json();if (res.status === 402) console.log('Add credits:', video.topup_url);else console.log(video.id, video.status);import osimport requestsAPI = "https://api.clipbeat.app/v1"headers = {"Authorization": f"Bearer {os.environ['CLIPBEAT_API_KEY']}"}res = requests.post(f"{API}/videos",headers=headers,json={"song_id": "SONG_ID", "tier": "preview", "aspect": "9:16", "style": "neon-lit rooftop at night, light rain"},timeout=60,)video = res.json()if res.status_code == 402:print("Add credits:", video["topup_url"])else:print(video["id"], video["status"])A started video returns
202 Acceptedwith the video object in statusqueued. -
Poll until it is ready
Section titled “Poll until it is ready”Check every 30 to 60 seconds. When
statusiscompleted,result.video_urlis a download link that stays valid forresult.expires_in_secseconds (24 hours by default). You can always get a fresh link by calling the endpoint again.Terminal window curl -s https://api.clipbeat.app/v1/videos/VIDEO_ID \-H "Authorization: Bearer $CLIPBEAT_API_KEY"const API = 'https://api.clipbeat.app/v1';const headers = { Authorization: `Bearer ${process.env.CLIPBEAT_API_KEY}` };const sleep = (ms) => new Promise((r) => setTimeout(r, ms));let video;do {await sleep(45_000);video = await fetch(`${API}/videos/VIDEO_ID`, { headers }).then((r) => r.json());console.log(video.status, video.progress?.percent ?? 0, '%');} while (video.status === 'queued' || video.status === 'running');console.log(video.result?.video_url ?? video.error);import osimport timeimport requestsAPI = "https://api.clipbeat.app/v1"headers = {"Authorization": f"Bearer {os.environ['CLIPBEAT_API_KEY']}"}while True:time.sleep(45)video = requests.get(f"{API}/videos/VIDEO_ID", headers=headers, timeout=30).json()print(video["status"], (video.get("progress") or {}).get("percent", 0), "%")if video["status"] not in ("queued", "running"):breakprint((video.get("result") or {}).get("video_url") or video.get("error")){"id": "f1e2d3c4-b5a6-4789-8abc-def012345678","status": "completed","tier": "preview","title": "My Song","aspect": "9:16","created_at": "2026-11-22T09:16:40.000Z","progress": { "stage": "done", "done": 3, "total": 3, "percent": 100 },"cost": { "credits_reserved": 100, "credits_charged": 100, "credits_refunded": 0, "usd": 5 },"result": {"video_url": "https://...","poster_url": "https://...","expires_in_sec": 86400},"studio_url": "https://studio.clipbeat.app/"}
Next steps
Section titled “Next steps”- Make the full video: start a new video with
tierset tostandard,plusorpremium. Prices depend on song length; read them withGET /v1/pricing?song_id=.... - Handle every response code your integration can meet: Errors.
- Give an AI assistant the same powers: Connect over MCP.
- See every field: API reference.