Visión general de la API
Automatiza el recorte y la renderización de vídeos con IA, de forma programática
La API de CutPro automatiza todo el flujo de recorte con IA: envías el enlace de un vídeo, la IA encuentra los mejores momentos y recibes los clips listos para renderizar y publicar, todo por peticiones HTTP.
URL base
Todas las rutas usan este prefijo:
https://api.cut.pro/api/v1La autenticación es una clave en la cabecera X-Api-Key, y el acceso a la API está en los planes Plus y Pro. Mira Autenticación.
El flujo típico
La API sigue el mismo camino que el estudio, en etapas que controlas petición a petición:
Analizar (sin coste). Previsualiza los metadatos y el coste en créditos de un enlace público, sin que se te cobre.
POST /clips/info
Enviar al recorte. Manda el vídeo. Los créditos se cobran en el momento.
POST /clips
Consultar el envío. Haz polling hasta que el status pase a completed o failed.
GET /clips/{videoId}/submissions/{submissionId}
Recuperar los clips generados. Toma lo que produjo la IA, con marcas de tiempo, nota y URLs.
GET /clips/{videoId}/submissions/{submissionId}/clips
Aplicar una plantilla (opcional). Aplica una de tus plantillas a los clips en lote.
POST /clips/{videoId}/submissions/{submissionId}/apply_template
Renderizar cada clip. Genera el MP4 final y haz polling hasta que termine.
POST .../clips/{clipId}/render y GET /renders/{renderId}
Descargar y publicar. Descarga el vídeo renderizado y, si quieres, publícalo.
GET /renders/{renderId}/download y POST /posts
El Quickstart recorre esos siete pasos con peticiones reales y la respuesta de cada una.
Convenciones
Aprender una ruta es aprenderlas todas. Toda la API sigue las mismas seis reglas:
- Todo en
snake_case, en cualquier cuerpo, de ida y de vuelta. - El id del propio recurso siempre es
id. La referencia a otro recurso lleva su nombre:video_id,edit_id,connection_id. - Toda fecha es ISO 8601, y toda duración o posición va en segundos.
- Todo listado responde igual:
{ "<recurso>": [...], "pagination": {...} }, conpageylimiten la query. - El estado va en minúsculas (
queued,completed), el error en mayúsculas (VIDEO_TOO_LONG). - Todo error tiene la misma forma:
{ "code": ..., "extra": {...} }, y nunca una frase lista.
La excepción es a propósito: la metadata de POST /posts guarda los nombres de campo de cada red (privacyLevel, categoryId, privacyStatus), porque van a la plataforma tal como los escribiste. Renombrarlos ahí solo escondería lo que de verdad se envía.
Errores
{
"code": "INSUFFICIENT_CREDITS",
"extra": { "credits_needed": 121, "current_balance": 40, "is_reclip": false, "scope": "workspace", "is_owner": true }
}| Status | Cuándo ocurre | Ejemplos de code |
|---|---|---|
400 | Cuerpo inválido u operación fuera de orden | VALIDATION_ERROR, TIMEFRAME_OUT_OF_BOUNDS, INVALID_METADATA |
401 | Clave ausente, revocada o inválida | UNAUTHORIZED |
402 | Créditos insuficientes para el envío | INSUFFICIENT_CREDITS |
403 | El vídeo o el recurso no está accesible | PRIVATE_VIDEO, REGION_BLOCKED, DAILY_LIMIT_EXCEEDED |
404 | El recurso no existe en ese workspace | VIDEO_NOT_FOUND, RENDER_NOT_FOUND |
409 | El recurso está en un estado que no acepta la operación | VIDEO_ALREADY_PROCESSING, DUPLICATE_POST |
410 | El resultado existió y caducó | SUBMISSION_EXPIRED, RENDER_FILE_EXPIRED |
422 | El enlace es válido pero el vídeo no sirve para recortar | LIVE_STREAM, PLAYLIST_URL, AUDIO_ONLY |
429 | Límite de peticiones alcanzado | RATE_LIMIT_EXCEEDED |
Cuando el code es VALIDATION_ERROR, el extra.errors dice qué campo falló. La página Errores y límites trae el tratamiento listo, con reintento y backoff, y los códigos de cada ruta están en la referencia, respuesta por respuesta.
Calidad y derechos
La IA elige los momentos por lo que se dice, no por lo que se ve: un vídeo con audio limpio da mejores clips. Usa solo contenido que tengas permiso para editar. CutPro no quita marcas de agua de terceros.
Próximos pasos
Autenticación
Cómo generar tu clave y enviarla en las peticiones, workspaces incluidos
Quickstart
Un ejemplo completo, del enlace al MP4 renderizado
Recetas
Los flujos enteros, listos para copiar: del enlace a la publicación, cola y re-render
Errores y límites
La forma única de error, el reintento y las cabeceras de límite