Music API

Browse the built-in music catalog and manage your custom uploaded tracks. Background music is mixed into videos during the final render stage at 15% volume by default.

Custom Uploads

Custom tracks are private to your account. Supported formats: MP3, WAV, OGG, AAC, M4A. Maximum file size: 20 MB. Upload via POST /music/custom.

List Music Catalog

Browse the global background music library with optional mood and tempo filters.

GET/api/v1/music/catalog

• Returns an array of catalog tracks (no pagination wrapper).

• Catalog tracks include mood, tempo, energy_level, bpm, has_vocals, artist, and tags.

Parameters

Parameter Type Description

Parameter	Type	Description
`mood`	string	Filter by mood. calmupbeatelegantenergeticinspiringplayfuldramaticneutralprofessionalcinematic
`tempo`	string	Filter by tempo.
`limit`	integer Default: 50	Max results. 1–200

mood

string

Filter by mood.

calmupbeatelegantenergeticinspiringplayfuldramaticneutralprofessionalcinematic

tempo

string

Filter by tempo.

limit

integer

Default: 50

Max results.

1–200

Request Example

curl -X GET "https://api.u-gen.ai/api/v1/music/catalog?mood=upbeat&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

List Custom Tracks

List all custom music tracks uploaded to your account, sorted by newest first.

GET/api/v1/music/custom

• Returns an array of your custom tracks (no pagination).

• Only active (non-deleted) tracks are returned.

Request Example

curl -X GET https://api.u-gen.ai/api/v1/music/custom \
  -H "X-API-Key: YOUR_API_KEY"

Upload Custom Track

Upload a custom audio file to your music library.

POST/api/v1/music/custom

Form Data

Parameter Type Description

Parameter	Type	Description
`file`REQ	file	Audio file to upload. MP3, WAV, OGG, AAC, or M4A. Max 20 MB.
`title`REQ	string	Display name for the track. 1–255 characters

fileREQ

file

Audio file to upload.

MP3, WAV, OGG, AAC, or M4A. Max 20 MB.

titleREQ

string

Display name for the track.

1–255 characters

Request Example

curl -X POST https://api.u-gen.ai/api/v1/music/custom \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@/path/to/track.mp3" \
  -F "title=My Custom Beat"

Delete Custom Track

Soft-delete a custom track from your library. Built-in catalog tracks cannot be deleted.

DELETE/api/v1/music/custom/{music_id}

• Only custom tracks can be deleted — catalog tracks are read-only.

• Deletion is soft (sets is_active = false). The file remains in storage.

Path

Parameter	Type	Description
`music_id`REQ	string (UUID)	The custom track UUID.

Request Example

curl -X DELETE https://api.u-gen.ai/api/v1/music/custom/f1e2d3c4-b5a6-7890-abcd-ef1234567890 \
  -H "X-API-Key: YOUR_API_KEY"