# Clipe um vídeo

> Analise o link, crie a submissão, acompanhe os estados e trabalhe com os clipes que a IA gerou.

A clipagem tem três recursos: o **vídeo** (a fonte), a **submissão** (um processamento daquele vídeo) e os **clipes** (os cortes que a submissão gerou). Um vídeo pode ter várias submissões, por exemplo com trechos ou templates diferentes.

```text
POST /clips/info  →  POST /clips  →  GET .../submissions/{id}  →  GET .../clips
   análise           submissão          até completed               os cortes
```

## Analise o link

```bash
curl -X POST https://api.cut.pro/api/v1/clips/info \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }'
```

A resposta traz título, autor, plataforma, duração em segundos, miniatura e o custo em créditos. Analisar não cobra, mas tem limite próprio de 10 por minuto. Se o arquivo está com você, use o [upload](/uploads) no lugar deste passo.

Quando o link não serve, o `code` diz por quê:

| Status | Codes | Significa |
|---|---|---|
| `400` | `VIDEO_TOO_LONG` | Passa da duração máxima do plano. `extra.duration` e `extra.max_duration` dizem quanto. |
| `403` | `PRIVATE_VIDEO`, `AGE_RESTRICTED`, `ACCESS_DENIED`, `REGION_BLOCKED`, `COPYRIGHT_BLOCKED`, `PLATFORM_NOT_SUPPORTED` | A plataforma não entrega este vídeo. |
| `404` | `VIDEO_ID_NOT_FOUND`, `UNAVAILABLE`, `METADATA_UNAVAILABLE` | O vídeo não existe ou saiu do ar. |
| `422` | `PLAYLIST_URL`, `CHANNEL_URL`, `SHORTS_NOT_SUPPORTED`, `LIVE_STREAM`, `PREMIUM_ONLY`, `AUDIO_ONLY`, `INVALID_URL`, `INVALID_DURATION`, `INVALID_DIMENSIONS` | O link é válido, mas não é um vídeo que dá para clipar. |

## Crie a submissão

```bash
curl -X POST https://api.cut.pro/api/v1/clips \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_id": "7412908365112823",
    "source_language": "pt",
    "timeframe": { "start": 600, "end": 1800 },
    "template_id": "7398110254410021"
  }'
```

| Campo | Obrigatório | Descrição |
|---|---|---|
| `video_id` | sim | O `id` de `POST /clips/info` ou do upload. |
| `source_language` | não | `auto` (padrão), `pt` ou `en`. Fixe quando souber: acerta mais. |
| `timeframe` | não | `{ start, end }` em segundos. Clipa só esse trecho. |
| `template_id` | não | Um template de `GET /templates`. Todo clipe sai editado com ele, pronto para renderizar. |
| `translate_to` | não | Código ISO 639-1 (`en`, `es`). Traduz as legendas dos clipes e custa mais. |
| `strategy_id` | não | Uma estratégia de clipagem salva na Cut.Pro. Sem ela, a IA usa a configuração padrão. |

> Os créditos saem na criação. `credits_charged` na resposta diz quanto saiu.

Erros comuns na criação: `402 INSUFFICIENT_CREDITS`, `409 VIDEO_ALREADY_PROCESSING` (o mesmo vídeo já está processando), `429 TOO_MANY_PENDING_CLIPS` (fila do workspace cheia), `400 TIMEFRAME_OUT_OF_BOUNDS` e `400 TIMEFRAME_TOO_SHORT`.

## Acompanhe a submissão

