Clip a video

Clipping has three resources: the video (the source), the submission (one processing run of that video) and the clips (the cuts the submission generated). A video can have several submissions, for example with different sections or templates.

POST /clips/info  →  POST /clips  →  GET .../submissions/{id}  →  GET .../clips
   analysis          submission         until completed             the cuts

Analyze the linkCopy Anchor Link

curl -X POST https://api.cut.pro/api/v1/clips/info \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }'

The response carries the title, author, platform, duration in seconds, thumbnail and the cost in credits. Analyzing does not charge, but it has its own limit of 10 per minute. If you have the file, use the upload in place of this step.

When the link does not work, the code says why:

Create the submissionCopy Anchor Link

curl -X POST https://api.cut.pro/api/v1/clips \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_id": "7412908365112823",
    "source_language": "pt",
    "timeframe": { "start": 600, "end": 1800 },
    "template_id": "7398110254410021"
  }'

Common errors on creation: 402 INSUFFICIENT_CREDITS, 409 VIDEO_ALREADY_PROCESSING (the same video is already processing), 429 TOO_MANY_PENDING_CLIPS (workspace queue full), 400 TIMEFRAME_OUT_OF_BOUNDS and 400 TIMEFRAME_TOO_SHORT.

Follow the submissionCopy Anchor Link

curl https://api.cut.pro/api/v1/clips/7412908365112823/submissions/7412908371004912 \
  -H "X-Api-Key: $CUTPRO_API_KEY"

Poll every 5 to 10 seconds. The states follow this order:

A source that is not live yetCopy Anchor Link

A submission can stop at downloading because the source does not fully exist yet: a scheduled premiere, a live stream still on air or a recording the platform is still processing. In that case waiting_reason is filled in:

It is not an error and it is not stuck: the submission continues on its own when the source becomes available. Show this to the person and offer to cancel, because DELETE in this state returns the credits.

When it failsCopy Anchor Link

error_code says the reason. Those that start with DOWNLOAD_ come from the source (DOWNLOAD_PRIVATE_VIDEO, DOWNLOAD_MEMBERS_ONLY, DOWNLOAD_GEO_RESTRICTED, DOWNLOAD_REMOVED_BY_UPLOADER): switching to another video is the way out. EMPTY_TRANSCRIPT and DOWNLOAD_NO_AUDIO say there is no speech to clip. The rest are processing failures and are worth another attempt:

curl -X POST https://api.cut.pro/api/v1/clips/7412908365112823/submissions/7412908371004912/retry \
  -H "X-Api-Key: $CUTPRO_API_KEY"

The retry creates a new submission with the same settings and charges like POST /clips. The one that failed stays in the history. It only works for a submission in failed: for the others, the response is 409 SUBMISSION_NOT_FAILED.

List the clipsCopy Anchor Link

curl "https://api.cut.pro/api/v1/clips/7412908365112823/submissions/7412908371004912/clips?min_rating=7&sort=rating&order=desc" \
  -H "X-Api-Key: $CUTPRO_API_KEY"

{
  "clips": [
    {
      "id": "7412908412887301",
      "title": "The chorus everyone knows",
      "description": "The highest-energy moment of the video, with the audience singing along.",
      "rating": 9.2,
      "start_time": 42.5,
      "end_time": 71.0,
      "language": "en",
      "created_at": "2026-10-29T18:04:50.000Z",
      "thumbnail_url": "https://...",
      "download_url": "https://...",
      "play_url": "https://...",
      "has_template_applied": false,
      "edit_id": null
    }
  ],
  "pagination": { "current_page": 1, "total_pages": 1, "total_count": 6, "has_next_page": false, "has_previous_page": false, "limit": 20 }
}

• rating goes from 0 to 10. Filter with min_rating and max_rating.
• Sort by rating, duration, title or start_time.
• download_url is the raw cut, with no editing. For the MP4 with template and captions, render it.
• The links are signed and short-lived. Ask for the list again when you are going to use it.

Clip captionsCopy Anchor Link

curl "https://api.cut.pro/api/v1/clips/7412908365112823/submissions/7412908371004912/clips/7412908412887301/subtitles?format=srt" \
  -H "X-Api-Key: $CUTPRO_API_KEY"

Returns SRT or plain text (format=txt), with time starting at 00:00 and aligned to the clip. If the clip has an edit, the captions are the edit's, with corrections and translation.

RetentionCopy Anchor Link

A submission's clips do not stay forever. Once retention passes, the submission shows expired: true and the clip routes respond 410 SUBMISSION_EXPIRED. It is permanent: do not retry, upload the video again. What you already rendered is still recoverable by the edit_id.

Organize the libraryCopy Anchor Link

Deleting cannot be undone.