Media

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

Type	Description
`video`	Looping background video.
`image`	Static background image.
`logo`	Logo overlay.
`intro-video`	Plays before the karaoke starts.
`outro-video`	Plays after the karaoke ends.

Endpoints

Method	Path	Purpose
`GET`	`/media`	List media for the authenticated account.
`POST`	`/media`	Register 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.

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.

PUT the file bytes

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

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

Render settings reference — all shared field paths and enum values
Presets — bundle media with other render settings
Project settings — apply backgrounds to a project
SDK media — the same flow in TypeScript

Guides

Resources

API Reference

Media types

Endpoints

Upload flow

List media

Apply a background

Delete media

What’s next

​Media types

​Endpoints

​Upload flow

​List media

​Apply a background

​Delete media

​What’s next

Media types

Endpoints

Upload flow

List media

Apply a background

Delete media

What’s next