---
title: "Split Segment Endpoint"
method: POST
path: "/segments/{segment_id}/split"
tags: ["segments"]
---

# Split Segment Endpoint

`POST /segments/{segment_id}/split`

## Request

- Base URL: `https://api.framesail.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.framesail.com/segments/{segment_id}/split`
- Auth: HTTP bearer

Split a segment into 2-4 parts at given time offsets.

## Path parameters

- `segment_id` string, required

## Request body

- SplitSegmentRequest: Split a segment into 2-4 parts at the given time offsets.
  - `dry_run` boolean: Preview the operation's consequences (assets kept / staled / recreated / deleted, jobs cancelled, rendered assets lost) without applying it.
  - `offsets_ms` integer[], required: Time offsets within the segment's duration to cut at (ms). 1 offset = 2 segments, 2 offsets = 3, 3 offsets = 4.
  - `inherit_index` integer: Which resulting segment (0-indexed) inherits the original's creative data. Others get new creative data via update_segment job.

## Response `200`

Successful Response

- SegmentOperationResponse: Response for all segment operations. A dry_run returns `preview` with an empty `segments` list; a real run returns the mutated segments.
  - `segments` object[], required
  - `warning` string, nullable
  - `preview` TransitionPreview: dry_run disclosure for a destructive segment operation — one payload shape for every op and every surface (storyboard UI, editor, MCP).
    - `kept` integer, required
    - `stale` integer, required
    - `recreated` integer, required
    - `deleted` integer, required
    - `jobs_cancelled` integer, required
    - `rendered_assets_lost` string[]: What each already-rendered asset this operation destroys is (image, clip, real photo, ...), named by generation.roles.asset_label.

## Other responses

- `422`: Validation Error

---

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