Visão geral da API
Automatize a clipagem e renderização de vídeos com IA, de forma programática
A API da CutPro automatiza todo o fluxo de clipagem com IA: você envia o link de um vídeo, a IA encontra os melhores momentos, e você recebe os clipes prontos para renderizar e publicar, tudo por requisições HTTP.
URL base
Todas as rotas usam o prefixo:
https://api.cut.pro/api/v1A autenticação é por chave no header X-Api-Key, e o acesso à API está nos planos Gratuito, Básico, Plus e Pro. Veja Autenticação.
O fluxo típico
A API segue o mesmo caminho do estúdio, em etapas que você controla por requisição:
Analisar (sem custo). Pré-visualize metadados e o custo em créditos de um link público, sem ser cobrado.
POST /clips/info
Enviar para clipagem. Submeta o vídeo. Os créditos são debitados na hora.
POST /clips
Acompanhar a submissão. Faça polling até o status virar completed ou failed.
GET /clips/{videoId}/submissions/{submissionId}
Buscar os clipes gerados. Pegue os clipes que a IA produziu, com timestamps, nota e URLs.
GET /clips/{videoId}/submissions/{submissionId}/clips
Aplicar um template (opcional). Aplique um dos seus templates em lote aos clipes.
POST /clips/{videoId}/submissions/{submissionId}/apply_template
Renderizar cada clipe. Gere o MP4 final e faça polling até concluir.
POST .../clips/{clipId}/render e GET /renders/{renderId}
Baixar e publicar. Baixe o vídeo renderizado e, se quiser, publique nas redes.
GET /renders/{renderId}/download e POST /posts
O Quickstart percorre esses sete passos com requisições reais e a resposta de cada uma.
Convenções
Aprender uma rota é aprender todas. A API inteira segue as mesmas seis regras:
- Tudo em
snake_case, em qualquer corpo, ida ou volta. - O id do próprio recurso é sempre
id. Referência a outro recurso leva o nome dele:video_id,edit_id,connection_id. - Toda data é ISO 8601, e toda duração ou posição é em segundos.
- Toda listagem responde igual:
{ "<recurso>": [...], "pagination": {...} }, compageelimitna query. - Estado é minúsculo (
queued,completed), erro é maiúsculo (VIDEO_TOO_LONG). - Todo erro tem a mesma forma:
{ "code": ..., "extra": {...} }, e nunca uma frase pronta.
A exceção é de propósito: a metadata de POST /posts guarda os nomes de campo de cada rede (privacyLevel, categoryId, privacyStatus), porque eles vão para a plataforma exatamente como você escreveu. Renomear ali só esconderia o que de fato é enviado.
Erros
{
"code": "INSUFFICIENT_CREDITS",
"extra": { "credits_needed": 121, "current_balance": 40, "is_reclip": false, "scope": "workspace", "is_owner": true }
}| Status | Quando acontece | Exemplos de code |
|---|---|---|
400 | Corpo inválido ou operação fora de ordem | VALIDATION_ERROR, TIMEFRAME_OUT_OF_BOUNDS, INVALID_METADATA |
401 | Chave ausente, revogada ou inválida | UNAUTHORIZED |
402 | Créditos insuficientes para a submissão | INSUFFICIENT_CREDITS |
403 | O vídeo ou o recurso não está acessível | PRIVATE_VIDEO, REGION_BLOCKED, DAILY_LIMIT_EXCEEDED |
404 | O recurso não existe nesse workspace | VIDEO_NOT_FOUND, RENDER_NOT_FOUND |
409 | O recurso está num estado que não aceita a operação | VIDEO_ALREADY_PROCESSING, DUPLICATE_POST |
410 | O resultado existiu e expirou | SUBMISSION_EXPIRED, RENDER_FILE_EXPIRED |
422 | O link é válido mas o vídeo não serve para clipagem | LIVE_STREAM, PLAYLIST_URL, AUDIO_ONLY |
429 | Limite de requisições atingido | RATE_LIMIT_EXCEEDED |
Quando o code é VALIDATION_ERROR, o extra.errors diz qual campo reprovou. A página Erros e limites traz o tratamento pronto, com retry e backoff, e os códigos de cada rota estão na referência, resposta por resposta.
Qualidade e direitos
A IA escolhe os momentos pelo que é dito, não pela imagem: vídeo com áudio limpo rende clipe melhor. Use apenas conteúdo que você tem permissão para editar. O CutPro não remove marca d'água de terceiros.