# Quickstart

> Make your first Clipbeat music video through the API in five minutes, with curl, JavaScript or Python.

Source: https://docs.clipbeat.app/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.

> **Videos cost credits:**
Steps 1 to 3 are free. Step 4 starts a paid video and reserves its price from the account's credit balance. Read
[Pricing & credits](https://docs.clipbeat.app/pricing/) first.

## Before you start

- A Clipbeat account at [studio.clipbeat.app](https://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.

1. ### Create an API key

   In [Clipbeat Studio](https://studio.clipbeat.app), 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:

   ```bash
   export CLIPBEAT_API_KEY="cb_live_..."
   ```

   More in [Authentication](https://docs.clipbeat.app/authentication/).

2. ### Check the balance and prices

   
   **curl**

   ```bash
   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"
   ```

   
   **JavaScript**

   ```js
   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}`));
   ```

   
   **Python**

   ```python
   import os
   import requests

   API = "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:

   ```json
   { "credits": 400, "usd": 20, "credits_per_usd": 20, "topup_url": "https://studio.clipbeat.app/credits" }
   ```

3. ### Import the song

   Send the link and confirm your rights. `rights_attestation` must be `true` and `rights_version` must be the current
   version, `2026-11-21` (see [Rights declaration](https://docs.clipbeat.app/concepts/rights/)).

   
   **curl**

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

   
   **JavaScript**

   ```js
   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);
   ```

   
   **Python**

   ```python
   import os
   import requests

   API = "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](https://docs.clipbeat.app/concepts/songs/). `201` means a new import, `200` means this account already
   imported the same audio and you get the existing song back.

   ```json
   {
     "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}` until `status` is `ready` (usually under a minute).

4. ### Start a preview

   A preview is a short lip-synced clip of the chorus with an original AI singer. `style` and `character` are optional
   and describe the world of the video and the lead.

   
   **curl**

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

   
   **JavaScript**

   ```js
   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);
   ```

   
   **Python**

   ```python
   import os
   import requests

   API = "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 Accepted` with the [video object](https://docs.clipbeat.app/concepts/video-jobs/) in status `queued`.

5. ### Poll until it is ready

   Check every 30 to 60 seconds. When `status` is `completed`, `result.video_url` is a download link that stays valid
   for `result.expires_in_sec` seconds (24 hours by default). You can always get a fresh link by calling the endpoint
   again.

   
   **curl**

   ```bash
   curl -s https://api.clipbeat.app/v1/videos/VIDEO_ID \
     -H "Authorization: Bearer $CLIPBEAT_API_KEY"
   ```

   
   **JavaScript**

   ```js
   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);
   ```

   
   **Python**

   ```python
   import os
   import time
   import requests

   API = "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"):
           break

   print((video.get("result") or {}).get("video_url") or video.get("error"))
   ```

   
   

   ```json
   {
     "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

- Make the full video: start a new video with `tier` set to `standard`, `plus` or `premium`. Prices depend on song
  length; read them with `GET /v1/pricing?song_id=...`.
- Handle every response code your integration can meet: [Errors](https://docs.clipbeat.app/errors/).
- Give an AI assistant the same powers: [Connect over MCP](https://docs.clipbeat.app/mcp/clients/).
- See every field: [API reference](https://docs.clipbeat.app/api/reference/).
