# Songs

> How a song gets into Clipbeat, which links are accepted, and the song object.

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

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

## Rights

Every import must include `"rights_attestation": true` and the current `rights_version`. See
[Rights declaration](https://docs.clipbeat.app/concepts/rights/).

## 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/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`.

## The song object

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

- 10 song imports per account per hour (`429 rate_limited`, `retry_after_sec: 360`). Failed imports do not count.
- See [Rate limits](https://docs.clipbeat.app/rate-limits/).
