---
title: "Start a video edit: a private upload link for the video, or footage from source_url"
method: POST
path: "/videos"
---

# Start a video edit: a private upload link for the video, or footage from source_url

`POST /videos`

## Request

- Base URL: `https://clypmint.com/api/v1`
- URL: `https://clypmint.com/api/v1/videos`
- Auth: HTTP bearer

The full brief of the MCP tool edit_video: purpose, hooks, shorts (or "all"), formats, sound_effects, speaker_name, instructions (8,000 characters), asset_ids, music_staging_key, style_id/style_version, source_url, or clips to cut a long recording into clips. format: vertical/horizontal still works. Cost: 3 credits plus 1 a minute of footage, plus 3 per extra output; dry_run: true answers it first.

## Request body

- object
  - `operation_id` string: A stable ID for this request. Preserve it on retries. Use a new ID only for a deliberate new request.
  - `purpose` 'organic' | 'ad' | 'youtube' | 'sales_page': organic (a post), ad (three openings by default), youtube (horizontal), sales_page.
  - `hooks` integer: Openings to make (1-3): an ad gets 3 by default, the main cut counting as one.
  - `shorts` union: Shorts to cut from the recording too (0-10), or 'all' the good ones.
    - integer
    - 'all'
  - `style_id` string: A style id from browse_styles, e.g. serif-editorial-launch, bold-navy-statement, crimson-serif-explainer, warm, luxe, brand, or a saved style of your own (my-...).
  - `style_version` integer
  - `kind` 'talking' | 'montage': talking: someone speaks and their words lead the cut (talking head, interview, podcast, tutorial). montage: the pictures and the music lead (sport, action, travel, events, scenery, b-roll); what people say is not followed. Leave out when unsure: Clypmint decides from the footage.
  - `length` object: How long the finished video should be. "45-60 s" is {min_seconds: 45, max_seconds: 60}; "under a minute" is {max_seconds: 60}; "about 30 s" is {min_seconds: 25, max_seconds: 35}. Leave out when the user named no length.
    - `min_seconds` integer
    - `max_seconds` integer, required
  - `camera_sound` 'keep' | 'mute': The footage's own sound. mute: only the song plays (the default for a montage with a song). keep: the camera sound stays (the default otherwise).
  - `instructions` string: Anything else the user asked for, in their own words, usually one or two sentences. Length, kind, song, style and formats go in their own fields, not here. Clypmint watches the footage itself: do not describe the footage, write rules or explain how to edit. Kept in full.
  - `format` 'vertical' | 'horizontal': The older one-shape switch; formats says more.
  - `title` string
  - `formats` string[]: Only when the user asked for a shape: vertical, TikTok, Reels or Shorts is 9:16; square is 1:1; 4:5; YouTube or widescreen is 16:9. Every shape to make, the main one first. Leave it out otherwise: the video keeps its own shape and nothing is cropped.
  - `sound_effects` boolean: true: sound effects on the edit.
  - `voice` 'matilda' | 'sarah' | 'jessica' | 'alice' | 'liam' | 'chris' | 'brian' | 'george' | 'roger' | 'laura' | 'charlie' | 'river' | 'will' | 'eric' | 'bella' | 'daniel' | 'lily' | 'bill' | 'adam' | 'callum' | 'harry': The narrator for a video made from words: matilda, sarah, jessica, alice, liam, chris, brian, george, roger, laura, charlie, river, will, eric, bella, daniel, lily, bill, adam, callum, harry (sarah: calm, reassuring, health and money; alice: a clear British educator; brian: deep documentary; liam: energetic ads). Leave out to let Clypmint pick one that fits the words. "Voice: <name>" in instructions does the same.
  - `speaker_name` string: Who is talking, spelled right, e.g. "Dr. Ana Ruiz".
  - `speaker_company` string: The speaker's company or business, spelled exactly for this video.
  - `names` string[]: Exact person, company and product names to spell correctly in this video; not a lasting account rule.
  - `spellings` object: Explicit heard-to-correct spelling pairs for this video, for example {"KMAC":"KMAK"}.
  - `asset_ids` string[]
  - `asset_staging_keys` string[]
  - `music_staging_key` string: The song for this video, from import_asset (mp3, wav or m4a): a montage's soundtrack, or music under the speech.
  - `song_upload` boolean: true when the user has a song file but no public link to it (a song attached in Claude, a file on their computer): the private upload link asks for the video and the song together. Leave out when music_staging_key is set.
  - `source_url` string, uri: A public https link to the footage (where links are open), instead of a file.
  - `footage_from` string: The video_id of a video already made from this footage: a new edit of the same footage with no new upload (another kind, length or style). To change that video itself, use revise_video or apply_edits instead.
  - `source_duration_seconds` number
  - `clips` object: Clips alone from one recording (no main film): podcasts, streams, long talks.
    - `count` union, required: How many clips (1-30), or 'all' the good ones.
      - integer
      - 'all'
    - `min_seconds` integer
    - `max_seconds` integer
    - `shape` 'source' | '9:16': source keeps the recording's shape; 9:16 cuts each clip vertical on the speaker.
    - `from_seconds` number
    - `to_seconds` number
    - `about` string: Topics to look for first, in plain words.
  - `dry_run` boolean: true: answer the credit cost and start nothing.

## Response `200`

Upload link ready; editing starts when the video arrives

- VideoStatus
  - `import_id` string, nullable
  - `video_id` string, nullable
  - `title` string
  - `state` 'waiting' | 'uploading' | 'editing' | 'ready' | 'failed', required: waiting: the private upload link is open. uploading: the video is arriving. editing: Clypmint is editing it.
  - `progress` number
  - `duration` number, nullable
  - `ready` boolean, required
  - `problem` string, nullable
  - `next_step` string: For a failed video: what to do now.
  - `message` string
  - `upload_url` string, uri, nullable: Open in a browser, or upload to it, to send the video. Works once, for 15 minutes.
  - `expires_at` string, date-time, nullable
  - `studio_url` string, uri
  - `share_url` string, nullable: A public page for the video; null until Clypmint has public pages.
  - `cost` Cost
    - `credits` number, nullable: Null until the footage length is known.
    - `how` string
  - `media` Media: Signed links that expire. Fetch them again with GET /videos/{id}.
    - `playback_url` string, nullable
    - `download_url` string, nullable

## Other responses

- `400`: The request is invalid. The message names each field to fix.
- `401`: A valid bearer token (API key or OAuth access token) is required.
- `402`: This account has no allowance left for this, or does not include it. error.checkout_url is where to add it.
- `403`: This needs publishing permission (scope clypmint.publish), or is not open on this account yet.
- `404`: The video, upload, memory or calendar was not found in this account.
- `409`: Busy: an upload or edit is already running, the video changed, or too many upload links are waiting.
- `413`: The request body is too large.
- `422`: Clypmint could not apply it as asked; error.problems names each part.
- `429`: A daily limit was reached (direct edits, caption fixes, upload links).
- `501`: This is not available on Clypmint yet; the message says what to use instead.
- `503`: Clypmint is busy. Try again in a moment.

---

[API](https://skmtc.dev/clypmint/apis/clypmint-api.md) · [All operations](https://skmtc.dev/clypmint/apis/clypmint-api/llms.txt) · [OpenAPI document](https://skmtc.dev/clypmint/apis/clypmint-api/revisions/dde4982718df?raw)