API overview
Automate AI video clipping and rendering programmatically
The CutPro API automates the whole AI clipping flow: you send a video link, the AI finds the best moments, and you get the clips ready to render and publish, all over HTTP requests.
Base URL
Every route uses this prefix:
https://api.cut.pro/api/v1Authentication is a key in the X-Api-Key header, and API access comes with the Gratuito, Básico, Plus, and Pro plans. See Authentication.
The typical flow
The API follows the same path as the studio, in steps you drive one request at a time:
Analyze (free). Preview the metadata and the credit cost of a public link, without being charged.
POST /clips/info
Submit for clipping. Send the video in. Credits are charged right away.
POST /clips
Poll the submission. Keep polling until status turns completed or failed.
GET /clips/{videoId}/submissions/{submissionId}
Fetch the generated clips. Take what the AI produced, with timestamps, score and URLs.
GET /clips/{videoId}/submissions/{submissionId}/clips
Apply a template (optional). Apply one of your templates to the clips in bulk.
POST /clips/{videoId}/submissions/{submissionId}/apply_template
Render each clip. Produce the final MP4 and poll until it is done.
POST .../clips/{clipId}/render and GET /renders/{renderId}
Download and publish. Download the rendered video and, if you want, publish it.
GET /renders/{renderId}/download and POST /posts
The Quickstart walks those seven steps with real requests and the response of each one.
Conventions
Learning one route is learning them all. The whole API follows the same six rules:
- Everything is
snake_case, in every body, in and out. - A resource's own id is always
id. A pointer to another resource carries its name:video_id,edit_id,connection_id. - Every date is ISO 8601, and every duration or offset is in seconds.
- Every listing answers the same way:
{ "<resource>": [...], "pagination": {...} }, withpageandlimitin the query. - States are lowercase (
queued,completed), errors are uppercase (VIDEO_TOO_LONG). - Every error has the same shape:
{ "code": ..., "extra": {...} }, and never a ready-made sentence.
The exception is deliberate: the metadata of POST /posts keeps each network's own field names (privacyLevel, categoryId, privacyStatus), because they go to the platform exactly as you wrote them. Renaming them there would only hide what is actually sent.
Errors
{
"code": "INSUFFICIENT_CREDITS",
"extra": { "credits_needed": 121, "current_balance": 40, "is_reclip": false, "scope": "workspace", "is_owner": true }
}| Status | When it happens | Example codes |
|---|---|---|
400 | Invalid body or an operation out of order | VALIDATION_ERROR, TIMEFRAME_OUT_OF_BOUNDS, INVALID_METADATA |
401 | Key missing, revoked or invalid | UNAUTHORIZED |
402 | Not enough credits for the submission | INSUFFICIENT_CREDITS |
403 | The video or the resource is not reachable | PRIVATE_VIDEO, REGION_BLOCKED, DAILY_LIMIT_EXCEEDED |
404 | The resource does not exist in this workspace | VIDEO_NOT_FOUND, RENDER_NOT_FOUND |
409 | The resource is in a state that rejects the operation | VIDEO_ALREADY_PROCESSING, DUPLICATE_POST |
410 | The result existed and has expired | SUBMISSION_EXPIRED, RENDER_FILE_EXPIRED |
422 | The link is valid but the video cannot be clipped | LIVE_STREAM, PLAYLIST_URL, AUDIO_ONLY |
429 | Rate limit reached | RATE_LIMIT_EXCEEDED |
When the code is VALIDATION_ERROR, extra.errors names the field that failed. The Errors and limits page has the handling written out, with retry and backoff, and the codes of each route are in the reference, response by response.
Quality and rights
The AI picks moments by what is said, not by what is shown: a video with clean audio makes better clips. Only use content you have permission to edit. CutPro does not remove third-party watermarks.