Browse the API docs
Endpoint reference

AutoClip

The Crayo AutoClip API turns a long video asset into vertical shorts cropped to the speaker and captioned. Submit a job with POST /v1/autoclip, poll it or wait for the autoclip.completed webhook, then export each clip through the projects export endpoint.

Create AutoClip job

POST/v1/autoclip

Finds the strongest moments in a long video you own and turns each one into a vertical short, cropped to the speaker and captioned. The job runs in the background and every finished clip becomes a project on your account, so you can export clips through the same export endpoint as anything else.

  • energy mode only works with edit_level clips, because captions and cropping both need speech.
  • Credits are charged for the clips you asked for when the job starts, and stay spent if the job finds fewer.
Credits:
1 video credit per requested clip, charged when the job starts
Rate limit:
Heavy tier, 2/s and 10/min

Parameters

NameInTypeRequiredDescription
asset_idbodystringYesA video asset you own to pull clips from. Between 1 minute and 3 hours long.
clip_countbodyintegerNoHow many clips to look for. 2 to 20.default 5
clip_lengthbodyintegerNoTarget clip length in seconds. Clips still end on natural sentence boundaries.default 60306090
edit_levelbodystringNoHow much editing to apply: clips cuts only, captions adds subtitles, cropped reframes to vertical, full does both.default fullclipscaptionscroppedfull
formatsbodystring[]NoLayouts to render each clip in. 1 to 5 unique values.default ["streamer"]streamersplitblack-boxtitle-subtitlesfull-video
promptbodystringNoSteer what counts as a good moment, for example focus on product demos. Max 500 characters.
modebodystringNoHow moments are found. speech reads the transcript, energy follows audio intensity for footage with little dialogue.default speechspeechenergy
languagebodystringNoSpoken language of the source. Defaults to automatic detection, which can pick the wrong language on videos with a dubbed audio track.enafarhybebnbsbgcazhhrcsdanlettlfifrkadeelguhehihuiditjaknkkkolvltmkmsmrnenofaplptparorusrskslessvtatethtrukurvi

Request

curl
curl -X POST "https://api.crayo.ai/v1/autoclip" \
  -H "Authorization: Bearer $CRAYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "asset_id": "cm7x1k2p40001abcd",
  "clip_count": 5,
  "clip_length": 60,
  "edit_level": "full"
}'

Response

200 application/json
{
  "success": true,
  "autoclip": {
    "id": "cm7x1m8880001abcd",
    "status": "queued",
    "clip_count": 5,
    "credits_charged": 5
  }
}

Errors

  • 400UNKNOWN_FIELDThe body carries a field this endpoint does not accept.
  • 400VALIDATION_ERRORThe asset is not a video, the source is too short or too long, or an option is out of range.
  • 401MISSING_API_KEYNo Authorization header was sent, or it does not carry a crayo_sk_ key.
  • 401UNAUTHORIZEDThe key sent is malformed, expired, or revoked.
  • 402INSUFFICIENT_CREDITSYour video balance is below clip_count.
  • 404NOT_FOUNDNo asset with that id belongs to your account.
  • 429JOB_LIMIT_REACHEDYou already have 3 AutoClip jobs running.
  • 429RATE_LIMITEDOver the rate limit. Wait Retry-After seconds.
  • 500SERVER_ERRORSomething failed on our side. Retry with backoff.

List AutoClip jobs

GET/v1/autoclip

Lists AutoClip jobs on the account, newest first, with the stage each one is in and how many clips are ready so far.

Credits:
Free
Rate limit:
Polling tier, 2/s and 120/min

Parameters

NameInTypeRequiredDescription
limitqueryintegerNoJobs per page. 1 to 100.default 25
offsetqueryintegerNoNumber of jobs to skip.default 0

Request

curl
curl "https://api.crayo.ai/v1/autoclip" \
  -H "Authorization: Bearer $CRAYO_API_KEY"

Response

