> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Media

> Reusable backgrounds, logos, and intro/outro videos

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.

<Steps>
  <Step title="Create an upload target">
    ```bash theme={null}
    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`.
  </Step>

  <Step title="PUT the file bytes">
    ```bash theme={null}
    curl -X PUT "$UPLOAD_URL" \
      -H "Content-Type: video/mp4" \
      --data-binary "@./background.mp4"
    ```
  </Step>

  <Step title="Register the media item">
    ```bash theme={null}
    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.
  </Step>
</Steps>

<Note>
  `POST /media` does not accept raw file uploads. It expects an `inputFileId`
  from a prior `POST /uploads` + `PUT` call.
</Note>

## List media

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
curl -X DELETE https://api.youka.io/api/v1/media/bg_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: delete-bg_abc123"
```

<Warning>
  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.
</Warning>

## What's next

* [Render settings reference](/en/render-settings-reference) — all shared field paths and enum values
* [Presets](/en/api/presets) — bundle media with other render settings
* [Project settings](/en/api/project-settings) — apply backgrounds to a project
* [SDK media](/en/sdk/media) — the same flow in TypeScript