Songs
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.
Accepted links
Section titled “Accepted links”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 answers400 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_linkor400 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.
Rights
Section titled “Rights”Every import must include "rights_attestation": true and the current rights_version. See
Rights declaration.
Processing
Section titled “Processing”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/videosalso waits up to 20 seconds for a song that is still processing. If it is still not ready, you get409 song_processingwithretry_after_sec: 30.- A song whose lyrics could not be read (an instrumental, for example) is still
ready, withlyrics_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.
The song object
Section titled “The song object”{ "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. |
Limits
Section titled “Limits”- 10 song imports per account per hour (
429 rate_limited,retry_after_sec: 360). Failed imports do not count. - See Rate limits.