200 application/json
{
  "success": true,
  "total": 3,
  "hasMore": false,
  "autoclips": [
    {
      "id": "cm7x1m8880001abcd",
      "status": "processing",
      "stage": "editing",
      "progress": 55,
      "clip_count": 5,
      "clips_ready": 2,
      "created_at": "2026-08-21T15:11:02.000Z"
    }
  ]
}

Errors

  • 401MISSING_API_KEYNo Authorization header was sent, or it does not carry a crayo_sk_ key.
  • 401UNAUTHORIZEDThe key sent is malformed, expired, or revoked.
  • 429RATE_LIMITEDOver the rate limit. Wait Retry-After seconds.
  • 500SERVER_ERRORSomething failed on our side. Retry with backoff.

Get AutoClip job

GET/v1/autoclip/{id}

Returns one AutoClip job and the clips it has finished. Each clip carries a project_id, which is what you pass to the export endpoint to render and download it.

  • Register autoclip.completed and autoclip.failed webhooks instead of polling this endpoint on a timer.
Credits:
Free
Rate limit:
Polling tier, 2/s and 120/min

Parameters

NameInTypeRequiredDescription
idpathstringYesThe AutoClip job id.

Request

curl
curl "https://api.crayo.ai/v1/autoclip/cm7x1m8880001abcd" \
  -H "Authorization: Bearer $CRAYO_API_KEY"

Response

200 application/json
{
  "success": true,
  "autoclip": {
    "id": "cm7x1m8880001abcd",
    "status": "completed",
    "stage": "finalizing",
    "progress": 100,
    "clip_count": 5,
    "created_at": "2026-08-21T15:11:02.000Z",
    "clips": [
      {
        "project_id": "cm7x1n0120003abcd",
        "title": "The habit that costs you an hour",
        "thumbnail_url": "https://cdn-crayo.com/user-uploads/cm7x0v8qa0000abcd/6b2.../thumb.jpg",
        "duration_ms": 58400
      }
    ]
  }
}

Errors

  • 401MISSING_API_KEYNo Authorization header was sent, or it does not carry a crayo_sk_ key.
  • 401UNAUTHORIZEDThe key sent is malformed, expired, or revoked.
  • 404NOT_FOUNDNo AutoClip job with that id belongs to your account.
  • 429RATE_LIMITEDOver the rate limit. Wait Retry-After seconds.
  • 500SERVER_ERRORSomething failed on our side. Retry with backoff.
New to the Crayo API? See what it is forUse cases, pricing and the console walkthrough live on the API feature page.

Keep exploring

API docs

Assets and Uploads

Import media from a URL or upload bytes through a signed URL, then list, rename and delete the assets every other Crayo API endpoint reads from.

API docs

Exports

Poll render status and collect the finished video file through the Crayo Exports API, or let the export.completed webhook deliver it.

API docs

Webhooks

Register https endpoints that receive signed POST deliveries when renders, AutoClip jobs, speech enhancements and tracker refreshes finish.

Feature

Developer API

Call Crayo from your own product: auto clipping, AI voiceovers, images, and rendered short-form video over one REST API.

API docs

Getting started

Create an API key on the Crayo Developers page, send it as a bearer token to api.crayo.ai, and learn the rate limits, error envelope and webhooks.

API docs

Account

Reference for GET /v1/account on the Crayo API: plan, credit balances by type, storage usage and the rate limits that apply to your key.

FAQs

Frequent questions

1 video credit per requested clip, charged when the job starts. The credits stay spent if the job finds fewer moments than you asked for.

The source must be between 1 minute and 3 hours long. clip_count accepts 2 to 20 and clip_length is 30, 60 or 90 seconds. An account can have 3 jobs running at once.

edit_level is clips, captions, cropped or full. formats takes 1 to 5 of streamer, split, black-box, title-subtitles and full-video. mode is speech or energy, and energy only works with edit_level clips.

Every finished clip is a project on your account. GET /v1/autoclip/{id} lists each clip with a project_id, which you pass to POST /v1/projects/{id}/export to render it and get a downloadable asset.

Still have questions?

Contact our 24/7 support team for any concerns or inquiries.

Get in touch