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

> Fundos reutilizáveis, logótipos e vídeos de introdução/finalização

Media são ficheiros reutilizáveis — fundos em vídeo, imagens estáticas, logótipos e clips de introdução/finalização — que carrega uma vez e referencia a partir de presets ou das definições do projeto. Isto evita ter de voltar a carregar o mesmo ficheiro sempre que renderiza uma nova faixa.

## Tipos de media

| Tipo          | Descrição                              |
| ------------- | -------------------------------------- |
| `video`       | Vídeo de fundo em loop.                |
| `image`       | Imagem de fundo estática.              |
| `logo`        | Sobreposição de logótipo.              |
| `intro-video` | Reproduz antes de o karaoke começar.   |
| `outro-video` | Reproduz depois de o karaoke terminar. |

## Endpoints

| Method   | Path               | Purpose                                                             |
| -------- | ------------------ | ------------------------------------------------------------------- |
| `GET`    | `/media`           | Listar media da conta autenticada.                                  |
| `POST`   | `/media`           | Registar um ficheiro previamente carregado como media reutilizável. |
| `GET`    | `/media/{mediaId}` | Obter um único item de media.                                       |
| `DELETE` | `/media/{mediaId}` | Eliminar um item de media.                                          |

Os esquemas completos de request e response estão na **referência da API**.

## Fluxo de upload

Criar um item de media é um processo em dois passos. Primeiro, carregue os bytes do ficheiro e, depois, registe o ficheiro carregado como media reutilizável.

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

    A resposta contém `inputFileId` e `uploadUrl`.
  </Step>

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

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

    A resposta inclui o novo `mediaId` e o `url` do media. Use o
    `url` dentro de presets ou das definições do projeto.
  </Step>
</Steps>

<Note>
  `POST /media` não aceita uploads de ficheiros em bruto. Espera um `inputFileId`
  de uma chamada anterior `POST /uploads` + `PUT`.
</Note>

## Listar media

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

Devolve um array com todos os itens de media reutilizáveis na conta autenticada.

## Aplicar um fundo

Referencie media carregados a partir de um preset ou diretamente a partir das definições do projeto:

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

## Eliminar media

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

<Warning>
  Eliminar media não afeta projetos ou exportações renderizados anteriormente com
  esse media. Renderizações futuras que referenciem o media eliminado irão voltar para o
  fundo predefinido.
</Warning>

## O que se segue

* [Render settings reference](/en/render-settings-reference) — todos os caminhos de campos partilhados e valores de enum
* [Presets](/pt/api/presets) — agrupar media com outras definições de renderização
* [Project settings](/pt/api/project-settings) — aplicar fundos a um projeto
* [SDK media](/pt/sdk/media) — o mesmo fluxo em TypeScript