@cliptude/cli 0.1.10 → 0.1.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -1
- package/cliptude_mcp/cli.py +34 -7
- package/cliptude_mcp/client.py +48 -1
- package/cliptude_mcp/server.py +176 -51
- package/npm/bin/cliptude.js +39 -20
- package/package.json +1 -1
- package/pyproject.toml +1 -1
package/README.md
CHANGED
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
Generate videos from a saved template. Same account and credits as cliptude.com.
|
|
4
4
|
|
|
5
|
+
> Also from Cliptude: [Awesome Faceless YouTube Automation](https://github.com/cliptude/awesome-faceless-youtube-automation), a curated list of tools, footage sources and YouTube policies for faceless channels.
|
|
6
|
+
|
|
5
7
|
## Set up
|
|
6
8
|
|
|
7
9
|
1. Install the CLI: run `npm i -g @cliptude/cli`.
|
|
@@ -41,7 +43,7 @@ cliptude continue <job-id>
|
|
|
41
43
|
cliptude status <job-id>
|
|
42
44
|
```
|
|
43
45
|
|
|
44
|
-
No template yet? `template-create` makes one without the create wizard: pick a `voice_id` from `voices`, and see `template-options` for every other field, its choices and its default (unset fields take the wizard default). Values are validated like the wizard; uploads (custom music, avatars, characters) still need the wizard. MCP tools: `get_template_options`, `list_voices`, `create_template`. For Avatar Video, `avatars` (MCP `list_avatars`) lists your avatars; set one with `--set avatar_profile_id=<id>` on `template-create`, or override it per video with `--avatar <id>` (and `--avatar-engine
|
|
46
|
+
No template yet? `template-create` makes one without the create wizard: pick a `voice_id` from `voices`, and see `template-options` for every other field, its choices and its default (unset fields take the wizard default). Values are validated like the wizard; uploads (custom music, avatars, characters) still need the wizard. MCP tools: `get_template_options`, `list_voices`, `create_template`. For Avatar Video, `avatars` (MCP `list_avatars`) lists your avatars; set one with `--set avatar_profile_id=<id>` on `template-create`, or override it per video with `--avatar <id>` (and `--avatar-engine iv|v`) on `generate`, `plan-job` and `estimate`. The avatar's gender must match the voice. For Vector Explainer, `vector-characters` lists the built-in cast and your uploads, `vector-character-upload --name "Dr. Maya" --file maya.png` (or `--url`) adds your own, and `--set vector_character_id=<id>` on `template-create` (or `--vector-character <id>` on `generate` / `plan-job`) uses it. Motion: `--set vector_reveal_mode=none|video` on the template, or `--vector-motion none|video` on `generate`, `plan-job` and `estimate` (`none` = stills with camera moves, `video` = AI clips). Thumbnails: `--thumbnail-reference <YouTube link or image URL>` or `--thumbnail-prompt "<brief>"` on `template-create` sets the template's look; the same flags on `generate` and `plan-job` set one video's. With neither, each video picks a style reference for its own title.
|
|
45
47
|
|
|
46
48
|
To check the price first, `estimate` (MCP `estimate_credits`, REST `POST /api/v1/jobs/estimate`) takes the same template and prompt/script as `generate` (an upload as `--voiceover-seconds` / `--talking-head-seconds`) and returns the credits the job would need and whether the account has them. It creates and charges nothing.
|
|
47
49
|
|
package/cliptude_mcp/cli.py
CHANGED
|
@@ -51,6 +51,29 @@ def _add_thumbnail_args(parser: argparse.ArgumentParser, *, scope: str) -> None:
|
|
|
51
51
|
)
|
|
52
52
|
|
|
53
53
|
|
|
54
|
+
def _add_pronunciations_arg(parser: argparse.ArgumentParser) -> None:
|
|
55
|
+
parser.add_argument(
|
|
56
|
+
"--pronunciations",
|
|
57
|
+
default="",
|
|
58
|
+
metavar="FILE",
|
|
59
|
+
help='JSON file: a list of {"word": "Gmay", "alias": "guh-MAY"} or {"word", "phoneme", "alphabet": "ipa"} '
|
|
60
|
+
"(ElevenLabs voices). Replaces the template's list for this video.",
|
|
61
|
+
)
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def _pronunciations_from_args(args) -> list | None:
|
|
65
|
+
path = (getattr(args, "pronunciations", "") or "").strip()
|
|
66
|
+
if not path:
|
|
67
|
+
return None
|
|
68
|
+
try:
|
|
69
|
+
rules = json.loads(Path(path).read_text(encoding="utf-8"))
|
|
70
|
+
except (OSError, ValueError) as exc:
|
|
71
|
+
raise CliptudeApiError(f"--pronunciations: could not read {path}: {exc}") from exc
|
|
72
|
+
if not isinstance(rules, list):
|
|
73
|
+
raise CliptudeApiError("--pronunciations must be a JSON list of rules.")
|
|
74
|
+
return rules
|
|
75
|
+
|
|
76
|
+
|
|
54
77
|
def _thumbnail_from_args(args) -> dict | None:
|
|
55
78
|
thumbnail = {
|
|
56
79
|
key: value.strip()
|
|
@@ -214,7 +237,7 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
214
237
|
est.add_argument("--avatar-intro-only", action=argparse.BooleanOptionalAction, default=None)
|
|
215
238
|
est.add_argument("--avatar-ai-footage", action=argparse.BooleanOptionalAction, default=None)
|
|
216
239
|
est.add_argument("--avatar", type=int, default=None, help="Avatar Video: avatar id from `cliptude avatars`. Default: the template's avatar")
|
|
217
|
-
est.add_argument("--avatar-engine", default="", choices=["", "
|
|
240
|
+
est.add_argument("--avatar-engine", default="", choices=["", "iv", "v"], help="Avatar Video: HeyGen engine. Default: the template's")
|
|
218
241
|
est.add_argument("--vector-motion", default="", choices=["", "none", "video"], help="Vector Explainer: price stills (none) or AI clips (video)")
|
|
219
242
|
est.add_argument("--render-only", action="store_true", help="Plan job where you bring the voiceover, pictures, clips and graphics (with --output plan --voiceover-seconds)")
|
|
220
243
|
|
|
@@ -247,13 +270,13 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
247
270
|
g.add_argument(
|
|
248
271
|
"--voiceover",
|
|
249
272
|
default="",
|
|
250
|
-
help="Path to a narration audio file (MP3, M4A, WAV, …). Transcribed; skips TTS. Do not combine with --prompt or --script.",
|
|
273
|
+
help="Path to a narration audio file (MP3, M4A, WAV, …), at least 6 minutes long. Transcribed; skips TTS. Do not combine with --prompt or --script.",
|
|
251
274
|
)
|
|
252
|
-
g.add_argument("--voiceover-url", default="", help="Public https link to the narration audio; Cliptude downloads it.")
|
|
275
|
+
g.add_argument("--voiceover-url", default="", help="Public https link to the narration audio (at least 6 minutes long); Cliptude downloads it.")
|
|
253
276
|
g.add_argument(
|
|
254
277
|
"--talking-head",
|
|
255
278
|
default="",
|
|
256
|
-
help="Path to a talking-head presenter video (MP4, MOV, WEBM, AVI). Requires a Talking Head template. Transcribed; skips TTS. Do not combine with --prompt, --script, or --voiceover.",
|
|
279
|
+
help="Path to a talking-head presenter video (MP4, MOV, WEBM, AVI), at least 6 minutes long. Requires a Talking Head template. Transcribed; skips TTS. Do not combine with --prompt, --script, or --voiceover.",
|
|
257
280
|
)
|
|
258
281
|
g.add_argument(
|
|
259
282
|
"--duration",
|
|
@@ -279,7 +302,7 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
279
302
|
),
|
|
280
303
|
)
|
|
281
304
|
g.add_argument("--avatar", type=int, default=None, help="Avatar Video: avatar id from `cliptude avatars`. Default: the template's avatar")
|
|
282
|
-
g.add_argument("--avatar-engine", default="", choices=["", "
|
|
305
|
+
g.add_argument("--avatar-engine", default="", choices=["", "iv", "v"], help="Avatar Video: HeyGen engine. Default: the template's")
|
|
283
306
|
g.add_argument(
|
|
284
307
|
"--disable-animations",
|
|
285
308
|
action=argparse.BooleanOptionalAction,
|
|
@@ -321,6 +344,7 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
321
344
|
help="Exclude a transition (e.g. flip-horizontal) from auto-selection. Repeatable. Omit to use the template.",
|
|
322
345
|
)
|
|
323
346
|
_add_thumbnail_args(g, scope="this video")
|
|
347
|
+
_add_pronunciations_arg(g)
|
|
324
348
|
g.add_argument("--vector-motion", default="", choices=["", "none", "video"], help='Vector Explainer: "none" = stills with camera moves, "video" = AI clips. Default: the template\'s')
|
|
325
349
|
g.add_argument("--vector-character", default="", help='Vector Explainer: character id from `cliptude vector-characters`, or "none". Default: the template\'s')
|
|
326
350
|
|
|
@@ -356,7 +380,7 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
356
380
|
vo.add_argument("--script-file", default="")
|
|
357
381
|
vo.add_argument("--duration", default="", help="Wizard duration bucket, e.g. 3-4 or 6-8")
|
|
358
382
|
|
|
359
|
-
dv = sub.add_parser("download-voiceover", help="Download voiceover MP3
|
|
383
|
+
dv = sub.add_parser("download-voiceover", help="Download the voiceover MP3 of a voiceover job, or the narration of a plan_ready plan job")
|
|
360
384
|
dv.add_argument("job_id")
|
|
361
385
|
dv.add_argument("--out", default="voiceover.mp3")
|
|
362
386
|
|
|
@@ -394,9 +418,10 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
394
418
|
pj.add_argument("--voiceover-url", default="", help="Public https link to the narration audio; Cliptude downloads it")
|
|
395
419
|
pj.add_argument("--duration", default="", help="Wizard duration bucket, e.g. 6-8")
|
|
396
420
|
pj.add_argument("--avatar", type=int, default=None, help="Avatar Video: avatar id from `cliptude avatars`. Default: the template's avatar")
|
|
397
|
-
pj.add_argument("--avatar-engine", default="", choices=["", "
|
|
421
|
+
pj.add_argument("--avatar-engine", default="", choices=["", "iv", "v"], help="Avatar Video: HeyGen engine. Default: the template's")
|
|
398
422
|
pj.add_argument("--render-only", action="store_true", help="You bring everything (needs --voiceover); Cliptude only builds and renders, at the render-only rate")
|
|
399
423
|
_add_thumbnail_args(pj, scope="this video")
|
|
424
|
+
_add_pronunciations_arg(pj)
|
|
400
425
|
pj.add_argument("--vector-motion", default="", choices=["", "none", "video"], help='Vector Explainer: "none" = stills with camera moves, "video" = AI clips. Default: the template\'s')
|
|
401
426
|
pj.add_argument("--vector-character", default="", help='Vector Explainer: character id from `cliptude vector-characters`, or "none". Default: the template\'s')
|
|
402
427
|
|
|
@@ -578,6 +603,7 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
578
603
|
thumbnail=_thumbnail_from_args(args),
|
|
579
604
|
vector_character_id=args.vector_character or None,
|
|
580
605
|
vector_reveal_mode=args.vector_motion or None,
|
|
606
|
+
pronunciations=_pronunciations_from_args(args),
|
|
581
607
|
))
|
|
582
608
|
elif args.cmd == "script":
|
|
583
609
|
if not (args.prompt or "").strip():
|
|
@@ -629,6 +655,7 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
629
655
|
thumbnail=_thumbnail_from_args(args),
|
|
630
656
|
vector_character_id=args.vector_character or None,
|
|
631
657
|
vector_reveal_mode=args.vector_motion or None,
|
|
658
|
+
pronunciations=_pronunciations_from_args(args),
|
|
632
659
|
))
|
|
633
660
|
elif args.cmd == "narration":
|
|
634
661
|
_print(client.get_narration(args.job_id))
|
package/cliptude_mcp/client.py
CHANGED
|
@@ -308,6 +308,7 @@ class CliptudeClient:
|
|
|
308
308
|
thumbnail: dict[str, str] | None = None,
|
|
309
309
|
vector_character_id: str | None = None,
|
|
310
310
|
vector_reveal_mode: str | None = None,
|
|
311
|
+
pronunciations: list[dict[str, str]] | None = None,
|
|
311
312
|
) -> Any:
|
|
312
313
|
if voiceover_path and voiceover_url:
|
|
313
314
|
raise CliptudeApiError("Give voiceover_path or voiceover_url, not both.")
|
|
@@ -381,6 +382,7 @@ class CliptudeClient:
|
|
|
381
382
|
**_thumbnail_job_field(thumbnail, as_string=True),
|
|
382
383
|
**({"vector_character_id": str(vector_character_id)} if vector_character_id else {}),
|
|
383
384
|
**({"vector_reveal_mode": str(vector_reveal_mode)} if vector_reveal_mode else {}),
|
|
385
|
+
**({"pronunciations": json.dumps(pronunciations)} if pronunciations is not None else {}),
|
|
384
386
|
}
|
|
385
387
|
return self._create_job_multipart(
|
|
386
388
|
template_id=template_id,
|
|
@@ -415,6 +417,8 @@ class CliptudeClient:
|
|
|
415
417
|
body["vector_character_id"] = str(vector_character_id)
|
|
416
418
|
if vector_reveal_mode:
|
|
417
419
|
body["vector_reveal_mode"] = str(vector_reveal_mode)
|
|
420
|
+
if pronunciations is not None:
|
|
421
|
+
body["pronunciations"] = pronunciations
|
|
418
422
|
return self.request("POST", "/api/v1/jobs", json_body=body)
|
|
419
423
|
|
|
420
424
|
def _raise_http(self, resp, *, payload=None) -> None:
|
|
@@ -675,6 +679,49 @@ class CliptudeClient:
|
|
|
675
679
|
pass
|
|
676
680
|
raise
|
|
677
681
|
|
|
682
|
+
def _start_signed_upload(self, base: str, *, filename: str, size: int, content_type: str | None) -> dict[str, Any]:
|
|
683
|
+
"""Open a multipart upload and sign every part: [{part, offset, length, url}] for the caller to PUT."""
|
|
684
|
+
if int(size or 0) <= 0:
|
|
685
|
+
raise CliptudeApiError("size (the file size in bytes) is required.")
|
|
686
|
+
ctype = content_type or mimetypes.guess_type(filename)[0] or "application/octet-stream"
|
|
687
|
+
init = self.request("POST", f"{base}/init", json_body={"filename": filename, "size": int(size), "content_type": ctype})
|
|
688
|
+
key, upload_id = str((init or {}).get("key") or ""), str((init or {}).get("upload_id") or "")
|
|
689
|
+
part_size, part_count = int((init or {}).get("part_size") or 0), int((init or {}).get("part_count") or 0)
|
|
690
|
+
if not key or not upload_id or part_size <= 0 or part_count <= 0:
|
|
691
|
+
raise CliptudeApiError("The upload init returned an incomplete plan.")
|
|
692
|
+
parts: list[dict[str, Any]] = []
|
|
693
|
+
for start in range(0, part_count, 50):
|
|
694
|
+
nums = list(range(start + 1, min(start + 50, part_count) + 1))
|
|
695
|
+
signed = self.request("POST", f"{base}/sign-parts", json_body={"key": key, "upload_id": upload_id, "part_numbers": nums})
|
|
696
|
+
urls = (signed or {}).get("urls") if isinstance(signed, dict) else None
|
|
697
|
+
if not isinstance(urls, dict):
|
|
698
|
+
raise CliptudeApiError("Could not sign the upload parts.")
|
|
699
|
+
for num in nums:
|
|
700
|
+
offset = (num - 1) * part_size
|
|
701
|
+
parts.append({"part": num, "offset": offset, "length": min(part_size, int(size) - offset), "url": urls.get(str(num))})
|
|
702
|
+
return {"key": key, "upload_id": upload_id, "part_size": part_size, "part_count": part_count, "size": int(size), "parts": parts}
|
|
703
|
+
|
|
704
|
+
def start_media_upload(self, job_id: str, *, filename: str, size: int, content_type: str | None = None) -> dict[str, Any]:
|
|
705
|
+
"""Signed PUT URLs for a picture or clip of a plan job, for a host that sends the bytes itself."""
|
|
706
|
+
return self._start_signed_upload(f"/api/v1/jobs/{job_id}/media", filename=filename, size=size, content_type=content_type)
|
|
707
|
+
|
|
708
|
+
def finish_media_upload(self, job_id: str, *, key: str, upload_id: str) -> Any:
|
|
709
|
+
return self.request("POST", f"/api/v1/jobs/{job_id}/media/complete", json_body={"key": key, "upload_id": upload_id})
|
|
710
|
+
|
|
711
|
+
def abort_media_upload(self, job_id: str, *, key: str, upload_id: str) -> Any:
|
|
712
|
+
return self.request("POST", f"/api/v1/jobs/{job_id}/media/abort", json_body={"key": key, "upload_id": upload_id})
|
|
713
|
+
|
|
714
|
+
def start_voiceover_upload(self, *, filename: str, size: int, content_type: str | None = None) -> dict[str, Any]:
|
|
715
|
+
"""Signed PUT URLs for a narration file, before the job exists."""
|
|
716
|
+
return self._start_signed_upload("/api/v1/uploads/voiceover", filename=filename, size=size, content_type=content_type)
|
|
717
|
+
|
|
718
|
+
def finish_voiceover_upload(self, *, key: str, upload_id: str) -> Any:
|
|
719
|
+
"""Returns {voiceover_url, key, expires_in_s}: pass voiceover_url to create_job / create_plan_job."""
|
|
720
|
+
return self.request("POST", "/api/v1/uploads/voiceover/complete", json_body={"key": key, "upload_id": upload_id})
|
|
721
|
+
|
|
722
|
+
def abort_voiceover_upload(self, *, key: str, upload_id: str) -> Any:
|
|
723
|
+
return self.request("POST", "/api/v1/uploads/voiceover/abort", json_body={"key": key, "upload_id": upload_id})
|
|
724
|
+
|
|
678
725
|
def get_narration(self, job_id: str) -> Any:
|
|
679
726
|
"""Numbered sentences (with word timings), digest, pricing and template flags of a plan job."""
|
|
680
727
|
return self.request("GET", f"/api/v1/jobs/{job_id}/narration")
|
|
@@ -810,7 +857,7 @@ class CliptudeClient:
|
|
|
810
857
|
return self.request("POST", f"/api/v1/editor-projects/{project_id}/agent/runs/{run_id}/cancel")
|
|
811
858
|
|
|
812
859
|
def render_project(self, project_id: int | str) -> Any:
|
|
813
|
-
"""Render the edited timeline to a new MP4
|
|
860
|
+
"""Render the edited timeline to a new MP4: free the first time, then 10% of the original generation."""
|
|
814
861
|
return self.request("POST", f"/api/v1/editor-projects/{project_id}/render")
|
|
815
862
|
|
|
816
863
|
def get_render(self, render_id: int | str) -> Any:
|
package/cliptude_mcp/server.py
CHANGED
|
@@ -103,8 +103,8 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
103
103
|
"(no suitable template? get_template_options + list_voices, then create_template) "
|
|
104
104
|
"To revise a finished video: open_editor_project, run_agent with timeline item ids, "
|
|
105
105
|
"poll get_agent_run, then render_project and get_render. "
|
|
106
|
-
"prompt, script, voiceover_path (uploaded audio, transcribed; skips TTS), "
|
|
107
|
-
"or talking_head_path (presenter video on a Talking Head template). "
|
|
106
|
+
"prompt, script, voiceover_path (uploaded audio of at least 6 minutes, transcribed; skips TTS), "
|
|
107
|
+
"or talking_head_path (presenter video of at least 6 minutes on a Talking Head template). "
|
|
108
108
|
"create_job returns immediately; poll get_job until completed or failed. "
|
|
109
109
|
"To quote a price or check the balance first, call estimate_credits with the same "
|
|
110
110
|
"template and prompt/script (an upload as voiceover_seconds); it creates nothing. "
|
|
@@ -139,7 +139,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
139
139
|
|
|
140
140
|
@mcp.tool(
|
|
141
141
|
title="List templates",
|
|
142
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
142
|
+
annotations=ToolAnnotations(title="List templates", read_only_hint=True, open_world_hint=False),
|
|
143
143
|
)
|
|
144
144
|
def list_templates(
|
|
145
145
|
limit: Annotated[int, Field(ge=1, le=100, description="Page size")] = 20,
|
|
@@ -153,7 +153,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
153
153
|
|
|
154
154
|
@mcp.tool(
|
|
155
155
|
title="Get template",
|
|
156
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
156
|
+
annotations=ToolAnnotations(title="Get template", read_only_hint=True, open_world_hint=False),
|
|
157
157
|
)
|
|
158
158
|
def get_template(
|
|
159
159
|
template_id: Annotated[str, Field(min_length=8, description="Template UUID")],
|
|
@@ -166,7 +166,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
166
166
|
|
|
167
167
|
@mcp.tool(
|
|
168
168
|
title="Get template options",
|
|
169
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
169
|
+
annotations=ToolAnnotations(title="Get template options", read_only_hint=True, open_world_hint=False),
|
|
170
170
|
)
|
|
171
171
|
def get_template_options(
|
|
172
172
|
format: Annotated[str, Field(description="Video format, e.g. faceless_documentary or vector_explainer")],
|
|
@@ -179,7 +179,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
179
179
|
|
|
180
180
|
@mcp.tool(
|
|
181
181
|
title="List voices",
|
|
182
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=True),
|
|
182
|
+
annotations=ToolAnnotations(title="List voices", read_only_hint=True, open_world_hint=True),
|
|
183
183
|
)
|
|
184
184
|
def list_voices(
|
|
185
185
|
provider: Annotated[str, Field(description="elevenlabs, minimax, cartesia, inworld or voicetory")] = "elevenlabs",
|
|
@@ -191,7 +191,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
191
191
|
except Exception as exc:
|
|
192
192
|
return _err(exc)
|
|
193
193
|
|
|
194
|
-
@mcp.tool(
|
|
194
|
+
@mcp.tool(
|
|
195
|
+
title="Create template",
|
|
196
|
+
annotations=ToolAnnotations(title="Create template", read_only_hint=False, destructive_hint=False),
|
|
197
|
+
)
|
|
195
198
|
def create_template(
|
|
196
199
|
name: Annotated[str, Field(min_length=1, max_length=120, description="Template name")],
|
|
197
200
|
format: Annotated[str, Field(description="Video format, e.g. faceless_documentary")],
|
|
@@ -219,7 +222,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
219
222
|
|
|
220
223
|
@mcp.tool(
|
|
221
224
|
title="Estimate credits",
|
|
222
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
225
|
+
annotations=ToolAnnotations(title="Estimate credits", read_only_hint=True, open_world_hint=False),
|
|
223
226
|
)
|
|
224
227
|
def estimate_credits(
|
|
225
228
|
template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
|
|
@@ -249,11 +252,11 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
249
252
|
] = None,
|
|
250
253
|
avatar_engine: Annotated[
|
|
251
254
|
str | None,
|
|
252
|
-
Field(description='Avatar Video only: "
|
|
255
|
+
Field(description='Avatar Video only: "iv" or "v" (list_avatars shows which each avatar supports; Avatar III is not offered). Omit to keep the template.'),
|
|
253
256
|
] = None,
|
|
254
257
|
render_only: Annotated[
|
|
255
258
|
bool | None,
|
|
256
|
-
Field(description="Render-only plan job: you bring the voiceover (voiceover_path, or voiceover_url on a remote host), every picture and clip (url, or keep from upload_plan_media) and the graphics; Cliptude searches, writes, voices and generates nothing and charges only the render-only rate per minute."),
|
|
259
|
+
Field(description="Render-only plan job: you bring the voiceover (voiceover_path, or voiceover_url: on a remote host from start_voiceover_upload), every picture and clip (url, or keep from upload_plan_media / start_media_upload) and the graphics; Cliptude searches, writes, voices and generates nothing and charges only the render-only rate per minute."),
|
|
257
260
|
] = None,
|
|
258
261
|
vector_reveal_mode: Annotated[
|
|
259
262
|
str | None,
|
|
@@ -287,7 +290,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
287
290
|
|
|
288
291
|
@mcp.tool(
|
|
289
292
|
title="List avatars",
|
|
290
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
293
|
+
annotations=ToolAnnotations(title="List avatars", read_only_hint=True, open_world_hint=False),
|
|
291
294
|
)
|
|
292
295
|
def list_avatars(
|
|
293
296
|
section: Annotated[
|
|
@@ -307,7 +310,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
307
310
|
|
|
308
311
|
@mcp.tool(
|
|
309
312
|
title="List vector characters",
|
|
310
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
313
|
+
annotations=ToolAnnotations(title="List vector characters", read_only_hint=True, open_world_hint=False),
|
|
311
314
|
)
|
|
312
315
|
def list_vector_characters() -> dict[str, Any]:
|
|
313
316
|
"""Characters for Vector Explainer videos: the built-in cast (id, name, descriptor, description, preview_url) and the user's own uploads (id, name, preview_url). Pass an id as vector_character_id in create_template settings, or on create_job / create_plan_job for one video. Also returns upload_guidance for making a new one."""
|
|
@@ -316,7 +319,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
316
319
|
except Exception as exc:
|
|
317
320
|
return _err(exc)
|
|
318
321
|
|
|
319
|
-
@mcp.tool(
|
|
322
|
+
@mcp.tool(
|
|
323
|
+
title="Upload vector character",
|
|
324
|
+
annotations=ToolAnnotations(title="Upload vector character", read_only_hint=False, destructive_hint=False),
|
|
325
|
+
)
|
|
320
326
|
def upload_vector_character(
|
|
321
327
|
name: Annotated[str, Field(min_length=1, max_length=120, description="A short name for the character, e.g. 'Dr. Maya'")],
|
|
322
328
|
image_path: Annotated[str | None, Field(description="Local PNG, JPG or WEBP file. Stdio / local MCP only.")] = None,
|
|
@@ -332,7 +338,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
332
338
|
except Exception as exc:
|
|
333
339
|
return _err(exc)
|
|
334
340
|
|
|
335
|
-
@mcp.tool(
|
|
341
|
+
@mcp.tool(
|
|
342
|
+
title="Delete vector character",
|
|
343
|
+
annotations=ToolAnnotations(title="Delete vector character", read_only_hint=False, destructive_hint=True),
|
|
344
|
+
)
|
|
336
345
|
def delete_vector_character(
|
|
337
346
|
character_id: Annotated[str, Field(min_length=8, description="Uploaded character id from list_vector_characters")],
|
|
338
347
|
) -> dict[str, Any]:
|
|
@@ -342,7 +351,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
342
351
|
except Exception as exc:
|
|
343
352
|
return _err(exc)
|
|
344
353
|
|
|
345
|
-
@mcp.tool(
|
|
354
|
+
@mcp.tool(
|
|
355
|
+
title="Create video job",
|
|
356
|
+
annotations=ToolAnnotations(title="Create video job", read_only_hint=False, destructive_hint=False),
|
|
357
|
+
)
|
|
346
358
|
def create_job(
|
|
347
359
|
template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
|
|
348
360
|
title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
|
|
@@ -362,7 +374,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
362
374
|
str | None,
|
|
363
375
|
Field(
|
|
364
376
|
description=(
|
|
365
|
-
"Local path to a talking-head presenter video (MP4, MOV, WEBM, AVI). "
|
|
377
|
+
"Local path to a talking-head presenter video (MP4, MOV, WEBM, AVI), at least 6 minutes long. "
|
|
366
378
|
"Requires a Talking Head template. Cliptude transcribes it and skips TTS. "
|
|
367
379
|
"Do not also send prompt, script, or voiceover_path. "
|
|
368
380
|
"Stdio / local MCP only — remote hosts should use the CLI."
|
|
@@ -397,7 +409,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
397
409
|
] = None,
|
|
398
410
|
avatar_engine: Annotated[
|
|
399
411
|
str | None,
|
|
400
|
-
Field(description='Avatar Video only: "
|
|
412
|
+
Field(description='Avatar Video only: "iv" or "v" (list_avatars shows which each avatar supports; Avatar III is not offered). Omit to keep the template.'),
|
|
401
413
|
] = None,
|
|
402
414
|
disable_animations: Annotated[
|
|
403
415
|
bool | None,
|
|
@@ -425,7 +437,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
425
437
|
] = None,
|
|
426
438
|
voiceover_url: Annotated[
|
|
427
439
|
str | None,
|
|
428
|
-
Field(description="Public https link to the narration audio (MP3, M4A, WAV, OGG, FLAC, WEBM; up to 200 MB). Cliptude downloads it and uses it like an uploaded voiceover.
|
|
440
|
+
Field(description="Public https link to the narration audio (MP3, M4A, WAV, OGG, FLAC, WEBM; up to 200 MB; at least 6 minutes long). Cliptude downloads it and uses it like an uploaded voiceover. On a remote host, upload a local file with start_voiceover_upload + finish_voiceover_upload and pass the voiceover_url it returns. Omit prompt/script and voiceover_path."),
|
|
429
441
|
] = None,
|
|
430
442
|
thumbnail_prompt: Annotated[
|
|
431
443
|
str | None,
|
|
@@ -443,6 +455,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
443
455
|
str | None,
|
|
444
456
|
Field(description='Vector Explainer only: "none" = drawn stills with camera moves (Ken Burns), "video" = every picture beat animated as an AI clip (costs more; check estimate_credits). Omit to use the template\'s.'),
|
|
445
457
|
] = None,
|
|
458
|
+
pronunciations: Annotated[
|
|
459
|
+
list[dict[str, str]] | None,
|
|
460
|
+
Field(description='How the voice says hard words (ElevenLabs voices): [{"word": "Gmay", "alias": "guh-MAY"}] or [{"word": "Ordnung", "phoneme": "ˈɔɹt.nʊŋ", "alphabet": "ipa"}]. Script, captions and searches keep the real spelling. Replaces the template\'s list for this video; omit to keep it.'),
|
|
461
|
+
] = None,
|
|
446
462
|
) -> dict[str, Any]:
|
|
447
463
|
"""Start generation and return a job id immediately. Do not wait for the MP4. Poll get_job. Provide prompt, script, voiceover_path, or talking_head_path. Never copy the title into prompt; for a topic-only request write a spoken script after web search and pass script. Uploaded audio or talking-head video is transcribed. Avatar Video: optional avatar_intro_only and avatar_ai_footage override the template. Any format: optional disable_animations/disable_overlays/disable_effects/disable_transitions and excluded_animation_types/excluded_transition_kinds override the template's motion & effects settings."""
|
|
448
464
|
try:
|
|
@@ -483,11 +499,15 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
483
499
|
thumbnail=_thumbnail_arg(thumbnail_prompt, thumbnail_reference_url),
|
|
484
500
|
vector_character_id=vector_character_id,
|
|
485
501
|
vector_reveal_mode=vector_reveal_mode,
|
|
502
|
+
pronunciations=pronunciations,
|
|
486
503
|
)
|
|
487
504
|
except Exception as exc:
|
|
488
505
|
return _err(exc)
|
|
489
506
|
|
|
490
|
-
@mcp.tool(
|
|
507
|
+
@mcp.tool(
|
|
508
|
+
title="Create script job",
|
|
509
|
+
annotations=ToolAnnotations(title="Create script job", read_only_hint=False, destructive_hint=False),
|
|
510
|
+
)
|
|
491
511
|
def create_script(
|
|
492
512
|
template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
|
|
493
513
|
title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
|
|
@@ -509,7 +529,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
509
529
|
except Exception as exc:
|
|
510
530
|
return _err(exc)
|
|
511
531
|
|
|
512
|
-
@mcp.tool(
|
|
532
|
+
@mcp.tool(
|
|
533
|
+
title="Create voiceover job",
|
|
534
|
+
annotations=ToolAnnotations(title="Create voiceover job", read_only_hint=False, destructive_hint=False),
|
|
535
|
+
)
|
|
513
536
|
def create_voiceover(
|
|
514
537
|
template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
|
|
515
538
|
title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
|
|
@@ -535,7 +558,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
535
558
|
except Exception as exc:
|
|
536
559
|
return _err(exc)
|
|
537
560
|
|
|
538
|
-
@mcp.tool(
|
|
561
|
+
@mcp.tool(
|
|
562
|
+
title="Continue job into video",
|
|
563
|
+
annotations=ToolAnnotations(title="Continue job into video", read_only_hint=False, destructive_hint=False),
|
|
564
|
+
)
|
|
539
565
|
def continue_job(
|
|
540
566
|
job_id: Annotated[str, Field(min_length=8, description="Completed script or voiceover job UUID, or a plan job with a locked plan")],
|
|
541
567
|
) -> dict[str, Any]:
|
|
@@ -545,16 +571,19 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
545
571
|
except Exception as exc:
|
|
546
572
|
return _err(exc)
|
|
547
573
|
|
|
548
|
-
@mcp.tool(
|
|
574
|
+
@mcp.tool(
|
|
575
|
+
title="Create agent-planned job",
|
|
576
|
+
annotations=ToolAnnotations(title="Create agent-planned job", read_only_hint=False, destructive_hint=False),
|
|
577
|
+
)
|
|
549
578
|
def create_plan_job(
|
|
550
579
|
template_id: Annotated[str, Field(min_length=8, description="Saved Faceless Documentary, Faceless Top 10, Avatar Video or Vector Explainer template UUID")],
|
|
551
580
|
title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
|
|
552
581
|
prompt: Annotated[str | None, Field(description="Topic/brief; Cliptude writes the narration. Never the video title.")] = None,
|
|
553
582
|
script: Annotated[str | None, Field(description="Spoken narration to voice as-is. Omit prompt when you pass this.")] = None,
|
|
554
|
-
voiceover_path: Annotated[str | None, Field(description="Local audio file to use as the narration (aligned, not re-voiced). Omit prompt/script. Stdio / local MCP only.")] = None,
|
|
583
|
+
voiceover_path: Annotated[str | None, Field(description="Local audio file to use as the narration (aligned, not re-voiced), at least 6 minutes long. Omit prompt/script. Stdio / local MCP only.")] = None,
|
|
555
584
|
voiceover_url: Annotated[
|
|
556
585
|
str | None,
|
|
557
|
-
Field(description="Public https link to the narration audio (MP3, M4A, WAV, OGG, FLAC, WEBM; up to 200 MB). Cliptude downloads it and uses it like an uploaded voiceover.
|
|
586
|
+
Field(description="Public https link to the narration audio (MP3, M4A, WAV, OGG, FLAC, WEBM; up to 200 MB; at least 6 minutes long). Cliptude downloads it and uses it like an uploaded voiceover. On a remote host, upload a local file with start_voiceover_upload + finish_voiceover_upload and pass the voiceover_url it returns. Omit prompt/script and voiceover_path."),
|
|
558
587
|
] = None,
|
|
559
588
|
duration: Annotated[str | None, Field(description="Duration bucket such as 6-8. Omit to use the template.")] = None,
|
|
560
589
|
avatar_profile_id: Annotated[
|
|
@@ -563,11 +592,11 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
563
592
|
] = None,
|
|
564
593
|
avatar_engine: Annotated[
|
|
565
594
|
str | None,
|
|
566
|
-
Field(description='Avatar Video only: "
|
|
595
|
+
Field(description='Avatar Video only: "iv" or "v" (list_avatars shows which each avatar supports; Avatar III is not offered). Omit to keep the template.'),
|
|
567
596
|
] = None,
|
|
568
597
|
render_only: Annotated[
|
|
569
598
|
bool | None,
|
|
570
|
-
Field(description="Render-only plan job: you bring the voiceover (voiceover_path, or voiceover_url on a remote host), every picture and clip (url, or keep from upload_plan_media) and the graphics; Cliptude searches, writes, voices and generates nothing and charges only the render-only rate per minute."),
|
|
599
|
+
Field(description="Render-only plan job: you bring the voiceover (voiceover_path, or voiceover_url: on a remote host from start_voiceover_upload), every picture and clip (url, or keep from upload_plan_media / start_media_upload) and the graphics; Cliptude searches, writes, voices and generates nothing and charges only the render-only rate per minute."),
|
|
571
600
|
] = None,
|
|
572
601
|
thumbnail_prompt: Annotated[
|
|
573
602
|
str | None,
|
|
@@ -585,6 +614,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
585
614
|
str | None,
|
|
586
615
|
Field(description='Vector Explainer only: "none" = drawn stills with camera moves (Ken Burns), "video" = every picture beat animated as an AI clip (costs more; check estimate_credits). Omit to use the template\'s.'),
|
|
587
616
|
] = None,
|
|
617
|
+
pronunciations: Annotated[
|
|
618
|
+
list[dict[str, str]] | None,
|
|
619
|
+
Field(description='How the voice says hard words (ElevenLabs voices): [{"word": "Gmay", "alias": "guh-MAY"}] or [{"word": "Ordnung", "phoneme": "ˈɔɹt.nʊŋ", "alphabet": "ipa"}]. Script, captions and searches keep the real spelling. Replaces the template\'s list for this video; omit to keep it.'),
|
|
620
|
+
] = None,
|
|
588
621
|
) -> dict[str, Any]:
|
|
589
622
|
"""Start a job whose visuals YOU plan. Cliptude writes (if needed) and voices the narration, then stops at status plan_ready. It needs the full website price in credits but charges only the narration now; the rest is charged when the video completes, and the total equals the website price. Poll get_job until plan_ready, then get_narration."""
|
|
590
623
|
try:
|
|
@@ -605,18 +638,19 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
605
638
|
thumbnail=_thumbnail_arg(thumbnail_prompt, thumbnail_reference_url),
|
|
606
639
|
vector_character_id=vector_character_id,
|
|
607
640
|
vector_reveal_mode=vector_reveal_mode,
|
|
641
|
+
pronunciations=pronunciations,
|
|
608
642
|
)
|
|
609
643
|
except Exception as exc:
|
|
610
644
|
return _err(exc)
|
|
611
645
|
|
|
612
646
|
@mcp.tool(
|
|
613
647
|
title="Get narration",
|
|
614
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
648
|
+
annotations=ToolAnnotations(title="Get narration", read_only_hint=True, open_world_hint=False),
|
|
615
649
|
)
|
|
616
650
|
def get_narration(
|
|
617
651
|
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
|
|
618
652
|
) -> dict[str, Any]:
|
|
619
|
-
"""The narration you plan against: numbered sentences with start/end seconds and every word's timing, narration_digest (copy it into the plan), suggested chapters, the template's theme and switched-off graphics,
|
|
653
|
+
"""The narration you plan against: numbered sentences with start/end seconds and every word's timing, narration_digest (copy it into the plan), suggested chapters, the template's theme and switched-off graphics, pricing (website price, already charged, due at continue), and narration_audio: a url to listen to (check names and borrowed words before you lock) and the API path that downloads the MP3. The sentence text is what the voice said, so a misspoken word shows up there too."""
|
|
620
654
|
try:
|
|
621
655
|
return _client().get_narration(job_id)
|
|
622
656
|
except Exception as exc:
|
|
@@ -624,7 +658,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
624
658
|
|
|
625
659
|
@mcp.tool(
|
|
626
660
|
title="Get graphics catalog",
|
|
627
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
661
|
+
annotations=ToolAnnotations(title="Get graphics catalog", read_only_hint=True, open_world_hint=False),
|
|
628
662
|
)
|
|
629
663
|
def get_kind_catalog(
|
|
630
664
|
format: Annotated[str | None, Field(description="faceless_documentary, faceless_top_10, avatar_video or vector_explainer")] = None,
|
|
@@ -641,7 +675,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
641
675
|
|
|
642
676
|
@mcp.tool(
|
|
643
677
|
title="Check plan",
|
|
644
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
678
|
+
annotations=ToolAnnotations(title="Check plan", read_only_hint=True, open_world_hint=False),
|
|
645
679
|
)
|
|
646
680
|
def check_plan(
|
|
647
681
|
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
|
|
@@ -653,7 +687,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
653
687
|
except Exception as exc:
|
|
654
688
|
return _err(exc)
|
|
655
689
|
|
|
656
|
-
@mcp.tool(
|
|
690
|
+
@mcp.tool(
|
|
691
|
+
title="Lock plan",
|
|
692
|
+
annotations=ToolAnnotations(title="Lock plan", read_only_hint=False, destructive_hint=False),
|
|
693
|
+
)
|
|
657
694
|
def lock_plan(
|
|
658
695
|
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
|
|
659
696
|
plan: Annotated[dict[str, Any], Field(description="The plan that check_plan reported valid")],
|
|
@@ -666,7 +703,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
666
703
|
|
|
667
704
|
@mcp.tool(
|
|
668
705
|
title="Get locked plan",
|
|
669
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
706
|
+
annotations=ToolAnnotations(title="Get locked plan", read_only_hint=True, open_world_hint=False),
|
|
670
707
|
)
|
|
671
708
|
def get_plan(
|
|
672
709
|
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID")],
|
|
@@ -679,7 +716,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
679
716
|
|
|
680
717
|
@mcp.tool(
|
|
681
718
|
title="Review the built video",
|
|
682
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
719
|
+
annotations=ToolAnnotations(title="Review the built video", read_only_hint=True, open_world_hint=False),
|
|
683
720
|
)
|
|
684
721
|
def get_plan_review(
|
|
685
722
|
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status ready_for_edit)")],
|
|
@@ -692,13 +729,13 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
692
729
|
|
|
693
730
|
@mcp.tool(
|
|
694
731
|
title="Upload plan media",
|
|
695
|
-
annotations=ToolAnnotations(read_only_hint=False, open_world_hint=False),
|
|
732
|
+
annotations=ToolAnnotations(title="Upload plan media", read_only_hint=False, destructive_hint=False, open_world_hint=False),
|
|
696
733
|
)
|
|
697
734
|
def upload_plan_media(
|
|
698
735
|
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID")],
|
|
699
736
|
path: Annotated[
|
|
700
737
|
str,
|
|
701
|
-
Field(description="Local picture (JPG/PNG/WEBP/GIF, up to 15 MB) or clip (MP4/MOV/WEBM/M4V, up to 300 MB). Stdio / local MCP only
|
|
738
|
+
Field(description="Local picture (JPG/PNG/WEBP/GIF, up to 15 MB) or clip (MP4/MOV/WEBM/M4V, up to 300 MB). Stdio / local MCP only: on a remote host (mcp.cliptude.com) use start_media_upload + finish_media_upload, which work from any agent that can run curl."),
|
|
702
739
|
],
|
|
703
740
|
) -> dict[str, Any]:
|
|
704
741
|
"""Send a picture or clip you found yourself to a plan job. The file goes straight to Cliptude's storage on signed URLs (no storage keys needed) and is checked to be a real picture or video. Returns {keep, file, media_type, size}: put {"keep": "<id>"} as a beat's media or a graphic's picture slot, with start_s/end_s on a beat to play only part of a clip."""
|
|
@@ -707,9 +744,88 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
707
744
|
except Exception as exc:
|
|
708
745
|
return _err(exc)
|
|
709
746
|
|
|
747
|
+
@mcp.tool(
|
|
748
|
+
title="Start media upload",
|
|
749
|
+
annotations=ToolAnnotations(title="Start media upload", read_only_hint=False, destructive_hint=False, open_world_hint=False),
|
|
750
|
+
)
|
|
751
|
+
def start_media_upload(
|
|
752
|
+
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID")],
|
|
753
|
+
filename: Annotated[str, Field(min_length=1, description="The file's name with its extension: JPG/PNG/WEBP/GIF picture (up to 15 MB) or MP4/MOV/WEBM/M4V clip (up to 300 MB).")],
|
|
754
|
+
size: Annotated[int, Field(gt=0, description="The file's size in bytes (e.g. `wc -c < file` or `stat`).")],
|
|
755
|
+
content_type: Annotated[str | None, Field(description="MIME type; omit to infer it from the file name.")] = None,
|
|
756
|
+
) -> dict[str, Any]:
|
|
757
|
+
"""Upload a picture or clip to a plan job from ANY host, remote included: Cliptude signs a PUT URL for each part and you send the bytes yourself, straight to Cliptude's storage. Then call finish_media_upload with the same key and upload_id to get its keep id. Each part: PUT bytes [offset, offset+length) of the file to its url, e.g. `tail -c +$((offset+1)) FILE | head -c LENGTH | curl -sf -X PUT --data-binary @- "URL"` (one part: `curl -sf -X PUT --upload-file FILE "URL"`). URLs expire in 1 hour."""
|
|
758
|
+
try:
|
|
759
|
+
out = _client().start_media_upload(job_id, filename=filename, size=size, content_type=content_type)
|
|
760
|
+
out["next"] = "PUT every part to its url, then finish_media_upload(job_id, key, upload_id)."
|
|
761
|
+
return out
|
|
762
|
+
except Exception as exc:
|
|
763
|
+
return _err(exc)
|
|
764
|
+
|
|
765
|
+
@mcp.tool(
|
|
766
|
+
title="Finish media upload",
|
|
767
|
+
annotations=ToolAnnotations(title="Finish media upload", read_only_hint=False, destructive_hint=False, open_world_hint=False),
|
|
768
|
+
)
|
|
769
|
+
def finish_media_upload(
|
|
770
|
+
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID")],
|
|
771
|
+
key: Annotated[str, Field(min_length=1, description="key from start_media_upload")],
|
|
772
|
+
upload_id: Annotated[str, Field(min_length=1, description="upload_id from start_media_upload")],
|
|
773
|
+
) -> dict[str, Any]:
|
|
774
|
+
"""Close an upload after every part is PUT. Cliptude checks it is a real picture or video and returns {keep, file, media_type, size}: put {"keep": "<id>"} as a beat's media or a graphic's picture slot (start_s/end_s on a beat to play part of a clip)."""
|
|
775
|
+
try:
|
|
776
|
+
return _client().finish_media_upload(job_id, key=key, upload_id=upload_id)
|
|
777
|
+
except Exception as exc:
|
|
778
|
+
return _err(exc)
|
|
779
|
+
|
|
780
|
+
@mcp.tool(
|
|
781
|
+
title="Abort media upload",
|
|
782
|
+
annotations=ToolAnnotations(title="Abort media upload", read_only_hint=False, destructive_hint=True, open_world_hint=False),
|
|
783
|
+
)
|
|
784
|
+
def abort_media_upload(
|
|
785
|
+
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID")],
|
|
786
|
+
key: Annotated[str, Field(min_length=1, description="key from start_media_upload")],
|
|
787
|
+
upload_id: Annotated[str, Field(min_length=1, description="upload_id from start_media_upload")],
|
|
788
|
+
) -> dict[str, Any]:
|
|
789
|
+
"""Cancel an upload you will not finish (frees the parts already sent)."""
|
|
790
|
+
try:
|
|
791
|
+
return _client().abort_media_upload(job_id, key=key, upload_id=upload_id)
|
|
792
|
+
except Exception as exc:
|
|
793
|
+
return _err(exc)
|
|
794
|
+
|
|
795
|
+
@mcp.tool(
|
|
796
|
+
title="Start voiceover upload",
|
|
797
|
+
annotations=ToolAnnotations(title="Start voiceover upload", read_only_hint=False, destructive_hint=False, open_world_hint=False),
|
|
798
|
+
)
|
|
799
|
+
def start_voiceover_upload(
|
|
800
|
+
filename: Annotated[str, Field(min_length=1, description="The narration file's name: MP3, M4A, WAV, OGG, FLAC or WEBM (up to 200 MB).")],
|
|
801
|
+
size: Annotated[int, Field(gt=0, description="The file's size in bytes.")],
|
|
802
|
+
content_type: Annotated[str | None, Field(description="MIME type; omit to infer it from the file name.")] = None,
|
|
803
|
+
) -> dict[str, Any]:
|
|
804
|
+
"""Upload your own narration before the job exists, from ANY host, remote included (for render_only plan jobs, or create_job with your voiceover). PUT each part's bytes to its url exactly as for start_media_upload, then call finish_voiceover_upload: it returns a voiceover_url to pass to create_plan_job / create_job. URLs expire in 1 hour."""
|
|
805
|
+
try:
|
|
806
|
+
out = _client().start_voiceover_upload(filename=filename, size=size, content_type=content_type)
|
|
807
|
+
out["next"] = "PUT every part to its url, then finish_voiceover_upload(key, upload_id) for the voiceover_url."
|
|
808
|
+
return out
|
|
809
|
+
except Exception as exc:
|
|
810
|
+
return _err(exc)
|
|
811
|
+
|
|
812
|
+
@mcp.tool(
|
|
813
|
+
title="Finish voiceover upload",
|
|
814
|
+
annotations=ToolAnnotations(title="Finish voiceover upload", read_only_hint=False, destructive_hint=False, open_world_hint=False),
|
|
815
|
+
)
|
|
816
|
+
def finish_voiceover_upload(
|
|
817
|
+
key: Annotated[str, Field(min_length=1, description="key from start_voiceover_upload")],
|
|
818
|
+
upload_id: Annotated[str, Field(min_length=1, description="upload_id from start_voiceover_upload")],
|
|
819
|
+
) -> dict[str, Any]:
|
|
820
|
+
"""Close a narration upload. Returns {voiceover_url, key, expires_in_s}: pass voiceover_url to create_plan_job (render_only or not) or create_job within the hour. The job checks the audio when it downloads it."""
|
|
821
|
+
try:
|
|
822
|
+
return _client().finish_voiceover_upload(key=key, upload_id=upload_id)
|
|
823
|
+
except Exception as exc:
|
|
824
|
+
return _err(exc)
|
|
825
|
+
|
|
710
826
|
@mcp.tool(
|
|
711
827
|
title="Get plan sourcing report",
|
|
712
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
828
|
+
annotations=ToolAnnotations(title="Get plan sourcing report", read_only_hint=True, open_world_hint=False),
|
|
713
829
|
)
|
|
714
830
|
def get_plan_report(
|
|
715
831
|
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (after continue_job)")],
|
|
@@ -722,7 +838,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
722
838
|
|
|
723
839
|
@mcp.tool(
|
|
724
840
|
title="Get job",
|
|
725
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
841
|
+
annotations=ToolAnnotations(title="Get job", read_only_hint=True, open_world_hint=False),
|
|
726
842
|
)
|
|
727
843
|
def get_job(
|
|
728
844
|
job_id: Annotated[str, Field(min_length=8, description="Job / video UUID")],
|
|
@@ -735,7 +851,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
735
851
|
|
|
736
852
|
@mcp.tool(
|
|
737
853
|
title="List jobs",
|
|
738
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
854
|
+
annotations=ToolAnnotations(title="List jobs", read_only_hint=True, open_world_hint=False),
|
|
739
855
|
)
|
|
740
856
|
def list_jobs(
|
|
741
857
|
status: Annotated[str | None, Field(description="Optional status filter")] = None,
|
|
@@ -750,7 +866,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
750
866
|
|
|
751
867
|
@mcp.tool(
|
|
752
868
|
title="Cancel job",
|
|
753
|
-
annotations=ToolAnnotations(destructive_hint=True, open_world_hint=False),
|
|
869
|
+
annotations=ToolAnnotations(title="Cancel job", read_only_hint=False, destructive_hint=True, open_world_hint=False),
|
|
754
870
|
)
|
|
755
871
|
def cancel_job(
|
|
756
872
|
job_id: Annotated[str, Field(min_length=8, description="Job UUID")],
|
|
@@ -763,12 +879,12 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
763
879
|
|
|
764
880
|
@mcp.tool(
|
|
765
881
|
title="Open editor project",
|
|
766
|
-
annotations=ToolAnnotations(read_only_hint=False, open_world_hint=False),
|
|
882
|
+
annotations=ToolAnnotations(title="Open editor project", read_only_hint=False, destructive_hint=False, open_world_hint=False),
|
|
767
883
|
)
|
|
768
884
|
def open_editor_project(
|
|
769
885
|
job_id: Annotated[str, Field(min_length=8, description="Completed video job id")],
|
|
770
886
|
) -> dict[str, Any]:
|
|
771
|
-
"""Open (or create) the timeline editor project for a completed video job. Returns project id, revision
|
|
887
|
+
"""Open (or create) the timeline editor project for a completed video job. Returns project id, revision, a compact timeline (item id, type, start_s, end_s, text) to reference in run_agent, and export_credits_due: what render_project would charge now."""
|
|
772
888
|
try:
|
|
773
889
|
return _client().open_editor_project(job_id)
|
|
774
890
|
except Exception as exc:
|
|
@@ -776,18 +892,21 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
776
892
|
|
|
777
893
|
@mcp.tool(
|
|
778
894
|
title="Get editor project",
|
|
779
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
895
|
+
annotations=ToolAnnotations(title="Get editor project", read_only_hint=True, open_world_hint=False),
|
|
780
896
|
)
|
|
781
897
|
def get_editor_project(
|
|
782
898
|
project_id: Annotated[int, Field(description="Editor project id")],
|
|
783
899
|
) -> dict[str, Any]:
|
|
784
|
-
"""Current revision, compact timeline
|
|
900
|
+
"""Current revision, compact timeline, latest render and export_credits_due (what render_project would charge now) of an editor project."""
|
|
785
901
|
try:
|
|
786
902
|
return _client().get_editor_project(project_id)
|
|
787
903
|
except Exception as exc:
|
|
788
904
|
return _err(exc)
|
|
789
905
|
|
|
790
|
-
@mcp.tool(
|
|
906
|
+
@mcp.tool(
|
|
907
|
+
title="Run Cliptude Agent",
|
|
908
|
+
annotations=ToolAnnotations(title="Run Cliptude Agent", read_only_hint=False, destructive_hint=False),
|
|
909
|
+
)
|
|
791
910
|
def run_agent(
|
|
792
911
|
project_id: Annotated[int, Field(description="Editor project id")],
|
|
793
912
|
prompt: Annotated[str, Field(min_length=1, description="Edit request in plain English")],
|
|
@@ -807,7 +926,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
807
926
|
|
|
808
927
|
@mcp.tool(
|
|
809
928
|
title="Get agent run",
|
|
810
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
929
|
+
annotations=ToolAnnotations(title="Get agent run", read_only_hint=True, open_world_hint=False),
|
|
811
930
|
)
|
|
812
931
|
def get_agent_run(
|
|
813
932
|
project_id: Annotated[int, Field(description="Editor project id")],
|
|
@@ -819,7 +938,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
819
938
|
except Exception as exc:
|
|
820
939
|
return _err(exc)
|
|
821
940
|
|
|
822
|
-
@mcp.tool(
|
|
941
|
+
@mcp.tool(
|
|
942
|
+
title="Cancel agent run",
|
|
943
|
+
annotations=ToolAnnotations(title="Cancel agent run", read_only_hint=False, destructive_hint=True),
|
|
944
|
+
)
|
|
823
945
|
def cancel_agent_run(
|
|
824
946
|
project_id: Annotated[int, Field(description="Editor project id")],
|
|
825
947
|
run_id: Annotated[str, Field(min_length=8, description="Agent run id")],
|
|
@@ -830,11 +952,14 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
830
952
|
except Exception as exc:
|
|
831
953
|
return _err(exc)
|
|
832
954
|
|
|
833
|
-
@mcp.tool(
|
|
955
|
+
@mcp.tool(
|
|
956
|
+
title="Render editor project",
|
|
957
|
+
annotations=ToolAnnotations(title="Render editor project", read_only_hint=False, destructive_hint=False),
|
|
958
|
+
)
|
|
834
959
|
def render_project(
|
|
835
960
|
project_id: Annotated[int, Field(description="Editor project id")],
|
|
836
961
|
) -> dict[str, Any]:
|
|
837
|
-
"""Render the edited timeline to a new MP4 (
|
|
962
|
+
"""Render the edited timeline to a new MP4. The first export of a project is free; later exports cost 10% of the original generation (export_credits_due on the project says the exact amount). Poll get_render for output_url."""
|
|
838
963
|
try:
|
|
839
964
|
return _client().render_project(project_id)
|
|
840
965
|
except Exception as exc:
|
|
@@ -842,12 +967,12 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
842
967
|
|
|
843
968
|
@mcp.tool(
|
|
844
969
|
title="Get render",
|
|
845
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
970
|
+
annotations=ToolAnnotations(title="Get render", read_only_hint=True, open_world_hint=False),
|
|
846
971
|
)
|
|
847
972
|
def get_render(
|
|
848
973
|
render_id: Annotated[int, Field(description="Editor render id")],
|
|
849
974
|
) -> dict[str, Any]:
|
|
850
|
-
"""Status of an editor render; output_url when completed."""
|
|
975
|
+
"""Status of an editor render; output_url when completed. The link plays in the browser and expires in 7 days, but the MP4 stays in the account: call get_render again for a fresh link instead of telling the user to download before it expires."""
|
|
851
976
|
try:
|
|
852
977
|
return _client().get_render(render_id)
|
|
853
978
|
except Exception as exc:
|
|
@@ -855,7 +980,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
855
980
|
|
|
856
981
|
@mcp.tool(
|
|
857
982
|
title="Get account",
|
|
858
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
983
|
+
annotations=ToolAnnotations(title="Get account", read_only_hint=True, open_world_hint=False),
|
|
859
984
|
)
|
|
860
985
|
def get_account() -> dict[str, Any]:
|
|
861
986
|
"""Plan, credits remaining, and concurrency in use."""
|
package/npm/bin/cliptude.js
CHANGED
|
@@ -11,25 +11,34 @@ const args = process.argv.slice(2);
|
|
|
11
11
|
const venvDir =
|
|
12
12
|
process.env.CLIPTUDE_VENV || path.join(os.homedir(), ".cliptude", "venv");
|
|
13
13
|
|
|
14
|
+
const MINOR_VERSIONS = [14, 13, 12, 11, 10];
|
|
15
|
+
|
|
14
16
|
function pythonCandidates() {
|
|
17
|
+
const fromEnv = process.env.CLIPTUDE_PYTHON ? [process.env.CLIPTUDE_PYTHON] : [];
|
|
15
18
|
if (process.platform === "win32") {
|
|
16
|
-
return ["py", "python", "python3"];
|
|
19
|
+
return [...fromEnv, "py", "python", "python3"];
|
|
17
20
|
}
|
|
18
|
-
|
|
21
|
+
// macOS ships python3 3.9 at /usr/bin; a newer Homebrew, pyenv or python.org
|
|
22
|
+
// install is usually only on PATH under its versioned name.
|
|
23
|
+
const versioned = MINOR_VERSIONS.map((minor) => `python3.${minor}`);
|
|
24
|
+
const dirs = ["/opt/homebrew/bin", "/usr/local/bin"];
|
|
25
|
+
const absolute = dirs.flatMap((dir) =>
|
|
26
|
+
versioned.map((name) => path.join(dir, name)),
|
|
27
|
+
);
|
|
28
|
+
return [...fromEnv, ...versioned, "python3", "python", ...absolute];
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
function isPython310(cmd) {
|
|
32
|
+
const probe = spawnSync(
|
|
33
|
+
cmd,
|
|
34
|
+
["-c", "import sys; sys.exit(0 if sys.version_info >= (3, 10) else 1)"],
|
|
35
|
+
{ encoding: "utf8" },
|
|
36
|
+
);
|
|
37
|
+
return probe.status === 0;
|
|
19
38
|
}
|
|
20
39
|
|
|
21
40
|
function findPython() {
|
|
22
|
-
|
|
23
|
-
const probe = spawnSync(
|
|
24
|
-
cmd,
|
|
25
|
-
["-c", "import sys; sys.exit(0 if sys.version_info >= (3, 10) else 1)"],
|
|
26
|
-
{ encoding: "utf8" },
|
|
27
|
-
);
|
|
28
|
-
if (probe.status === 0) {
|
|
29
|
-
return cmd;
|
|
30
|
-
}
|
|
31
|
-
}
|
|
32
|
-
return null;
|
|
41
|
+
return pythonCandidates().find(isPython310) || null;
|
|
33
42
|
}
|
|
34
43
|
|
|
35
44
|
function venvPython() {
|
|
@@ -120,14 +129,24 @@ function ensureVenv(systemPy) {
|
|
|
120
129
|
return py;
|
|
121
130
|
}
|
|
122
131
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
132
|
+
function resolvePython() {
|
|
133
|
+
// A working install needs no system Python at all.
|
|
134
|
+
const existing = venvPython();
|
|
135
|
+
if (fs.existsSync(existing) && installedVersionMatches(existing)) {
|
|
136
|
+
return existing;
|
|
137
|
+
}
|
|
138
|
+
const systemPy = findPython();
|
|
139
|
+
if (!systemPy) {
|
|
140
|
+
console.error(
|
|
141
|
+
"Python 3.10+ is required and none was found (tried " +
|
|
142
|
+
pythonCandidates().slice(0, 7).join(", ") +
|
|
143
|
+
", ...). Install it, or point CLIPTUDE_PYTHON at one, then re-run: npm i -g @cliptude/cli",
|
|
144
|
+
);
|
|
145
|
+
process.exit(1);
|
|
146
|
+
}
|
|
147
|
+
return ensureVenv(systemPy);
|
|
129
148
|
}
|
|
130
149
|
|
|
131
|
-
const py =
|
|
150
|
+
const py = resolvePython();
|
|
132
151
|
const result = run(py, ["-m", "cliptude_mcp.cli", ...args]);
|
|
133
152
|
process.exit(result.status ?? 1);
|
package/package.json
CHANGED
package/pyproject.toml
CHANGED