Visão geral da API

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/v1

A autenticação é por chave no header X-Api-Key, e o acesso à API exige o plano 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.

Erros

Toda resposta de erro tem o mesmo formato: um code estável, em maiúsculas, que o seu código trata num switch. O texto que a pessoa lê é escrito por você, no idioma dela.

{
  "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, a resposta traz também um errors com o campo que reprovou. Os códigos possíveis de cada rota estão listados na referência, resposta por resposta.

Qualidade e direitos

Próximos passos

Autenticação

Como gerar sua chave e enviá-la nas requisições, incluindo workspaces

Quickstart

Um exemplo completo, do link ao MP4 renderizado

Workspace e créditos

Como o consumo de créditos funciona em cada submissão

Publicação

Como publicar os clipes renderizados nas redes sociais