Skip to main content
Media are reusable files — video backgrounds, static images, logos, and intro/outro clips — you upload once and reference from presets or project settings. This saves re-uploading the same file every time you render a new track.

​
Media types

TypeDescription
videoLooping background video.
imageStatic background image.
logoLogo overlay.
intro-videoPlays before the karaoke starts.
outro-videoPlays after the karaoke ends.

​
Endpoints

MethodPathPurpose
GET/mediaList media for the authenticated account.
POST/mediaRegister a previously uploaded file as reusable media.
GET/media/{mediaId}Fetch a single media item.
DELETE/media/{mediaId}Delete a media item.
Full request and response schemas are in API reference.

​
Upload flow

Creating a media item is a two-step process. First upload the file bytes, then register the uploaded file as reusable media.
1

Create an upload target

curl -X POST https://api.youka.io/api/v1/uploads \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "background.mp4",
    "contentType": "video/mp4",
    "contentLength": 8421120
  }'
The response contains inputFileId and uploadUrl.
2

PUT the file bytes

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary "@./background.mp4"
3

Register the media item

curl -X POST https://api.youka.io/api/v1/media \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: bg-loop-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "inputFileId": "file_abc123",
    "type": "video"
  }'
The response includes the new mediaId and the media url. Use the url inside presets or project settings.
POST /media does not accept raw file uploads. It expects an inputFileId from a prior POST /uploads + PUT call.

​
List media

curl https://api.youka.io/api/v1/media \
  -H "Authorization: Bearer yk_..."
Returns an array of every reusable media item on the authenticated account.

​
Apply a background

Reference uploaded media from a preset or directly from project settings: 
curl -X PATCH https://api.youka.io/api/v1/projects/prj_abc/settings \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "style": {
        "background": {
          "type": "image",
          "url": "https://cdn.youka.io/backgrounds/bg_abc123.jpg",
          "objectFit": "cover"
        }
      }
    }
  }'

​
Delete media

curl -X DELETE https://api.youka.io/api/v1/media/bg_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: delete-bg_abc123"
Deleting media does not affect projects or exports previously rendered with it. Future renders that reference the deleted media will fall back to the default background.

​
What’s next