```bash
curl https://api.cut.pro/api/v1/clips/7412908365112823/submissions/7412908371004912 \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

Consulte a cada 5 a 10 segundos. Os estados seguem esta ordem:

| `status` | O que está acontecendo |
|---|---|
| `queued` | Na fila. `queue_position` e `estimated_time` (em segundos) dizem quanto falta. |
| `downloading` | Baixando a fonte. |
| `transcribing` | Transcrevendo o áudio. |
| `video_analysis` | Analisando a imagem. |
| `analyzing` | A IA escolhendo os momentos. |
| `finalizing` | Gerando os clipes. |
| `completed` | Pronto. `clips_count` diz quantos clipes saíram. |
| `failed` | Falhou. O motivo está em `error_code`. |

### Fonte que ainda não está no ar

Uma submissão pode parar em `downloading` porque a fonte ainda não existe por inteiro: uma estreia agendada, uma live ainda no ar ou uma gravação que a plataforma ainda processa. Nesse caso `waiting_reason` vem preenchido:

| `waiting_reason` | Significa |
|---|---|
| `SOURCE_PREMIERE_SCHEDULED` | Estreia agendada. `waiting_until` traz o horário anunciado, quando a plataforma informa. |
| `SOURCE_LIVE_IN_PROGRESS` | A live ainda está no ar. |
| `SOURCE_VOD_PROCESSING` | A transmissão acabou e a plataforma ainda prepara a gravação. |

Não é erro e não travou: a submissão continua sozinha quando a fonte fica disponível. Mostre isso para a pessoa e ofereça cancelar, porque o `DELETE` nesse estado devolve os créditos.

### Quando falha

`error_code` diz o motivo. Os que começam com `DOWNLOAD_` são da fonte (`DOWNLOAD_PRIVATE_VIDEO`, `DOWNLOAD_MEMBERS_ONLY`, `DOWNLOAD_GEO_RESTRICTED`, `DOWNLOAD_REMOVED_BY_UPLOADER`): trocar de vídeo é o caminho. `EMPTY_TRANSCRIPT` e `DOWNLOAD_NO_AUDIO` dizem que não há fala para clipar. Os demais são falha do processamento e valem uma nova tentativa:

```bash
curl -X POST https://api.cut.pro/api/v1/clips/7412908365112823/submissions/7412908371004912/retry \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

O retry cria uma **nova** submissão com as mesmas configurações e cobra como `POST /clips`. A que falhou continua no histórico. Só vale para submissão em `failed`: nas outras, a resposta é `409 SUBMISSION_NOT_FAILED`.

## Liste os clipes

```bash
curl "https://api.cut.pro/api/v1/clips/7412908365112823/submissions/7412908371004912/clips?min_rating=7&sort=rating&order=desc" \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

```json title="200 OK"
{
  "clips": [
    {
      "id": "7412908412887301",
      "title": "O refrão que todo mundo sabe",
      "description": "O momento de maior energia do vídeo, com o público cantando junto.",
      "rating": 9.2,
      "start_time": 42.5,
      "end_time": 71.0,
      "language": "en",
      "created_at": "2026-10-29T18:04:50.000Z",
      "thumbnail_url": "https://...",
      "download_url": "https://...",
      "play_url": "https://...",
      "has_template_applied": false,
      "edit_id": null
    }
  ],
  "pagination": { "current_page": 1, "total_pages": 1, "total_count": 6, "has_next_page": false, "has_previous_page": false, "limit": 20 }
}
```

- `rating` vai de 0 a 10. Filtre com `min_rating` e `max_rating`.
- Ordene por `rating`, `duration`, `title` ou `start_time`.
- `download_url` é o corte cru, sem edição. Para o MP4 com template e legenda, [renderize](/rendering).
- Os links são assinados e duram pouco. Peça a lista de novo quando for usar.

### Legendas do clipe

```bash
curl "https://api.cut.pro/api/v1/clips/7412908365112823/submissions/7412908371004912/clips/7412908412887301/subtitles?format=srt" \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

Devolve SRT ou texto puro (`format=txt`), com o tempo começando em `00:00` e alinhado ao clipe. Se o clipe tem edição, as legendas são as da edição, com correções e tradução.

## Retenção

Os clipes de uma submissão não ficam para sempre. Passada a retenção, a submissão aparece com `expired: true` e as rotas de clipes respondem `410 SUBMISSION_EXPIRED`. É permanente: não repita, envie o vídeo de novo. O que você já renderizou continua recuperável pelo `edit_id`.

## Organize a biblioteca

| Rota | O que faz |
|---|---|
| `GET /clips` | Lista os vídeos, com contadores de clipes, edições, exports e posts e o estado da última submissão. |
| `GET /clips/{videoId}/submissions` | Lista as submissões de um vídeo, com `credit_cost`, `timeframe` e `expired`. |
| `DELETE /clips/{videoId}/submissions/{submissionId}` | Apaga a submissão e os clipes. Se ainda processa, cancela e devolve os créditos. |
| `DELETE /clips/{videoId}/submissions/{submissionId}/clips/{clipId}` | Apaga um clipe. |
| `DELETE /clips/{videoId}` | Apaga o vídeo com todas as submissões. As que processam são canceladas e reembolsadas. |

Apagar não tem volta.