episode_create
Create an episode or derived reel
Assembles a new EPISODE or derived reel from ordered recording/episode/template ranges into ONE combined video. A reel cut from an Episode takes derived_from_id for lineage and one segment row per chosen moment in the canonical shape {episode_id, range:[start_seconds,end_seconds]}; segments[].range is a half-open [start,end) interval in EPISODE time. derived_from_id does not select a range. Creation selects Program ranges; simultaneous participant boxes are composed afterwards with camera_program_set, not with extra segment fields. Use this when the user asks to make, cut together, or export a multi-segment highlight, reel, montage, or supercut. Suggestions alone create nothing (saved Moments are review_points_place), and a single-range Clip is clip_create. Branding: identity:"project_default" applies the project's saved Signature defaults (the user's branding); identity_assets_list lists the saved assets an explicit choice names. Episode-range slices keep what their parent plays there (a pinned or replaced microphone, silence) and program_audio names it; audio that cannot be carried, such as a pinned microphone in a montage without derived_from_id, refuses with program_audio_not_preservable and its exact span. Persists the edit only — does not render or charge. The rendered video is a separate render_create with the exact returned target_type, target_id, and revision; render_status reports it. Publishing is separate. Always returns edge_warnings. A warning means a cut edge overlaps an approximate transcript word span, not that acoustic evidence proved a mid-word cut. Each warning's episode_seconds is the created target's point for a narrow episode_zoom region and edge, and occurrence_id and source_id identify the exact side; when those coordinates are absent, episode_read of the target maps the edge. A point whose speech evidence is supported inter_word_silence or supported aligned_word_edge stands; any other point is revised on the same target with episode_edit at an exact supported point. Acoustic envelope/onset suggestions alone are not boundary authority. A second episode_create or a superseding Clip does not resolve edge_warnings. Accepts idempotency_key. A creation with derived_from_id produces a Clip (a derived Episode IS a Clip), addressed as target_type:"clip" in render_create, render_status, and workspace_open. A canvas taller than the source picture (a portrait canvas over landscape footage) keeps only a vertical slice of each frame; episode_framing_guidance reports, per visible person, whether their measured extent fits that crop window (fits | too_wide | uncertain | unknown), and episode_edit occurrence.reframe carries the framing decision.
Surface: Default model and app
Product release eb8538f4a297f331d0399351c1e175bffcd212d2
Public contract commit 20688e11af473a363145ed880d5019c90a7ec1e2
Public contract SHA-256 87a94b85a84dc19245fc03f9b544c70d64bd9f5e08585dcccb38157cace5700d
Captured 2026-10-04T11:55:45.577Z. Review or improve this contract on GitHub.
These blocks show the complete MCP descriptors captured from serving Rails. Security schemes and resource URIs can differ by connected host.
Default model descriptor
{
"name": "episode_create",
"title": "Create an episode or derived reel",
"description": "Assembles a new EPISODE or derived reel from ordered recording/episode/template ranges into ONE combined video. A reel cut from an Episode takes derived_from_id for lineage and one segment row per chosen moment in the canonical shape {episode_id, range:[start_seconds,end_seconds]}; segments[].range is a half-open [start,end) interval in EPISODE time. derived_from_id does not select a range. Creation selects Program ranges; simultaneous participant boxes are composed afterwards with camera_program_set, not with extra segment fields. Use this when the user asks to make, cut together, or export a multi-segment highlight, reel, montage, or supercut. Suggestions alone create nothing (saved Moments are review_points_place), and a single-range Clip is clip_create. Branding: identity:\"project_default\" applies the project's saved Signature defaults (the user's branding); identity_assets_list lists the saved assets an explicit choice names. Episode-range slices keep what their parent plays there (a pinned or replaced microphone, silence) and program_audio names it; audio that cannot be carried, such as a pinned microphone in a montage without derived_from_id, refuses with program_audio_not_preservable and its exact span. Persists the edit only — does not render or charge. The rendered video is a separate render_create with the exact returned target_type, target_id, and revision; render_status reports it. Publishing is separate. Always returns edge_warnings. A warning means a cut edge overlaps an approximate transcript word span, not that acoustic evidence proved a mid-word cut. Each warning's episode_seconds is the created target's point for a narrow episode_zoom region and edge, and occurrence_id and source_id identify the exact side; when those coordinates are absent, episode_read of the target maps the edge. A point whose speech evidence is supported inter_word_silence or supported aligned_word_edge stands; any other point is revised on the same target with episode_edit at an exact supported point. Acoustic envelope/onset suggestions alone are not boundary authority. A second episode_create or a superseding Clip does not resolve edge_warnings. Accepts idempotency_key. A creation with derived_from_id produces a Clip (a derived Episode IS a Clip), addressed as target_type:\"clip\" in render_create, render_status, and workspace_open. A canvas taller than the source picture (a portrait canvas over landscape footage) keeps only a vertical slice of each frame; episode_framing_guidance reports, per visible person, whether their measured extent fits that crop window (fits | too_wide | uncertain | unknown), and episode_edit occurrence.reframe carries the framing decision.",
"inputSchema": {
"type": "object",
"properties": {
"segments": {
"type": "array",
"description": "Ordered episode/recording/template segments. The only model-visible boundary field is range: {episode_id, range:[start,end]} in EPISODE time or {recording_id, range:[start,end]} in SOURCE time, both half-open [start,end) intervals; episode_range and start_seconds/end_seconds are not accepted. Template rows use {template, params} and have no range.",
"minItems": 1,
"items": {
"type": "object",
"oneOf": [
{
"required": [
"episode_id",
"range"
]
},
{
"required": [
"recording_id",
"range"
]
},
{
"required": [
"template"
],
"not": {
"required": [
"range"
]
}
}
],
"properties": {
"episode_id": {
"type": "string",
"description": "Source Episode public ID. This row must also provide range in half-open EPISODE time."
},
"recording_id": {
"type": "string",
"description": "Source Recording public ID. This row must also provide range in half-open SOURCE time."
},
"template": {
"type": "string",
"description": "Curated block template key, such as show_open/studio_dissolve or outro/sting_chime."
},
"params": {
"type": "object",
"description": "Template parameters.",
"properties": {
"title": {
"type": "string"
},
"subtitle": {
"type": "string"
},
"accent": {
"type": "string",
"description": "Hex color, for example #f28f84."
},
"sting": {
"type": "string",
"enum": [
"none",
"chime",
"bass",
"glitch",
"shutter"
]
}
}
},
"range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "Required for episode_id and recording_id rows. The field is named range and contains the half-open interval [start_seconds, end_seconds): EPISODE time for episode_id, SOURCE time for recording_id."
},
"crop_strategy": {
"type": "string",
"enum": [
"center_crop",
"fit_pad"
]
},
"audio_policy": {
"type": "string",
"enum": [
"source",
"mute"
]
},
"caption_mode": {
"type": "string",
"enum": [
"inherit",
"off",
"on"
]
},
"boundary_rationale": {
"type": "object",
"description": "Optional audit notes for selected boundaries.",
"properties": {
"start": {
"type": "string"
},
"end": {
"type": "string"
}
}
},
"zoom_regions": {
"type": "array",
"description": "Optional audit list of consulted source/episode windows.",
"items": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
}
}
},
"required": [],
"additionalProperties": false
}
},
"title": {
"type": "string",
"description": "Title for the new episode."
},
"description": {
"type": "string",
"description": "Optional episode description."
},
"derived_from_id": {
"type": "string",
"description": "Optional parent Episode public ID used only for lineage/filing. It does not select media or replace segments[].range. It files a multi-segment reel cut from one existing Episode under that parent instead of listing it as a primary project Episode."
},
"aspect_ratio": {
"type": "string",
"enum": [
"9:16",
"16:9",
"1:1"
],
"description": "Output shape, set only for a shape the user asked for or a named vertical destination (Reels/Shorts/TikTok). When omitted it follows the footage: the source recording's native aspect, nearest of 9:16/16:9/1:1, and 16:9 when unprobed. \"Reel\" describes the edit, not the shape: 9:16 on landscape footage crops the sides away and can cut a second person out of frame."
},
"transition": {
"type": "string",
"enum": [
"cut",
"dip_to_black",
"overlap_dissolve"
],
"description": "Optional seam transition for segment boundaries. Defaults to cut."
},
"identity": {
"oneOf": [
{
"type": "string",
"enum": [
"project_default",
"none"
]
},
{
"type": "object",
"properties": {
"opener": {
"type": "string",
"description": "Explicit opener library_entry_id returned by identity_assets_list, or none; a specific saved asset instead of project_default."
},
"outro": {
"type": "string",
"description": "Explicit outro library_entry_id returned by identity_assets_list, or none; a specific saved asset instead of project_default."
}
},
"additionalProperties": false
}
],
"description": "Optional highlight-reel Signature. project_default applies the project's saved Signature defaults (the user's branding); saved project music becomes a full-Episode music cue. identity_assets_list lists saved openers and outros with their uses_title. The object form chooses explicit saved opener and outro assets. A specific song is added or changed with music_cue_mutate after creation. Omitted object keys mean none."
},
"opener_title": {
"type": "string",
"description": "Optional per-reel opener title, used only when the selected opener asset has uses_title:true; static or absent openers return identity_warnings:[\"opener_title_ignored_static_opener\"] and ignore this value."
},
"supersedes_episode_id": {
"type": "string",
"description": "Optional explicit lineage for a replacement draft the user deliberately asks for. It does not resolve edge_warnings, which are revised on the same created target with episode_edit."
},
"idempotency_key": {
"type": "string",
"description": "Opaque key unique across the account for this logical creation. Under a v3 editor ask it is the full requestId plus a distinct action suffix; otherwise it is a fresh opaque key chosen once. Exact retry/recovery reuses the original complete key and arguments, including across later messages. A key derived from titles or media ranges changes with them, and a new key on an ambiguous write can create a duplicate. A near-duplicate this same session already created comes back with near_duplicate:true instead of a second row."
}
},
"required": [
"segments",
"idempotency_key"
],
"additionalProperties": false
},
"annotations": {
"title": "Create an episode or derived reel",
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
],
"ui": {
"visibility": [
"model",
"app"
]
},
"openai/widgetAccessible": true
}
}App descriptor
{
"name": "episode_create",
"title": "Create an episode or derived reel",
"description": "Assembles a new EPISODE or derived reel from ordered recording/episode/template ranges into ONE combined video. A reel cut from an Episode takes derived_from_id for lineage and one segment row per chosen moment in the canonical shape {episode_id, range:[start_seconds,end_seconds]}; segments[].range is a half-open [start,end) interval in EPISODE time. derived_from_id does not select a range. Creation selects Program ranges; simultaneous participant boxes are composed afterwards with camera_program_set, not with extra segment fields. Use this when the user asks to make, cut together, or export a multi-segment highlight, reel, montage, or supercut. Suggestions alone create nothing (saved Moments are review_points_place), and a single-range Clip is clip_create. Branding: identity:\"project_default\" applies the project's saved Signature defaults (the user's branding); identity_assets_list lists the saved assets an explicit choice names. Episode-range slices keep what their parent plays there (a pinned or replaced microphone, silence) and program_audio names it; audio that cannot be carried, such as a pinned microphone in a montage without derived_from_id, refuses with program_audio_not_preservable and its exact span. Persists the edit only — does not render or charge. The rendered video is a separate render_create with the exact returned target_type, target_id, and revision; render_status reports it. Publishing is separate. Always returns edge_warnings. A warning means a cut edge overlaps an approximate transcript word span, not that acoustic evidence proved a mid-word cut. Each warning's episode_seconds is the created target's point for a narrow episode_zoom region and edge, and occurrence_id and source_id identify the exact side; when those coordinates are absent, episode_read of the target maps the edge. A point whose speech evidence is supported inter_word_silence or supported aligned_word_edge stands; any other point is revised on the same target with episode_edit at an exact supported point. Acoustic envelope/onset suggestions alone are not boundary authority. A second episode_create or a superseding Clip does not resolve edge_warnings. Accepts idempotency_key. A creation with derived_from_id produces a Clip (a derived Episode IS a Clip), addressed as target_type:\"clip\" in render_create, render_status, and workspace_open. A canvas taller than the source picture (a portrait canvas over landscape footage) keeps only a vertical slice of each frame; episode_framing_guidance reports, per visible person, whether their measured extent fits that crop window (fits | too_wide | uncertain | unknown), and episode_edit occurrence.reframe carries the framing decision.",
"inputSchema": {
"type": "object",
"properties": {
"segments": {
"type": "array",
"description": "Ordered episode/recording/template segments. The only model-visible boundary field is range: {episode_id, range:[start,end]} in EPISODE time or {recording_id, range:[start,end]} in SOURCE time, both half-open [start,end) intervals; episode_range and start_seconds/end_seconds are not accepted. Template rows use {template, params} and have no range.",
"minItems": 1,
"items": {
"type": "object",
"oneOf": [
{
"required": [
"episode_id",
"range"
]
},
{
"required": [
"recording_id",
"range"
]
},
{
"required": [
"template"
],
"not": {
"required": [
"range"
]
}
}
],
"properties": {
"episode_id": {
"type": "string",
"description": "Source Episode public ID. This row must also provide range in half-open EPISODE time."
},
"recording_id": {
"type": "string",
"description": "Source Recording public ID. This row must also provide range in half-open SOURCE time."
},
"template": {
"type": "string",
"description": "Curated block template key, such as show_open/studio_dissolve or outro/sting_chime."
},
"params": {
"type": "object",
"description": "Template parameters.",
"properties": {
"title": {
"type": "string"
},
"subtitle": {
"type": "string"
},
"accent": {
"type": "string",
"description": "Hex color, for example #f28f84."
},
"sting": {
"type": "string",
"enum": [
"none",
"chime",
"bass",
"glitch",
"shutter"
]
}
}
},
"range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "Required for episode_id and recording_id rows. The field is named range and contains the half-open interval [start_seconds, end_seconds): EPISODE time for episode_id, SOURCE time for recording_id."
},
"crop_strategy": {
"type": "string",
"enum": [
"center_crop",
"fit_pad"
]
},
"audio_policy": {
"type": "string",
"enum": [
"source",
"mute"
]
},
"caption_mode": {
"type": "string",
"enum": [
"inherit",
"off",
"on"
]
},
"boundary_rationale": {
"type": "object",
"description": "Optional audit notes for selected boundaries.",
"properties": {
"start": {
"type": "string"
},
"end": {
"type": "string"
}
}
},
"zoom_regions": {
"type": "array",
"description": "Optional audit list of consulted source/episode windows.",
"items": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
}
}
},
"required": [],
"additionalProperties": false
}
},
"title": {
"type": "string",
"description": "Title for the new episode."
},
"description": {
"type": "string",
"description": "Optional episode description."
},
"derived_from_id": {
"type": "string",
"description": "Optional parent Episode public ID used only for lineage/filing. It does not select media or replace segments[].range. It files a multi-segment reel cut from one existing Episode under that parent instead of listing it as a primary project Episode."
},
"aspect_ratio": {
"type": "string",
"enum": [
"9:16",
"16:9",
"1:1"
],
"description": "Output shape, set only for a shape the user asked for or a named vertical destination (Reels/Shorts/TikTok). When omitted it follows the footage: the source recording's native aspect, nearest of 9:16/16:9/1:1, and 16:9 when unprobed. \"Reel\" describes the edit, not the shape: 9:16 on landscape footage crops the sides away and can cut a second person out of frame."
},
"transition": {
"type": "string",
"enum": [
"cut",
"dip_to_black",
"overlap_dissolve"
],
"description": "Optional seam transition for segment boundaries. Defaults to cut."
},
"identity": {
"oneOf": [
{
"type": "string",
"enum": [
"project_default",
"none"
]
},
{
"type": "object",
"properties": {
"opener": {
"type": "string",
"description": "Explicit opener library_entry_id returned by identity_assets_list, or none; a specific saved asset instead of project_default."
},
"outro": {
"type": "string",
"description": "Explicit outro library_entry_id returned by identity_assets_list, or none; a specific saved asset instead of project_default."
}
},
"additionalProperties": false
}
],
"description": "Optional highlight-reel Signature. project_default applies the project's saved Signature defaults (the user's branding); saved project music becomes a full-Episode music cue. identity_assets_list lists saved openers and outros with their uses_title. The object form chooses explicit saved opener and outro assets. A specific song is added or changed with music_cue_mutate after creation. Omitted object keys mean none."
},
"opener_title": {
"type": "string",
"description": "Optional per-reel opener title, used only when the selected opener asset has uses_title:true; static or absent openers return identity_warnings:[\"opener_title_ignored_static_opener\"] and ignore this value."
},
"supersedes_episode_id": {
"type": "string",
"description": "Optional explicit lineage for a replacement draft the user deliberately asks for. It does not resolve edge_warnings, which are revised on the same created target with episode_edit."
},
"idempotency_key": {
"type": "string",
"description": "Opaque key unique across the account for this logical creation. Under a v3 editor ask it is the full requestId plus a distinct action suffix; otherwise it is a fresh opaque key chosen once. Exact retry/recovery reuses the original complete key and arguments, including across later messages. A key derived from titles or media ranges changes with them, and a new key on an ambiguous write can create a duplicate. A near-duplicate this same session already created comes back with near_duplicate:true instead of a second row."
}
},
"required": [
"segments",
"idempotency_key"
],
"additionalProperties": false
},
"annotations": {
"title": "Create an episode or derived reel",
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
],
"ui": {
"visibility": [
"model",
"app"
]
},
"openai/widgetAccessible": true
},
"outputSchema": {
"type": "object",
"properties": {
"episode_id": {
"type": "string"
},
"near_duplicate": {
"type": "boolean",
"description": "True when nothing was created because this session already made a near-identical derived clip; the returned handles are that existing clip's. That clip is refined with episode_edit; repeating the create returns it again."
},
"already_applied": {
"type": "boolean",
"description": "True when the returned persisted Clip was already in place: either an exact same-key replay, or (with near_duplicate:true) same-session range convergence."
},
"clip_id": {
"type": "string",
"description": "Present when target_type is clip. The episode_id alias remains for compatibility."
},
"target_type": {
"type": "string",
"enum": [
"episode",
"clip"
],
"description": "Structural kind of the created composition."
},
"target_id": {
"type": "string",
"description": "Canonical handle for the created Episode or Clip."
},
"title": {
"type": "string",
"description": "Persisted title of the created Episode or Clip."
},
"segment_count": {
"type": "integer",
"description": "Number of persisted Program segments in the returned target."
},
"creation_disposition": {
"type": "string",
"enum": [
"created",
"replayed",
"converged"
],
"description": "Whether this call created a target, replayed the exact idempotent create, or converged onto an existing near-duplicate."
},
"duration_seconds": {
"type": "number",
"description": "Kept play length in seconds."
},
"total_duration_seconds": {
"type": "number",
"description": "Total Program duration, including applied identity segments."
},
"content_duration_seconds": {
"type": "number",
"description": "Duration of the requested editorial content before identity additions."
},
"derived_from_id": {
"type": [
"string",
"null"
],
"description": "Parent Episode handle when the created target is a Clip."
},
"identity_opener": {
"type": [
"object",
"null"
],
"description": "Compact applied opener summary when present."
},
"project_id": {
"type": [
"string",
"null"
],
"description": "Owning Project handle when present."
},
"workspace_url": {
"type": "string",
"description": "BitterClip workspace URL for the created target."
},
"revision": {
"type": "integer",
"description": "Durable revision counter (starts at 1 for a fresh episode)."
},
"tool_outcome": {
"type": "object",
"description": "Persisted production receipt with the exact target, revision, and next Open action."
},
"segments": {
"type": "array",
"description": "The persisted segment manifest (index, source_id, source_label, source_range, episode_range, boundary)."
},
"block_segments": {
"type": "array",
"description": "Template-backed segments created during this request.",
"items": {
"type": "object",
"properties": {
"position": {
"type": "integer"
},
"template": {
"type": "string"
},
"source_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"ready",
"preparing",
"failed"
],
"description": "Whether the template-backed Recording is already renderable or still baking."
}
}
}
},
"edge_warnings": {
"type": "array",
"description": "Always present. Non-mutating flags for cut edges that overlap approximate transcript word spans; acoustic verification decides whether the existing point is supported.",
"items": {
"type": "object",
"properties": {
"segment_index": {
"type": "integer"
},
"edge": {
"type": "string",
"enum": [
"start",
"end"
]
},
"at_seconds": {
"type": "number",
"description": "Recording source time for the flagged edge. This legacy field name is not Episode time."
},
"source_id": {
"type": "string",
"description": "Recording containing the flagged source edge."
},
"occurrence_id": {
"type": "string",
"description": "Exact created-target occurrence containing this edge, when mapped."
},
"episode_seconds": {
"type": "number",
"description": "Exact flagged point on the created target's Episode clock, usable directly as an episode_zoom edge; occurrence_id identifies its source side."
},
"word": {
"type": "string"
},
"word_range_source": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
}
}
}
},
"identity_plan": {
"type": [
"object",
"null"
],
"description": "Frozen resolved identity plan when identity: project_default resolved to an applied project identity."
},
"identity_layers": {
"type": "array",
"description": "Resolved Signature layers such as opener, cut style, and outro."
},
"identity_segments": {
"type": "array",
"description": "Identity-inserted segment rows with role, final_position, and segment_id for follow-up edits."
},
"identity_warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Identity warnings such as project_identity_missing or unsupported identity config."
},
"request_row_map": {
"type": "array",
"description": "Mapping from requested rows to final composition positions, including segment_id. Identity insertion shifts these positions."
},
"derived": {
"type": "boolean",
"description": "True when this edit is filed under a parent episode via derived_from_id and hidden from the primary episode index."
},
"derived_episode": {
"type": "boolean",
"description": "Present and true only for a top-level montage assembled from episode_id segments without derived_from_id."
},
"derived_from_episode_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Source episode IDs used to assemble a top-level montage episode."
},
"program_audio": {
"type": "object",
"description": "Present on a fresh create cut from existing Episodes/Clips: preserved is true because each selected range was proven to play the same Recording and source second (or silence) as its parent. settled says how: none (plain occurrence audio), pin, intervals or pin_and_intervals.",
"properties": {
"preserved": {
"type": "boolean"
},
"settled": {
"type": "string",
"enum": [
"none",
"pin",
"intervals",
"pin_and_intervals"
]
},
"pinned_camera_group_key": {
"type": "string",
"description": "The camera group the new target's Program audio is pinned to, when settled includes pin."
},
"authorities": {
"type": "array",
"description": "Seconds of the new target played by each authority and Recording.",
"items": {
"type": "object",
"properties": {
"authority": {
"type": "string",
"enum": [
"occurrence_base",
"pinned_primary",
"explicit_replace",
"explicit_silence",
"silence"
]
},
"recording_id": {
"type": "string"
},
"seconds": {
"type": "number"
}
}
}
}
}
},
"status": {
"type": "string",
"description": "Always draft — persisted but not rendered."
},
"blockers": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [
"edge_warnings"
],
"additionalProperties": false
}
}Live Workspace descriptor
{
"name": "episode_create",
"title": "Create an episode or derived reel",
"description": "Assembles a new EPISODE or derived reel from ordered recording/episode/template ranges into ONE combined video. A reel cut from an Episode takes derived_from_id for lineage and one segment row per chosen moment in the canonical shape {episode_id, range:[start_seconds,end_seconds]}; segments[].range is a half-open [start,end) interval in EPISODE time. derived_from_id does not select a range. Creation selects Program ranges; simultaneous participant boxes are composed afterwards with camera_program_set, not with extra segment fields. Use this when the user asks to make, cut together, or export a multi-segment highlight, reel, montage, or supercut. Suggestions alone create nothing (saved Moments are review_points_place), and a single-range Clip is clip_create. Branding: identity:\"project_default\" applies the project's saved Signature defaults (the user's branding); identity_assets_list lists the saved assets an explicit choice names. Episode-range slices keep what their parent plays there (a pinned or replaced microphone, silence) and program_audio names it; audio that cannot be carried, such as a pinned microphone in a montage without derived_from_id, refuses with program_audio_not_preservable and its exact span. Persists the edit only — does not render or charge. The rendered video is a separate render_create with the exact returned target_type, target_id, and revision; render_status reports it. Publishing is separate. Always returns edge_warnings. A warning means a cut edge overlaps an approximate transcript word span, not that acoustic evidence proved a mid-word cut. Each warning's episode_seconds is the created target's point for a narrow episode_zoom region and edge, and occurrence_id and source_id identify the exact side; when those coordinates are absent, episode_read of the target maps the edge. A point whose speech evidence is supported inter_word_silence or supported aligned_word_edge stands; any other point is revised on the same target with episode_edit at an exact supported point. Acoustic envelope/onset suggestions alone are not boundary authority. A second episode_create or a superseding Clip does not resolve edge_warnings. Accepts idempotency_key. A creation with derived_from_id produces a Clip (a derived Episode IS a Clip), addressed as target_type:\"clip\" in render_create, render_status, and workspace_get_link. A canvas taller than the source picture (a portrait canvas over landscape footage) keeps only a vertical slice of each frame; episode_framing_guidance reports, per visible person, whether their measured extent fits that crop window (fits | too_wide | uncertain | unknown), and episode_edit occurrence.reframe carries the framing decision.",
"inputSchema": {
"type": "object",
"properties": {
"segments": {
"type": "array",
"description": "Ordered episode/recording/template segments. The only model-visible boundary field is range: {episode_id, range:[start,end]} in EPISODE time or {recording_id, range:[start,end]} in SOURCE time, both half-open [start,end) intervals; episode_range and start_seconds/end_seconds are not accepted. Template rows use {template, params} and have no range.",
"minItems": 1,
"items": {
"type": "object",
"oneOf": [
{
"required": [
"episode_id",
"range"
]
},
{
"required": [
"recording_id",
"range"
]
},
{
"required": [
"template"
],
"not": {
"required": [
"range"
]
}
}
],
"properties": {
"episode_id": {
"type": "string",
"description": "Source Episode public ID. This row must also provide range in half-open EPISODE time."
},
"recording_id": {
"type": "string",
"description": "Source Recording public ID. This row must also provide range in half-open SOURCE time."
},
"template": {
"type": "string",
"description": "Curated block template key, such as show_open/studio_dissolve or outro/sting_chime."
},
"params": {
"type": "object",
"description": "Template parameters.",
"properties": {
"title": {
"type": "string"
},
"subtitle": {
"type": "string"
},
"accent": {
"type": "string",
"description": "Hex color, for example #f28f84."
},
"sting": {
"type": "string",
"enum": [
"none",
"chime",
"bass",
"glitch",
"shutter"
]
}
}
},
"range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "Required for episode_id and recording_id rows. The field is named range and contains the half-open interval [start_seconds, end_seconds): EPISODE time for episode_id, SOURCE time for recording_id."
},
"crop_strategy": {
"type": "string",
"enum": [
"center_crop",
"fit_pad"
]
},
"audio_policy": {
"type": "string",
"enum": [
"source",
"mute"
]
},
"caption_mode": {
"type": "string",
"enum": [
"inherit",
"off",
"on"
]
},
"boundary_rationale": {
"type": "object",
"description": "Optional audit notes for selected boundaries.",
"properties": {
"start": {
"type": "string"
},
"end": {
"type": "string"
}
}
},
"zoom_regions": {
"type": "array",
"description": "Optional audit list of consulted source/episode windows.",
"items": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
}
}
},
"required": [],
"additionalProperties": false
}
},
"title": {
"type": "string",
"description": "Title for the new episode."
},
"description": {
"type": "string",
"description": "Optional episode description."
},
"derived_from_id": {
"type": "string",
"description": "Optional parent Episode public ID used only for lineage/filing. It does not select media or replace segments[].range. It files a multi-segment reel cut from one existing Episode under that parent instead of listing it as a primary project Episode."
},
"aspect_ratio": {
"type": "string",
"enum": [
"9:16",
"16:9",
"1:1"
],
"description": "Output shape, set only for a shape the user asked for or a named vertical destination (Reels/Shorts/TikTok). When omitted it follows the footage: the source recording's native aspect, nearest of 9:16/16:9/1:1, and 16:9 when unprobed. \"Reel\" describes the edit, not the shape: 9:16 on landscape footage crops the sides away and can cut a second person out of frame."
},
"transition": {
"type": "string",
"enum": [
"cut",
"dip_to_black",
"overlap_dissolve"
],
"description": "Optional seam transition for segment boundaries. Defaults to cut."
},
"identity": {
"oneOf": [
{
"type": "string",
"enum": [
"project_default",
"none"
]
},
{
"type": "object",
"properties": {
"opener": {
"type": "string",
"description": "Explicit opener library_entry_id returned by identity_assets_list, or none; a specific saved asset instead of project_default."
},
"outro": {
"type": "string",
"description": "Explicit outro library_entry_id returned by identity_assets_list, or none; a specific saved asset instead of project_default."
}
},
"additionalProperties": false
}
],
"description": "Optional highlight-reel Signature. project_default applies the project's saved Signature defaults (the user's branding); saved project music becomes a full-Episode music cue. identity_assets_list lists saved openers and outros with their uses_title. The object form chooses explicit saved opener and outro assets. A specific song is added or changed with music_cue_mutate after creation. Omitted object keys mean none."
},
"opener_title": {
"type": "string",
"description": "Optional per-reel opener title, used only when the selected opener asset has uses_title:true; static or absent openers return identity_warnings:[\"opener_title_ignored_static_opener\"] and ignore this value."
},
"supersedes_episode_id": {
"type": "string",
"description": "Optional explicit lineage for a replacement draft the user deliberately asks for. It does not resolve edge_warnings, which are revised on the same created target with episode_edit."
},
"idempotency_key": {
"type": "string",
"description": "Opaque key unique across the account for this logical creation. Under a v3 editor ask it is the full requestId plus a distinct action suffix; otherwise it is a fresh opaque key chosen once. Exact retry/recovery reuses the original complete key and arguments, including across later messages. A key derived from titles or media ranges changes with them, and a new key on an ambiguous write can create a duplicate. A near-duplicate this same session already created comes back with near_duplicate:true instead of a second row."
}
},
"required": [
"segments",
"idempotency_key"
],
"additionalProperties": false
},
"annotations": {
"title": "Create an episode or derived reel",
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
},
"outputSchema": {
"type": "object",
"properties": {
"episode_id": {
"type": "string"
},
"near_duplicate": {
"type": "boolean",
"description": "True when nothing was created because this session already made a near-identical derived clip; the returned handles are that existing clip's. That clip is refined with episode_edit; repeating the create returns it again."
},
"already_applied": {
"type": "boolean",
"description": "True when the returned persisted Clip was already in place: either an exact same-key replay, or (with near_duplicate:true) same-session range convergence."
},
"clip_id": {
"type": "string",
"description": "Present when target_type is clip. The episode_id alias remains for compatibility."
},
"target_type": {
"type": "string",
"enum": [
"episode",
"clip"
],
"description": "Structural kind of the created composition."
},
"target_id": {
"type": "string",
"description": "Canonical handle for the created Episode or Clip."
},
"title": {
"type": "string",
"description": "Persisted title of the created Episode or Clip."
},
"segment_count": {
"type": "integer",
"description": "Number of persisted Program segments in the returned target."
},
"creation_disposition": {
"type": "string",
"enum": [
"created",
"replayed",
"converged"
],
"description": "Whether this call created a target, replayed the exact idempotent create, or converged onto an existing near-duplicate."
},
"duration_seconds": {
"type": "number",
"description": "Kept play length in seconds."
},
"total_duration_seconds": {
"type": "number",
"description": "Total Program duration, including applied identity segments."
},
"content_duration_seconds": {
"type": "number",
"description": "Duration of the requested editorial content before identity additions."
},
"derived_from_id": {
"type": [
"string",
"null"
],
"description": "Parent Episode handle when the created target is a Clip."
},
"identity_opener": {
"type": [
"object",
"null"
],
"description": "Compact applied opener summary when present."
},
"project_id": {
"type": [
"string",
"null"
],
"description": "Owning Project handle when present."
},
"workspace_url": {
"type": "string",
"description": "BitterClip workspace URL for the created target."
},
"revision": {
"type": "integer",
"description": "Durable revision counter (starts at 1 for a fresh episode)."
},
"tool_outcome": {
"type": "object",
"description": "Persisted production receipt with the exact target, revision, and next Open action."
},
"segments": {
"type": "array",
"description": "The persisted segment manifest (index, source_id, source_label, source_range, episode_range, boundary)."
},
"block_segments": {
"type": "array",
"description": "Template-backed segments created during this request.",
"items": {
"type": "object",
"properties": {
"position": {
"type": "integer"
},
"template": {
"type": "string"
},
"source_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"ready",
"preparing",
"failed"
],
"description": "Whether the template-backed Recording is already renderable or still baking."
}
}
}
},
"edge_warnings": {
"type": "array",
"description": "Always present. Non-mutating flags for cut edges that overlap approximate transcript word spans; acoustic verification decides whether the existing point is supported.",
"items": {
"type": "object",
"properties": {
"segment_index": {
"type": "integer"
},
"edge": {
"type": "string",
"enum": [
"start",
"end"
]
},
"at_seconds": {
"type": "number",
"description": "Recording source time for the flagged edge. This legacy field name is not Episode time."
},
"source_id": {
"type": "string",
"description": "Recording containing the flagged source edge."
},
"occurrence_id": {
"type": "string",
"description": "Exact created-target occurrence containing this edge, when mapped."
},
"episode_seconds": {
"type": "number",
"description": "Exact flagged point on the created target's Episode clock, usable directly as an episode_zoom edge; occurrence_id identifies its source side."
},
"word": {
"type": "string"
},
"word_range_source": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
}
}
}
},
"identity_plan": {
"type": [
"object",
"null"
],
"description": "Frozen resolved identity plan when identity: project_default resolved to an applied project identity."
},
"identity_layers": {
"type": "array",
"description": "Resolved Signature layers such as opener, cut style, and outro."
},
"identity_segments": {
"type": "array",
"description": "Identity-inserted segment rows with role, final_position, and segment_id for follow-up edits."
},
"identity_warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Identity warnings such as project_identity_missing or unsupported identity config."
},
"request_row_map": {
"type": "array",
"description": "Mapping from requested rows to final composition positions, including segment_id. Identity insertion shifts these positions."
},
"derived": {
"type": "boolean",
"description": "True when this edit is filed under a parent episode via derived_from_id and hidden from the primary episode index."
},
"derived_episode": {
"type": "boolean",
"description": "Present and true only for a top-level montage assembled from episode_id segments without derived_from_id."
},
"derived_from_episode_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Source episode IDs used to assemble a top-level montage episode."
},
"program_audio": {
"type": "object",
"description": "Present on a fresh create cut from existing Episodes/Clips: preserved is true because each selected range was proven to play the same Recording and source second (or silence) as its parent. settled says how: none (plain occurrence audio), pin, intervals or pin_and_intervals.",
"properties": {
"preserved": {
"type": "boolean"
},
"settled": {
"type": "string",
"enum": [
"none",
"pin",
"intervals",
"pin_and_intervals"
]
},
"pinned_camera_group_key": {
"type": "string",
"description": "The camera group the new target's Program audio is pinned to, when settled includes pin."
},
"authorities": {
"type": "array",
"description": "Seconds of the new target played by each authority and Recording.",
"items": {
"type": "object",
"properties": {
"authority": {
"type": "string",
"enum": [
"occurrence_base",
"pinned_primary",
"explicit_replace",
"explicit_silence",
"silence"
]
},
"recording_id": {
"type": "string"
},
"seconds": {
"type": "number"
}
}
}
}
}
},
"status": {
"type": "string",
"description": "Always draft — persisted but not rendered."
},
"blockers": {
"type": "array",
"items": {
"type": "object"
}
},
"workspace_binding": {
"type": "object",
"properties": {
"schema": {
"type": "string",
"enum": [
"bitterclip.workspace-binding.v2"
]
},
"mode": {
"type": "string",
"enum": [
"live_workspace"
]
},
"project_id": {
"type": "string"
},
"target_kind": {
"type": "string",
"enum": [
"episode",
"clip"
]
},
"target_id": {
"type": "string"
},
"revision": {
"type": "integer"
},
"draft_revision": {
"type": "string"
},
"workspace_url": {
"type": "string"
},
"output_id": {
"type": "string"
},
"output_status": {
"type": "string",
"enum": [
"missing",
"stale",
"rendering",
"ready",
"failed"
]
},
"output_revision": {
"type": "integer"
},
"parent_episode_id": {
"type": "string"
}
},
"required": [
"schema",
"mode",
"target_kind",
"target_id",
"revision",
"draft_revision",
"workspace_url",
"output_status"
],
"additionalProperties": false
}
},
"required": [
"edge_warnings"
],
"additionalProperties": false
}
}Errors
[
"composition_not_found",
"recording_not_found",
"invalid_time_range",
"invalid_input",
"identity_asset_not_found",
"identity_brand_mismatch",
"music_range_derivation_unsupported",
"program_audio_not_preservable",
"program_source_range_unplayable",
"stale_composition_revision"
]Examples
[
{
"label": "Create a top-level episode from recording ranges",
"input": {
"segments": [
{
"recording_id": "src_...",
"range": [
0,
300
]
}
],
"title": "Episode 3",
"idempotency_key": "episode-1"
}
},
{
"label": "Create a derived highlight reel under one parent episode",
"input": {
"derived_from_id": "comp_parent",
"segments": [
{
"episode_id": "comp_parent",
"range": [
124.5,
151
]
},
{
"episode_id": "comp_parent",
"range": [
421,
455
]
}
],
"title": "Best moments",
"idempotency_key": "episode-reel-1"
}
},
{
"label": "Create a top-level montage from multiple episodes",
"input": {
"segments": [
{
"episode_id": "comp_a",
"range": [
124.5,
151
]
},
{
"episode_id": "comp_b",
"range": [
421,
455
]
}
],
"title": "Cross-episode best moments",
"idempotency_key": "episode-montage-1"
}
}
]