Convenções
URL base, formato dos campos, paginação, jobs assíncronos e links que expiram: as regras que valem em toda rota.
As mesmas regras valem em todas as rotas. Leia uma vez e a referência passa a ser previsível.
URL base
https://api.cut.pro/api/v1Só HTTPS. A versão faz parte do caminho.
Requisição
Mande o corpo em JSON com Content-Type: application/json. As rotas também aceitam application/x-www-form-urlencoded e multipart/form-data com os mesmos campos, o que ajuda em ferramentas no-code.
Campos
| Regra | Exemplo |
|---|---|
Todo campo é snake_case | credits_cost, output_resolution |
O id do próprio recurso é sempre id | { "id": "7412908371004912" } |
| Referência a outro recurso leva o nome dele | video_id, edit_id, connection_id |
| IDs são strings | guarde como string, nunca converta para número |
| Data e hora em ISO 8601, UTC | "2026-10-29T18:04:51.000Z" |
| Duração e posição no vídeo em segundos | "start_time": 42.5 |
Campo sem valor vem null, não some | "completed_at": null |
A única exceção é metadata em POST /posts: as chaves ali são as de cada rede (privacyLevel, categoryId, privacyStatus) e vão para a plataforma do jeito que você escreveu.
Estado e erro
status descreve onde um job está e vem em minúsculas: queued, processing, completed, failed.
code descreve o que deu errado e vem em maiúsculas: INSUFFICIENT_CREDITS, SUBMISSION_EXPIRED. Todo erro tem o mesmo corpo, sem mensagem em texto:
{ "code": "INSUFFICIENT_CREDITS", "extra": { "credits_needed": 121, "current_balance": 40 } }Faça switch no code e traduza para a sua interface. Veja Erros.
Listas e paginação
Toda lista responde com o nome do recurso e um bloco pagination:
{
"clips": [{ "id": "7412908412887301" }],
"pagination": {
"current_page": 1,
"total_pages": 3,
"total_count": 52,
"has_next_page": true,
"has_previous_page": false,
"limit": 20
}
}Pagine com page (começa em 1) e limit (máximo 100). O padrão de limit muda por rota e está na referência de cada uma.
curl "https://api.cut.pro/api/v1/renders?page=2&limit=100" \
-H "X-Api-Key: $CUTPRO_API_KEY"Avance enquanto has_next_page for true.
Jobs assíncronos
Clipagem, render, post, transcrição, geração e persona não terminam na resposta. A criação devolve um id e você consulta até o fim:
- Crie o job e guarde o
id. - Consulte a rota de leitura do job a cada 5 a 10 segundos.
- Pare quando o
statuschegar a um estado final.
| Job | Rota de leitura | Estados finais |
|---|---|---|
| Clipagem | GET /clips/{videoId}/submissions/{submissionId} | completed, failed |
| Render | GET /renders/{renderId} | completed, failed, cancelled, expired |
| Post | GET /posts/{id} | completed, partial, failed, cancelled |
| Transcrição | GET /transcriptions/{transcriptionId} | ready, no_speech, failed |
| Geração | GET /generations/{id} | ready, failed |
Esse ritmo cabe com folga no limite de requisições. A API não envia webhooks: o fim de um job sempre se descobre consultando.
Links que expiram
| O quê | Validade |
|---|---|
download_url, play_url e thumbnail_url de um clipe | curta: peça de novo quando for usar |
Link de GET /renders/{renderId}/download | 1 hora |
| Arquivo MP4 de um render | definido pelo plano, em render_expiry_hours de GET /renders/limits |
Edição (edit_id) | não expira |
Não guarde link assinado no seu banco. Guarde o id e peça o link na hora. Se o MP4 já foi apagado, POST /renders com o edit_id gera um novo.
Especificação OpenAPI
A especificação completa fica em https://api.cut.pro/api/v1/openapi.json. Use para gerar um cliente tipado, importar no Postman ou Insomnia, ou dar contexto a um agente de código.