# Monitore canais e lives

> Acompanhe um canal do YouTube, da Twitch ou da Kick e receba clipes de cada live ou vídeo novo, sem enviar link.

Um monitor observa um canal e clipa sozinho. Há dois tipos:

| `type` | O que clipa | Onde os clipes aparecem | Cobrança |
|---|---|---|---|
| `live` | Cada transmissão, enquanto está no ar, em blocos de 10 minutos | `GET /monitors/{id}/broadcasts/{broadcastId}/clips` | Por bloco de 10 minutos que gerou clipes, só com o monitor ligado |
| `video` | Cada vídeo novo publicado no canal | Submissões comuns em `GET /clips` | Como uma clipagem normal |

Plataformas: YouTube, Twitch e Kick.

## Crie o monitor

```bash
curl -X POST https://api.cut.pro/api/v1/monitors \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "https://www.twitch.tv/gaules",
    "type": "live",
    "template_id": "7398110254410021"
  }'
```

```json title="201 Created"
{
  "id": "7413020011876610",
  "type": "live",
  "platform": "twitch",
  "username": "gaules",
  "display_name": "Gaules",
  "avatar_url": "https://...",
  "enabled": true,
  "enabled_at": "2026-10-29T19:00:00.000Z",
  "strategy_id": "7398110000000001",
  "template_id": "7398110254410021",
  "video_min_duration": null,
  "video_max_duration": null,
  "days_of_week": [],
  "hours_of_day": []
}
```

| Campo | Descrição |
|---|---|
| `channel` | URL do canal: `https://www.youtube.com/@handle`, `https://www.twitch.tv/login` ou `https://kick.com/slug`. |
| `type` | `live` ou `video`. |
| `enabled` | Começa ligado (`true`, padrão). Mande `false` para configurar agora e ligar depois. |
| `template_id` | Template aplicado a todo clipe. Com ele, cada clipe já chega com `edit_id`, pronto para renderizar ou postar. |
| `strategy_id` | Estratégia de clipagem. Sem ela, a configuração padrão. |

Só para `video`:

| Campo | Descrição |
|---|---|
| `video_min_duration`, `video_max_duration` | Ignora vídeos mais curtos ou mais longos, em segundos (1 a 3600). |
| `days_of_week` | Dias aceitos, 0 é domingo. Vazio aceita todos. |
| `hours_of_day` | Faixas `[de, até]` de hora aceitas, no fuso do dono do workspace. |

`POST /monitors` aceita 10 chamadas por minuto, porque consulta o canal na plataforma. Monitorar o mesmo canal com o mesmo `type` duas vezes responde `409 ALREADY_MONITORING`.

## Ligue e desligue

```bash
curl -X POST https://api.cut.pro/api/v1/monitors/7413020011876610/start \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

- **Ligar** (`/start`): num canal que já está ao vivo, a gravação começa em cerca de um minuto. Só o que vai ao ar a partir daí é clipado.
- **Desligar** (`/stop`): nenhum bloco novo é clipado nem cobrado, e a gravação em curso para em cerca de um minuto.
- Chamar `/start` num monitor ligado, ou `/stop` num desligado, não muda nada e responde `200`.

> O monitor precisa ficar ligado pelo menos 10 minutos antes de desligar. Antes disso, `/stop` responde `409 MINIMUM_MONITORING_TIME` com `extra.remaining_seconds`. O monitor também desliga sozinho quando o saldo acaba.

Para um canal que transmite 24 horas, crie com `enabled: false` e use `/start` e `/stop` nos horários que interessam.

## Pegue os clipes de uma live

Liste as transmissões do canal:

```bash
curl https://api.cut.pro/api/v1/monitors/7413020011876610/broadcasts \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

```json title="200 OK"
{
  "broadcasts": [
    {
      "id": "318274651093",
      "title": "Final do campeonato",
      "category": "Counter-Strike",
      "language": "pt",
      "is_mature": false,
      "tags": ["Português"],
      "started_at": "2026-10-29T19:02:11.000Z",
      "ended_at": null,
      "clips_count": 14,
      "thumbnail_url": "https://...",
      "recording_expired": false
    }
  ],
  "pagination": { "current_page": 1, "total_pages": 1, "total_count": 1, "has_next_page": false, "has_previous_page": false, "limit": 20 }
}
```

`ended_at: null` quer dizer que a live está no ar e continua gerando clipes a cada 10 minutos. Não espere ela acabar: consulte os clipes enquanto chegam.

```bash
curl "https://api.cut.pro/api/v1/monitors/7413020011876610/broadcasts/318274651093/clips?min_rating=7" \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

Cada clipe traz `rating`, `duration`, `started_at` e `ended_at` (quando o momento foi ao ar), `play_url` e:

| Campo | Significa |
|---|---|
| `edit_id` | O clipe já tem edição. Mande para `POST /renders` ou `POST /posts`. |
| `render_id` | Já existe um MP4 pronto dessa edição. Baixe em `GET /renders/{renderId}/download`. |
| `rendering` | Um render deste clipe está na fila ou rodando. |

Clipe sem `edit_id` renderiza com o layout padrão:

```bash
curl -X POST https://api.cut.pro/api/v1/monitors/7413020011876610/broadcasts/318274651093/clips/7413020199001234/render \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

Para editar em lote os clipes que já chegaram, use `POST /monitors/{id}/broadcasts/{broadcastId}/clips/apply_template`. Para todo clipe futuro, ponha `template_id` no monitor.

Quando a gravação expira, `recording_expired` vira `true` e os clipes daquela live respondem `410 RECORDING_EXPIRED`.

## Gerencie

| Rota | O que faz |
|---|---|
| `GET /monitors` | Lista os monitores, filtrando por `type`. |
| `GET /monitors/{id}` | Mostra um monitor e se está ligado. |
| `PATCH /monitors/{id}` | Muda só os campos enviados. `null` limpa `template_id` e os limites de duração. |
| `DELETE /monitors/{id}` | Para de observar. Os clipes ficam. Criar de novo o mesmo canal e `type` traz o monitor de volta, com o mesmo `id` e o histórico. |

## Erros

| Code | Quando |
|---|---|
| `INVALID_CHANNEL_URL` | A URL não é de um canal do YouTube, da Twitch ou da Kick. |
| `CREATOR_NOT_FOUND` | O canal não existe. |
| `LIVE_CLIPS_NOT_AVAILABLE` | O plano não inclui clipes de live. |
| `INVALID_OBSERVING_TYPE` | Pediu transmissões de um monitor `video`. |
| `MINIMUM_MONITORING_TIME` | Tentou desligar antes de 10 minutos. |