# clip_create
Canonical HTML page: https://bitterclip.com/docs/assistants/tools/clip_create
Surface: default model and app
Product release: 1dce717408a55fac1047e7d779177fa3ef8ede51
Public contract commit: 1ce47f7857ae3d9b6933fe83d5c33de3ae5efc64
Public contract SHA-256: 241d47d25e4b4c1dae9d2263793874d06fc4ba7bc3c78d4cf2bc63fbb32ed7dc
Descriptor SHA-256: 885d46f3ca3939dec2ace0cd6e93611c8b3f741f2d8f7a82e0adfe1452cc9a9e
Captured: 2026-09-24T16:39:30.100Z
Source: https://app.bitterclip.com/api/v1/mcp_descriptors.json
Create a short derived Clip from one current Program range. Use typed input:{type:clip|episode,id:comp_...} plus a stable variant_id for an explicitly requested fresh alternative. Range uses that input production's local Program time; Rails maps its current source occurrences. Ordinary shortening edits the existing Clip with episode_edit. This is for a single-range Clip; several moments combined into one video should use episode_create, not N clips. If this Clip must show a simultaneous Picture layout, first prove complete distinct-camera coverage for the entire range; never create a Clip as a coverage probe, and explain any necessary range shift before writing. The Clip keeps what the parent plays over that range (a pinned or replaced microphone, silence) and program_audio names it; audio that cannot be carried refuses with program_audio_not_preservable and the exact span to avoid. This persists the Clip only; it does not open or render. For ordinary make/cut/create Clip intent, continue with render_create using target_type:"clip", the exact returned clip_id as target_id, and the returned revision, then render_status until ready unless the user asks for draft-only, review-first, or no-render. Report private Download/editor Open; never quote or retain its capability URL. Publishing stays explicit. Optional aspect_ratio sets the draft/render default, not a finished Export.
The JSON blocks below are the exact MCP descriptor projections served by Rails for the named profiles at capture time. Security schemes and resource URIs may vary by connected host.
## Default model descriptor
```json
{
"name": "clip_create",
"title": "Create a clip",
"description": "Create a short derived Clip from one current Program range. Use typed input:{type:clip|episode,id:comp_...} plus a stable variant_id for an explicitly requested fresh alternative. Range uses that input production's local Program time; Rails maps its current source occurrences. Ordinary shortening edits the existing Clip with episode_edit. This is for a single-range Clip; several moments combined into one video should use episode_create, not N clips. If this Clip must show a simultaneous Picture layout, first prove complete distinct-camera coverage for the entire range; never create a Clip as a coverage probe, and explain any necessary range shift before writing. The Clip keeps what the parent plays over that range (a pinned or replaced microphone, silence) and program_audio names it; audio that cannot be carried refuses with program_audio_not_preservable and the exact span to avoid. This persists the Clip only; it does not open or render. For ordinary make/cut/create Clip intent, continue with render_create using target_type:\"clip\", the exact returned clip_id as target_id, and the returned revision, then render_status until ready unless the user asks for draft-only, review-first, or no-render. Report private Download/editor Open; never quote or retain its capability URL. Publishing stays explicit. Optional aspect_ratio sets the draft/render default, not a finished Export.",
"inputSchema": {
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "Compatibility top-level Episode input. Mutually exclusive with input."
},
"input": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"episode",
"clip"
]
},
"id": {
"type": "string"
}
},
"required": [
"type",
"id"
],
"additionalProperties": false
},
"variant_id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Required with typed input. Stable identity of the explicitly requested alternative; retain on retries. A separate requested alternative uses a new variant_id and idempotency_key."
},
"range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "[start_seconds, end_seconds] in the selected input production's current local Program time."
},
"expected_revision": {
"type": "integer",
"description": "Required input production Program revision captured with the selected range. A new-key call refuses if the parent changed; an exact same-key replay still returns its existing Clip."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Clip title. When supplied, use 1-200 characters with no surrounding whitespace."
},
"description": {
"type": "string",
"description": "Optional clip description."
},
"aspect_ratio": {
"type": "string",
"enum": [
"9:16",
"16:9",
"1:1"
],
"description": "OMIT THIS unless the user asked for a specific shape or named a vertical destination. Left alone a typed variant preserves its input shape; legacy Episode input follows the footage. Setting 9:16 on landscape footage crops the sides away. render_create still materializes media."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable key for safe retry. Scope it to the ask (conversation + attempt), never derive it from the media range — a range-derived key changes when you refine the cut, so idempotency never fires. A near-duplicate this same session already created comes back with near_duplicate:true instead of a second clip."
}
},
"required": [
"range",
"expected_revision",
"idempotency_key"
],
"additionalProperties": false,
"oneOf": [
{
"required": [
"episode_id"
],
"not": {
"anyOf": [
{
"required": [
"input"
]
},
{
"required": [
"variant_id"
]
}
]
}
},
{
"required": [
"input",
"variant_id"
],
"not": {
"required": [
"episode_id"
]
}
}
]
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
],
"ui": {
"visibility": [
"model",
"app"
]
},
"openai/widgetAccessible": true
}
}
```
## App descriptor
```json
{
"name": "clip_create",
"title": "Create a clip",
"description": "Create a short derived Clip from one current Program range. Use typed input:{type:clip|episode,id:comp_...} plus a stable variant_id for an explicitly requested fresh alternative. Range uses that input production's local Program time; Rails maps its current source occurrences. Ordinary shortening edits the existing Clip with episode_edit. This is for a single-range Clip; several moments combined into one video should use episode_create, not N clips. If this Clip must show a simultaneous Picture layout, first prove complete distinct-camera coverage for the entire range; never create a Clip as a coverage probe, and explain any necessary range shift before writing. The Clip keeps what the parent plays over that range (a pinned or replaced microphone, silence) and program_audio names it; audio that cannot be carried refuses with program_audio_not_preservable and the exact span to avoid. This persists the Clip only; it does not open or render. For ordinary make/cut/create Clip intent, continue with render_create using target_type:\"clip\", the exact returned clip_id as target_id, and the returned revision, then render_status until ready unless the user asks for draft-only, review-first, or no-render. Report private Download/editor Open; never quote or retain its capability URL. Publishing stays explicit. Optional aspect_ratio sets the draft/render default, not a finished Export.",
"inputSchema": {
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "Compatibility top-level Episode input. Mutually exclusive with input."
},
"input": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"episode",
"clip"
]
},
"id": {
"type": "string"
}
},
"required": [
"type",
"id"
],
"additionalProperties": false
},
"variant_id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Required with typed input. Stable identity of the explicitly requested alternative; retain on retries. A separate requested alternative uses a new variant_id and idempotency_key."
},
"range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "[start_seconds, end_seconds] in the selected input production's current local Program time."
},
"expected_revision": {
"type": "integer",
"description": "Required input production Program revision captured with the selected range. A new-key call refuses if the parent changed; an exact same-key replay still returns its existing Clip."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Clip title. When supplied, use 1-200 characters with no surrounding whitespace."
},
"description": {
"type": "string",
"description": "Optional clip description."
},
"aspect_ratio": {
"type": "string",
"enum": [
"9:16",
"16:9",
"1:1"
],
"description": "OMIT THIS unless the user asked for a specific shape or named a vertical destination. Left alone a typed variant preserves its input shape; legacy Episode input follows the footage. Setting 9:16 on landscape footage crops the sides away. render_create still materializes media."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable key for safe retry. Scope it to the ask (conversation + attempt), never derive it from the media range — a range-derived key changes when you refine the cut, so idempotency never fires. A near-duplicate this same session already created comes back with near_duplicate:true instead of a second clip."
}
},
"required": [
"range",
"expected_revision",
"idempotency_key"
],
"additionalProperties": false,
"oneOf": [
{
"required": [
"episode_id"
],
"not": {
"anyOf": [
{
"required": [
"input"
]
},
{
"required": [
"variant_id"
]
}
]
}
},
{
"required": [
"input",
"variant_id"
],
"not": {
"required": [
"episode_id"
]
}
}
]
},
"annotations": {
"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": {
"clip_id": {
"type": "string"
},
"title": {
"type": "string",
"description": "The persisted Clip title, reread from the created or converged Clip."
},
"range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "The exact persisted parent-Episode [start_seconds, end_seconds] range represented by this Clip."
},
"episode_id": {
"type": "string"
},
"episode_title": {
"type": "string"
},
"project_id": {
"type": "string"
},
"project_title": {
"type": "string"
},
"status": {
"type": "string"
},
"duration_seconds": {
"type": "number"
},
"revision": {
"type": "integer"
},
"edge_warnings": {
"type": "array",
"items": {
"type": "object"
},
"description": "Recording boundary evidence requiring review before delivery."
},
"tool_outcome": {
"type": "object",
"description": "Persisted production receipt with the exact target, revision, and next Open action."
},
"near_duplicate": {
"type": "boolean",
"description": "True when nothing was created: this session already made a near-identical clip of this episode and the returned handles are that clip's. Refine it with episode_edit; do not retry the create."
},
"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."
},
"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"
}
}
}
}
}
},
"user_presence": {
"type": "object",
"description": "Present when a live editor session on the parent episode is active: this is presence only, not visible navigation acknowledgement. Always preserve the exact Open Clip action. Absent means visibility is unknown; do not claim it."
},
"opened": {
"type": "boolean"
},
"review_status": {
"type": "string",
"enum": [
"created_not_opened",
"idempotency_replay_returned",
"near_duplicate_returned"
]
},
"next_action": {
"type": "object"
},
"blockers": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [],
"additionalProperties": false
}
}
```
## Live Workspace descriptor
```json
{
"name": "clip_create",
"title": "Create a clip",
"description": "Create a short derived Clip from one current Program range. Use typed input:{type:clip|episode,id:comp_...} plus a stable variant_id for an explicitly requested fresh alternative. Range uses that input production's local Program time; Rails maps its current source occurrences. Ordinary shortening edits the existing Clip with episode_edit. This is for a single-range Clip; several moments combined into one video should use episode_create, not N clips. If this Clip must show a simultaneous Picture layout, first prove complete distinct-camera coverage for the entire range; never create a Clip as a coverage probe, and explain any necessary range shift before writing. The Clip keeps what the parent plays over that range (a pinned or replaced microphone, silence) and program_audio names it; audio that cannot be carried refuses with program_audio_not_preservable and the exact span to avoid. This persists the Clip only; it does not open or render. For ordinary make/cut/create Clip intent, continue with render_create using target_type:\"clip\", the exact returned clip_id as target_id, and the returned revision, then render_status until ready unless the user asks for draft-only, review-first, or no-render. Report private Download/editor Open; never quote or retain its capability URL. Publishing stays explicit. Optional aspect_ratio sets the draft/render default, not a finished Export.",
"inputSchema": {
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "Compatibility top-level Episode input. Mutually exclusive with input."
},
"input": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"episode",
"clip"
]
},
"id": {
"type": "string"
}
},
"required": [
"type",
"id"
],
"additionalProperties": false
},
"variant_id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Required with typed input. Stable identity of the explicitly requested alternative; retain on retries. A separate requested alternative uses a new variant_id and idempotency_key."
},
"range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "[start_seconds, end_seconds] in the selected input production's current local Program time."
},
"expected_revision": {
"type": "integer",
"description": "Required input production Program revision captured with the selected range. A new-key call refuses if the parent changed; an exact same-key replay still returns its existing Clip."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Clip title. When supplied, use 1-200 characters with no surrounding whitespace."
},
"description": {
"type": "string",
"description": "Optional clip description."
},
"aspect_ratio": {
"type": "string",
"enum": [
"9:16",
"16:9",
"1:1"
],
"description": "OMIT THIS unless the user asked for a specific shape or named a vertical destination. Left alone a typed variant preserves its input shape; legacy Episode input follows the footage. Setting 9:16 on landscape footage crops the sides away. render_create still materializes media."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable key for safe retry. Scope it to the ask (conversation + attempt), never derive it from the media range — a range-derived key changes when you refine the cut, so idempotency never fires. A near-duplicate this same session already created comes back with near_duplicate:true instead of a second clip."
}
},
"required": [
"range",
"expected_revision",
"idempotency_key"
],
"additionalProperties": false,
"oneOf": [
{
"required": [
"episode_id"
],
"not": {
"anyOf": [
{
"required": [
"input"
]
},
{
"required": [
"variant_id"
]
}
]
}
},
{
"required": [
"input",
"variant_id"
],
"not": {
"required": [
"episode_id"
]
}
}
]
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
},
"outputSchema": {
"type": "object",
"properties": {
"clip_id": {
"type": "string"
},
"title": {
"type": "string",
"description": "The persisted Clip title, reread from the created or converged Clip."
},
"range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "The exact persisted parent-Episode [start_seconds, end_seconds] range represented by this Clip."
},
"episode_id": {
"type": "string"
},
"episode_title": {
"type": "string"
},
"project_id": {
"type": "string"
},
"project_title": {
"type": "string"
},
"status": {
"type": "string"
},
"duration_seconds": {
"type": "number"
},
"revision": {
"type": "integer"
},
"edge_warnings": {
"type": "array",
"items": {
"type": "object"
},
"description": "Recording boundary evidence requiring review before delivery."
},
"tool_outcome": {
"type": "object",
"description": "Persisted production receipt with the exact target, revision, and next Open action."
},
"near_duplicate": {
"type": "boolean",
"description": "True when nothing was created: this session already made a near-identical clip of this episode and the returned handles are that clip's. Refine it with episode_edit; do not retry the create."
},
"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."
},
"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"
}
}
}
}
}
},
"user_presence": {
"type": "object",
"description": "Present when a live editor session on the parent episode is active: this is presence only, not visible navigation acknowledgement. Always preserve the exact Open Clip action. Absent means visibility is unknown; do not claim it."
},
"opened": {
"type": "boolean"
},
"review_status": {
"type": "string",
"enum": [
"created_not_opened",
"idempotency_replay_returned",
"near_duplicate_returned"
]
},
"next_action": {
"type": "object"
},
"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": [],
"additionalProperties": false
}
}
```
## Errors
```json
[
"composition_not_found",
"recording_not_found",
"stale_composition_revision",
"idempotency_conflict",
"invalid_time_range",
"invalid_input",
"program_audio_not_preservable",
"program_source_range_unplayable"
]
```
## Examples
```json
[]
```