Skip to content

Quickstart

View as Markdown

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.

  • 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.
  1. 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.

  2. 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"

    The balance response looks like this:

    { "credits": 400, "usd": 20, "credits_per_usd": 20, "topup_url": "https://studio.clipbeat.app/credits" }
  3. 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).

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

    The response is the song object. 201 means a new import, 200 means 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} until status is ready (usually under a minute).

  4. 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.

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

    A started video returns 202 Accepted with the video object in status queued.

  5. 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.

    Terminal window
    curl -s https://api.clipbeat.app/v1/videos/VIDEO_ID \
    -H "Authorization: Bearer $CLIPBEAT_API_KEY"
    {
    "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/"
    }
  • 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.
  • Give an AI assistant the same powers: Connect over MCP.
  • See every field: API reference.