Skip to content

Songs

View as Markdown

A song is an audio file imported into the account. Every video starts from a song. Import it once and start as many videos from it as you like.

POST /v1/songs takes a public https link in url:

Source Example
Direct audio file https://example.com/my-song.mp3 (the path must end in .mp3, .m4a or .wav)
Google Drive A file share link (drive.google.com/file/d/...), shared with “Anyone with the link”
Dropbox A share link to the file

Not accepted:

  • Suno page links (suno.com/...). Download the audio from Suno and send a direct link to the file instead. The API answers 400 suno_link_not_supported.
  • Streaming pages (YouTube, Spotify, SoundCloud and similar), private links, links that need a login, and anything that is not an audio file (400 unsupported_link or 400 invalid_audio).
  • Files larger than 100 MB (413 too_large). Links are followed through at most 3 redirects.

The song must be at least 20 seconds long to make a video. Songs up to about 20 minutes are supported.

Every import must include "rights_attestation": true and the current rights_version. See Rights declaration.

After import Clipbeat reads the lyrics and their timing in the background. While that runs the song has status: "processing". When it is done the song is ready and you can start a video.

  • Poll GET /v1/songs/{id} every few seconds, usually ready in under a minute.
  • POST /v1/videos also waits up to 20 seconds for a song that is still processing. If it is still not ready, you get 409 song_processing with retry_after_sec: 30.
  • A song whose lyrics could not be read (an instrumental, for example) is still ready, with lyrics_status: "failed". You can still make a video from it.

Importing the same audio again into the same account returns the existing song with 200 instead of 201.

{
"id": "8c5d2f9e-2a51-4f0e-9a43-1f4f3b0d6a21",
"title": "My Song",
"duration_sec": 184.3,
"status": "ready",
"lyrics_status": "ready",
"created_at": "2026-11-22T09:14:03.000Z"
}
Field Type Description
id string (UUID) Song id. Use it as song_id in POST /v1/videos and GET /v1/pricing.
title string or null Title read from the file or link.
duration_sec number or null Length in seconds. Full video prices depend on it.
status processing, ready Whether a video can be started.
lyrics_status processing, ready, failed Lyrics and timing detection.
created_at string (ISO 8601) or null When the song was imported.
  • 10 song imports per account per hour (429 rate_limited, retry_after_sec: 360). Failed imports do not count.
  • See Rate limits.