Clipe um vídeo

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.

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

Analise o linkCopy Anchor Link

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 no lugar deste passo.

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

Crie a submissãoCopy Anchor Link

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"
  }'

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ãoCopy Anchor Link

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:

Fonte que ainda não está no arCopy Anchor Link

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:

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 falhaCopy Anchor Link

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:

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 clipesCopy Anchor Link

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"

{
  "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.
• Os links são assinados e duram pouco. Peça a lista de novo quando for usar.

Legendas do clipeCopy Anchor Link

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çãoCopy Anchor Link

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 bibliotecaCopy Anchor Link

Apagar não tem volta.