Skip to main content
Glama

Create project

create_project

Creates a clipping project from a video URL or uploaded file, queues background processing, and returns a project ID to track progress.

Instructions

Start clipping a video from a URL (anything yt-dlp fetches) or a file you uploaded: POST /api/upload with the file as the body, header x-filename and your API key as Authorization: Bearer, then pass the uploadId it returns. Returns { id, title, status: "queued", next } at once; the pipeline (download, transcribe, pick, render) runs in the background for minutes, so follow with wait_for_project(id). Intro/outro default to your library defaults unless introAssetId/outroAssetId say otherwise.

Input Schema

NameRequiredDescriptionDefault
titleNoProject title (default: the video's own title)
introSecNoSeconds an intro image shows (1-10)
metadataNoYour own key/value strings (≤20 keys, 1 KB), returned by get_project and sent in every webhook for this project, e.g. { runId: "n8n-123" }
outroSecNoSeconds an outro image shows (1-10)
settingsNoProject settings; omit for the defaults (automatic clip count, 20–60 s clips, natural pauses, name fixes and the on-screen text scan on, filler removal off). Set refineDisfluency / disfluencyLlm true to opt into filler removal, refineEntities / refineScenes false to skip those steps (instance Pipeline gates must be on).
uploadIdNoId returned by POST /api/upload (the file body, x-filename header, API key as Bearer); give this or sourceUrl
sourceUrlNohttp(s) URL of the video; give this or uploadId
introAssetIdNoLibrary asset id (search_assets with source library) for the intro of every clip; null = no intro; omitted = your default intro
outroAssetIdNoSame for the outro

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.33.0
    • addedInput schema / properties / settings / properties / bumperTransition
      Added value: +{
      +  "description": "How the intro/outro joins the clip: cut (default), dip (fade through black, no change in length) or crossfade (the two overlap, so the video is shorter by the transition)",
      +  "enum": [
      +    "cut",
      +    "dip",
      +    "crossfade"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / settings / properties / bumperTransitionSec
      Added value: +{
      +  "description": "Length of the intro/outro transition, seconds (0.2-2, default 0.5); ignored for cut",
      +  "maximum": 2,
      +  "minimum": 0.2,
      +  "type": "number"
      +}
    • addedInput schema / properties / settings / properties / fadeIn
      Added value: +{
      +  "description": "Fade in from black (picture and sound) at the start of the video, seconds (0-2, default 0 = off)",
      +  "maximum": 2,
      +  "minimum": 0,
      +  "type": "number"
      +}
    • addedInput schema / properties / settings / properties / fadeOut
      Added value: +{
      +  "description": "Fade out to black (picture and sound) at the end of the video, seconds (0-2, default 0 = off)",
      +  "maximum": 2,
      +  "minimum": 0,
      +  "type": "number"
      +}
  2. Changed1 schema field changedv0.31.0
    • addedInput schema / properties / metadata
      Added value: +{
      +  "additionalProperties": {
      +    "maxLength": 500,
      +    "type": "string"
      +  },
      +  "description": "Your own key/value strings (≤20 keys, 1 KB), returned by get_project and sent in every webhook for this project, e.g. { runId: \"n8n-123\" }",
      +  "propertyNames": {
      +    "pattern": "^[A-Za-z0-9_.-]{1,40}$",
      +    "type": "string"
      +  },
      +  "type": "object"
      +}
  3. Changed1 schema field changedv0.28.1
    • addedInput schema / properties / settings / properties / captionSeam
      Added value: +{
      +  "description": "In split and stack sections, put captions on the line between the two panes instead of at captionY (default true)",
      +  "type": "boolean"
      +}
  4. Changed3 schema fields changedv0.26.3
    • changedInput schema / properties / sourceUrl / description
      Previous value: -"http(s) URL of the video"New value: +"http(s) URL of the video; give this or uploadId"
    • addedInput schema / properties / uploadId
      Added value: +{
      +  "description": "Id returned by POST /api/upload (the file body, x-filename header, API key as Bearer); give this or sourceUrl",
      +  "maxLength": 100,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • removedInput schema / required
      Removed value: -[
      -  "sourceUrl"
      -]
  5. Changed5 schema fields changedv0.23.0
    • changedInput schema / properties / settings / description
      Previous value: -"Project settings; omit for the defaults (automatic clip count, 20–60 s clips, natural pauses, refine steps off). Set refineEntities / refineDisfluency / disfluencyLlm / refineScenes true to opt into polish (instance Pipeline gates must be on)."New value: +"Project settings; omit for the defaults (automatic clip count, 20–60 s clips, natural pauses, name fixes and the on-screen text scan on, filler removal off). Set refineDisfluency / disfluencyLlm true to opt into filler removal, refineEntities / refineScenes false to skip those steps (instance Pipeline gates must be on)."
    • addedInput schema / properties / settings / properties / layerTemplateId
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maxLength": 100,
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Layer template id (list_layer_templates) applied to each new clip of this project; null = none. Existing clips: apply_layer_template"
      +}
    • changedInput schema / properties / settings / properties / refineEntities / description
      Previous value: -"Fix misheard names after transcription (LLM). Off by default; on runs that refine step."New value: +"Fix misheard names after transcription (LLM). On by default; off skips that refine step."
    • changedInput schema / properties / settings / properties / refineScenes / description
      Previous value: -"Detect scene cuts and on-screen text. Off by default; on runs that refine step."New value: +"Scan the video for on-screen text (burned-in captions, watermarks, slides). On by default; off skips that refine step. Shot cuts are always detected."
    • addedInput schema / properties / settings / properties / reframeAdjust
      Added value: +{
      +  "anyOf": [
      +    {
      +      "properties": {
      +        "contentCrop": {
      +          "description": "Stack only: the part of the frame shown on top instead of the whole frame or the detected content region",
      +          "properties": {
      +            "x1": {
      +              "description": "Left edge, fraction of the source width",
      +              "maximum": 1,
      +              "minimum": 0,
      +              "type": "number"
      +            },
      +            "x2": {
      +              "description": "Right edge, fraction of the source width",
      +              "maximum": 1,
      +              "minimum": 0,
      +              "type": "number"
      +            },
      +            "y1": {
      +              "description": "Top edge, fraction of the source height",
      +              "maximum": 1,
      +              "minimum": 0,
      +              "type": "number"
      +            },
      +            "y2": {
      +              "description": "Bottom edge, fraction of the source height",
      +              "maximum": 1,
      +              "minimum": 0,
      +              "type": "number"
      +            }
      +          },
      +          "required": [
      +            "x1",
      +            "y1",
      +            "x2",
      +            "y2"
      +          ],
      +          "type": "object"
      +        },
      +        "crop": {
      +          "description": "Show exactly this part of the source in the (top / only) pane, as fractions of the source size; replaces the automatic crop, the offset and the subject. A shape unlike the pane's is fitted over a blurred copy",
      +          "properties": {
      +            "x1": {
      +              "description": "Left edge, fraction of the source width",
      +              "maximum": 1,
      +              "minimum": 0,
      +              "type": "number"
      +            },
      +            "x2": {
      +              "description": "Right edge, fraction of the source width",
      +              "maximum": 1,
      +              "minimum": 0,
      +              "type": "number"
      +            },
      +            "y1": {
      +              "description": "Top edge, fraction of the source height",
      +              "maximum": 1,
      +              "minimum": 0,
      +              "type": "number"
      +            },
      +            "y2": {
      +              "description": "Bottom edge, fraction of the source height",
      +              "maximum": 1,
      +              "minimum": 0,
      +              "type": "number"
      +            }
      +          },
      +          "required": [
      +            "x1",
      +            "y1",
      +            "x2",
      +            "y2"
      +          ],
      +          "type": "object"
      +        },
      +        "crop2": {
      +          "description": "Split only: a fixed crop for the bottom pane",
      +          "properties": {
      +            "x1": {
      +              "description": "Left edge, fraction of the source width",
      +              "maximum": 1,
      +              "minimum": 0,
      +              "type": "number"
      +            },
      +            "x2": {
      +              "description": "Right edge, fraction of the source width",
      +              "maximum": 1,
      +              "minimum": 0,
      +              "type": "number"
      +            },
      +            "y1": {
      +              "description": "Top edge, fraction of the source height",
      +              "maximum": 1,
      +              "minimum": 0,
      +              "type": "number"
      +            },
      +            "y2": {
      +              "description": "Bottom edge, fraction of the source height",
      +              "maximum": 1,
      +              "minimum": 0,
      +              "type": "number"
      +            }
      +          },
      +          "required": [
      +            "x1",
      +            "y1",
      +            "x2",
      +            "y2"
      +          ],
      +          "type": "object"
      +        },
      +        "offsetX": {
      +          "description": "Shift the (top) crop sideways by this fraction of the source width (-0.5 to 0.5), relative to the face it follows",
      +          "maximum": 0.5,
      +          "minimum": -0.5,
      +          "type": "number"
      +        },
      +        "offsetX2": {
      +          "description": "Split only: shift the bottom crop sideways (-0.5 to 0.5)",
      +          "maximum": 0.5,
      +          "minimum": -0.5,
      +          "type": "number"
      +        },
      +        "offsetY": {
      +          "description": "Shift the (top) crop up or down by this fraction of the source height; only matters where the crop is shorter than the frame (split, stack)",
      +          "maximum": 0.5,
      +          "minimum": -0.5,
      +          "type": "number"
      +        },
      +        "offsetY2": {
      +          "description": "Split only: shift the bottom crop up or down (-0.5 to 0.5)",
      +          "maximum": 0.5,
      +          "minimum": -0.5,
      +          "type": "number"
      +        },
      +        "subjectX": {
      +          "description": "Follow the person at this x (0-1 of the source width) in the top/only pane; the offset still applies on top",
      +          "maximum": 1,
      +          "minimum": 0,
      +          "type": "number"
      +        },
      +        "subjectX2": {
      +          "description": "Split only: follow the person at this x in the bottom pane",
      +          "maximum": 1,
      +          "minimum": 0,
      +          "type": "number"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Applied with reframe to clips without their own sections: offsetX/Y, offsetX2/Y2, subjectX/X2, crop, crop2, contentCrop as on a clip's section; null = none. apply_framing sets it from one clip"
      +}
  6. Changed3 schema fields changedv0.19.1
    • changedInput schema / properties / introAssetId / description
      Previous value: -"Library asset id (list_bumpers) for the intro of every clip; null = no intro; omitted = your default intro"New value: +"Library asset id (search_assets with source library) for the intro of every clip; null = no intro; omitted = your default intro"
    • changedInput schema / properties / settings / properties / introAssetId / description
      Previous value: -"Library asset id of the intro (list_bumpers); null = none"New value: +"Library asset id of the intro (search_assets with source library); null = none"
    • changedInput schema / properties / settings / properties / outroAssetId / description
      Previous value: -"Library asset id of the outro (list_bumpers); null = none"New value: +"Library asset id of the outro (search_assets with source library); null = none"
  7. Changed5 schema fields changedv0.17.0
    • changedInput schema / properties / settings / description
      Previous value: -"Project settings; omit for the defaults (automatic clip count, 20–60 s clips, natural pauses)."New value: +"Project settings; omit for the defaults (automatic clip count, 20–60 s clips, natural pauses, refine steps off). Set refineEntities / refineDisfluency / disfluencyLlm / refineScenes true to opt into polish (instance Pipeline gates must be on)."
    • addedInput schema / properties / settings / properties / disfluencyLlm
      Added value: +{
      +  "description": "Model pass on top of rule-based disfluency detection. Off by default (rules only when disfluency is on).",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / settings / properties / refineDisfluency
      Added value: +{
      +  "description": "Find fillers, repetitions and false starts. Off by default; on runs that refine step.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / settings / properties / refineEntities
      Added value: +{
      +  "description": "Fix misheard names after transcription (LLM). Off by default; on runs that refine step.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / settings / properties / refineScenes
      Added value: +{
      +  "description": "Detect scene cuts and on-screen text. Off by default; on runs that refine step.",
      +  "type": "boolean"
      +}
  8. Changed33 schema fields changedv0.7.0
    • changedInput schema / properties / introAssetId / description
      Previous value: -"Library asset id for the intro of every clip; null = no intro; omitted = your default intro"New value: +"Library asset id (list_bumpers) for the intro of every clip; null = no intro; omitted = your default intro"
    • changedInput schema / properties / introSec / description
      Previous value: -"Seconds an intro image shows"New value: +"Seconds an intro image shows (1-10)"
    • addedInput schema / properties / outroSec / description
      Added value: +"Seconds an outro image shows (1-10)"
    • addedInput schema / properties / settings / properties / captionPosition / description
      Added value: +"Deprecated: use captionY"
    • addedInput schema / properties / settings / properties / captionSize / description
      Added value: +"Caption size multiplier (0.5-2, default 1)"
    • addedInput schema / properties / settings / properties / captionX / description
      Added value: +"Caption centre, horizontal, as a fraction of the 9:16 frame (0-1)"
    • addedInput schema / properties / settings / properties / captionY / description
      Added value: +"Caption centre, vertical (default 0.72), as a fraction of the 9:16 frame (0-1)"
    • addedInput schema / properties / settings / properties / captions / description
      Added value: +"Caption look: karaoke (active word highlighted), box, plain, or none (no captions)"
    • addedInput schema / properties / settings / properties / emphasis / description
      Added value: +"Colour the clip's key words (default true)"
    • addedInput schema / properties / settings / properties / emphasisColor / description
      Added value: +"Colour of emphasised words, #RRGGBB (default #39FF14)"
    • addedInput schema / properties / settings / properties / focus / description
      Added value: +"Only pick clips about this topic (max 300 chars)"
    • addedInput schema / properties / settings / properties / highlightColor / description
      Added value: +"Karaoke active-word colour, #RRGGBB (default #FFD700)"
    • addedInput schema / properties / settings / properties / hookSeconds / description
      Added value: +"How long the hook shows, seconds (0-15, default 3.5)"
    • addedInput schema / properties / settings / properties / hookX / description
      Added value: +"Hook centre, horizontal, as a fraction of the 9:16 frame (0-1)"
    • addedInput schema / properties / settings / properties / hookY / description
      Added value: +"Hook centre, vertical (default 0.16), as a fraction of the 9:16 frame (0-1)"
    • addedInput schema / properties / settings / properties / instructions / description
      Added value: +"Free-text guidance for picking and titling clips (max 2000 chars)"
    • addedInput schema / properties / settings / properties / introAssetId / description
      Added value: +"Library asset id of the intro (list_bumpers); null = none"
    • addedInput schema / properties / settings / properties / introSec / description
      Added value: +"Seconds an image intro/outro shows (1-10); videos keep their own length"
    • addedInput schema / properties / settings / properties / language / description
      Added value: +"Spoken language code (e.g. en); unset = detected"
    • addedInput schema / properties / settings / properties / maxClipSeconds / description
      Added value: +"Longest clip, seconds (10-300, default 60; must be above minClipSeconds)"
    • addedInput schema / properties / settings / properties / maxClips / description
      Added value: +"Most clips to pick (1-50); unset = every moment that stands on its own"
    • addedInput schema / properties / settings / properties / minClipSeconds / description
      Added value: +"Shortest clip, seconds (5-180, default 20)"
    • addedInput schema / properties / settings / properties / outroAssetId / description
      Added value: +"Library asset id of the outro (list_bumpers); null = none"
    • addedInput schema / properties / settings / properties / outroSec / description
      Added value: +"Seconds an image intro/outro shows (1-10); videos keep their own length"
    • addedInput schema / properties / settings / properties / pauses / description
      Added value: +"Long pauses inside clips: natural (cut to 0.6 s, default), tight (0.35 s) or off"
    • addedInput schema / properties / settings / properties / reframe / description
      Added value: +"Framing: auto (detect per section), face (follow the speaker), split (two speakers stacked), stack (full frame over a face crop), fit (whole frame on blur), center (static crop), none (original aspect)"
    • addedInput schema / properties / settings / properties / showHook / description
      Added value: +"Show the hook text at the start of the clip (default true)"
    • addedInput schema / properties / settings / properties / sourceText / description
      Added value: +"Text already in the video: hide (blur captions/logos except in slide decks, default), always (blur even then), keep"
    • addedInput schema / properties / settings / properties / uppercase / description
      Added value: +"Captions in capitals"
    • addedInput schema / properties / settings / properties / vocabulary / description
      Added value: +"Names, brands and jargon to spell correctly, comma separated (max 1000 chars)"
    • addedInput schema / properties / settings / properties / wordsPerLine / description
      Added value: +"Max caption words on screen at once (1-8, default 4)"
    • addedInput schema / properties / sourceUrl / description
      Added value: +"http(s) URL of the video"
    • addedInput schema / properties / title / description
      Added value: +"Project title (default: the video's own title)"
  9. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations at all, the description carries the full behavioral burden and does so well: it discloses that the call returns immediately with { id, title, status: 'queued', next }, that processing takes minutes in the background, and that intro/outro fall back to library defaults unless overridden. It does not mention authorization scope, plan/quota gates, or what happens on an unsupported URL, so it falls short of full disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact sentences, front-loaded with the resource and source options, then the return contract, then the next step. It is information-dense and almost every clause earns its place, though the parenthetical pipeline enumeration and the upload recipe make it longer than strictly necessary for a first scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-annotation, no-output-schema tool with a deep nested settings object, the description supplies the critical missing pieces: the immediate return shape, the asynchronous lifecycle, and the required follow-up call. It stops short of covering failure modes or permission/quota constraints, which leaves a small gap for a high-complexity creation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description still earns a bump by adding out-of-schema meaning to uploadId (the POST /api/upload body, x-filename header, Bearer auth) and by stating the default-inheritance behavior for introAssetId/outroAssetId. The remaining eight top-level parameters, notably the large nested settings object, get no description-level guidance beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource plus scope: 'Start clipping a video from a URL (anything yt-dlp fetches) or a file you uploaded.' It explains what a 'project' actually is (a background download/transcribe/pick/render pipeline), which no sibling name alone conveys, and it names wait_for_project as the follow-up rather than leaving the agent to guess.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly states the two mutually exclusive input routes (sourceUrl vs uploadId) with the exact HTTP steps to obtain an uploadId, and it explicitly tells the agent to follow with wait_for_project(id) because the pipeline runs in the background. It does not state when *not* to use it (e.g. adding clips to an existing project via create_clip), but the entry-point role is unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.