> ## 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

> Sfondi, loghi e video intro/outro riutilizzabili

I media sono file riutilizzabili — sfondi video, immagini statiche, loghi e clip intro/outro — che carichi una sola volta e richiami da preset o dalle impostazioni del progetto. Questo evita di ricaricare lo stesso file ogni volta che esegui il rendering di una nuova traccia.

## Tipi di media

| Tipo          | Descrizione                            |
| ------------- | -------------------------------------- |
| `video`       | Video di sfondo in loop.               |
| `image`       | Immagine di sfondo statica.            |
| `logo`        | Overlay del logo.                      |
| `intro-video` | Riproduce prima che inizi il karaoke.  |
| `outro-video` | Riproduce dopo che finisce il karaoke. |

## Endpoint

| Metodo   | Path               | Scopo                                                              |
| -------- | ------------------ | ------------------------------------------------------------------ |
| `GET`    | `/media`           | Elenca i media dell’account autenticato.                           |
| `POST`   | `/media`           | Registra un file caricato in precedenza come media riutilizzabile. |
| `GET`    | `/media/{mediaId}` | Recupera un singolo elemento media.                                |
| `DELETE` | `/media/{mediaId}` | Elimina un elemento media.                                         |

Gli schemi completi di richiesta e risposta sono in **API reference**.

## Flusso di upload

La creazione di un elemento media è un processo in due passaggi. Prima carichi i byte del file, poi registri il file caricato come media riutilizzabile.

<Steps>
  <Step title="Crea una destinazione di upload">
    ```bash theme={null}
    curl -X POST https://api.youka.io/it/api/v1/uploads \
      -H "Authorization: Bearer yk_..." \
      -H "Content-Type: application/json" \
      -d '{
        "filename": "background.mp4",
        "contentType": "video/mp4",
        "contentLength": 8421120
      }'
    ```

    La risposta contiene `inputFileId` e `uploadUrl`.
  </Step>

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

  <Step title="Registra l’elemento media">
    ```bash theme={null}
    curl -X POST https://api.youka.io/it/api/v1/media \
      -H "Authorization: Bearer yk_..." \
      -H "Idempotency-Key: bg-loop-v1" \
      -H "Content-Type: application/json" \
      -d '{
        "inputFileId": "file_abc123",
        "type": "video"
      }'
    ```

    La risposta include il nuovo `mediaId` e l’`url` del media. Usa l’`url` all’interno di preset o delle impostazioni del progetto.
  </Step>
</Steps>

<Note>
  `POST /media` non accetta upload di file grezzi. Si aspetta un `inputFileId`
  da una chiamata precedente `POST /uploads` + `PUT`.
</Note>

## Elenca i media

```bash theme={null}
curl https://api.youka.io/it/api/v1/media \
  -H "Authorization: Bearer yk_..."
```

Restituisce un array di tutti gli elementi media riutilizzabili sull’account autenticato.

## Applica uno sfondo

Fai riferimento ai media caricati da un preset o direttamente dalle impostazioni del progetto:

```bash theme={null}
curl -X PATCH https://api.youka.io/it/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"
        }
      }
    }
  }'
```

## Elimina media

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

<Warning>
  L’eliminazione dei media non influisce sui progetti o sugli export renderizzati
  in precedenza con essi. I rendering futuri che fanno riferimento ai media eliminati torneranno allo sfondo predefinito.
</Warning>

## Cosa c’è dopo

* [Render settings reference](/en/render-settings-reference) — tutti i percorsi dei campi condivisi e i valori enum
* [Presets](/it/api/presets) — raggruppa i media con altre impostazioni di rendering
* [Project settings](/it/api/project-settings) — applica sfondi a un progetto
* [SDK media](/it/sdk/media) — lo stesso flusso in TypeScript