@cliptude/cli 0.1.11 → 0.1.13
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 +20 -0
- package/cliptude_mcp/cli.py +58 -3
- package/cliptude_mcp/client.py +85 -1
- package/cliptude_mcp/server.py +250 -48
- 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`.
|
|
@@ -69,6 +71,24 @@ footage under every beat, the transition on each cut, two-image reveals, and fre
|
|
|
69
71
|
lists the graphics, `transitions`, `reveal_styles` and `sounds` (with previews). The plan schema and rules are in
|
|
70
72
|
`skills/cliptude-plan/SKILL.md`. The job costs the same as the website price.
|
|
71
73
|
|
|
74
|
+
### Product videos from a store
|
|
75
|
+
|
|
76
|
+
Turn a store product into a 6 to 60 minute educational YouTube video: about 80% teaching, then the product, with its
|
|
77
|
+
real photos composited into the closing boards (never regenerated). Any Shopify product URL works with no setup; other
|
|
78
|
+
stores work through the page's structured data; a store connected at cliptude.com/integrations/stores/ (or that
|
|
79
|
+
installed the Cliptude Shopify app) can also be searched.
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
cliptude product fetch https://store.com/products/handle # product_id + 3 angles
|
|
83
|
+
cliptude product script <product-id> --angle 1 --duration 10-12 --discount-code YOUTUBE15
|
|
84
|
+
cliptude product status <job-id> # until script_ready; review the script
|
|
85
|
+
cliptude product render <job-id> --aspect-ratio 16:9 # returns at once
|
|
86
|
+
cliptude product status <job-id> # until ready_for_review; open editor_url
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
MCP tools: `fetch_product_context`, `draft_product_script`, `render_product_video`, `get_product_video_status`.
|
|
90
|
+
None of them waits for a render; poll the status tool.
|
|
91
|
+
|
|
72
92
|
`--title` is required. Provide **one** of `--prompt`, `--script` / `--script-file`, `--voiceover`, or `--talking-head`. Never copy the title into `--prompt`. If you only have a topic, follow **cliptude-script** (web search → spoken narration → `--script-file`), or ask Cliptude to write it with `cliptude script`. After a completed `script` or `voiceover` job, `cliptude continue <job-id>` turns that same job into a full video (reuses the script; voiceover jobs reuse the TTS file). `--voiceover` is a local audio file (same as create.html); it is transcribed and skips TTS — do not combine it with prompt/script. `--talking-head` is a presenter video on a Talking Head template (MP4, MOV, WEBM, AVI); it is transcribed and skips TTS. Optional `--duration` is a wizard bucket (`3-4`, `6-8`, `10-12`, …). Omit it to use the template duration, or the word-count estimate when you pass `--script`. Uploaded audio or talking-head video sets duration from the file. Avatar Video templates can override **Avatar Intro Only** and **AI Image + AI Video** with `--avatar-intro-only` / `--no-avatar-intro-only` and `--avatar-ai-footage` / `--no-avatar-ai-footage`. Omit those flags to keep the template. `generate` / `script` / `voiceover` / `continue` return immediately (`queued`). Poll `status`.
|
|
73
93
|
|
|
74
94
|
## MCP
|
package/cliptude_mcp/cli.py
CHANGED
|
@@ -143,6 +143,15 @@ def _run_auth(auth_cmd: str) -> None:
|
|
|
143
143
|
print(f"Logged in{f' as {email}' if email else '.'}")
|
|
144
144
|
|
|
145
145
|
|
|
146
|
+
def _review_arg(value: str) -> dict:
|
|
147
|
+
"""--review "quote|author|rating" -> {quote, author, rating}."""
|
|
148
|
+
parts = [p.strip() for p in value.split("|")]
|
|
149
|
+
review = {"quote": parts[0], "author": parts[1] if len(parts) > 1 else ""}
|
|
150
|
+
if len(parts) > 2 and parts[2]:
|
|
151
|
+
review["rating"] = float(parts[2])
|
|
152
|
+
return review
|
|
153
|
+
|
|
154
|
+
|
|
146
155
|
def main(argv: list[str] | None = None) -> None:
|
|
147
156
|
parser = argparse.ArgumentParser(
|
|
148
157
|
prog="cliptude",
|
|
@@ -270,13 +279,13 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
270
279
|
g.add_argument(
|
|
271
280
|
"--voiceover",
|
|
272
281
|
default="",
|
|
273
|
-
help="Path to a narration audio file (MP3, M4A, WAV, …). Transcribed; skips TTS. Do not combine with --prompt or --script.",
|
|
282
|
+
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.",
|
|
274
283
|
)
|
|
275
|
-
g.add_argument("--voiceover-url", default="", help="Public https link to the narration audio; Cliptude downloads it.")
|
|
284
|
+
g.add_argument("--voiceover-url", default="", help="Public https link to the narration audio (at least 6 minutes long); Cliptude downloads it.")
|
|
276
285
|
g.add_argument(
|
|
277
286
|
"--talking-head",
|
|
278
287
|
default="",
|
|
279
|
-
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.",
|
|
288
|
+
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.",
|
|
280
289
|
)
|
|
281
290
|
g.add_argument(
|
|
282
291
|
"--duration",
|
|
@@ -395,6 +404,38 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
395
404
|
)
|
|
396
405
|
cont.add_argument("job_id")
|
|
397
406
|
|
|
407
|
+
prod = sub.add_parser(
|
|
408
|
+
"product",
|
|
409
|
+
help="Product videos from a store: fetch a product, draft its 80/20 script, render, check status",
|
|
410
|
+
formatter_class=argparse.RawDescriptionHelpFormatter,
|
|
411
|
+
epilog=(
|
|
412
|
+
"examples:\n"
|
|
413
|
+
" cliptude product fetch https://store.com/products/handle\n"
|
|
414
|
+
" cliptude product script <product-id> --angle 1 --duration 10-12 --discount-code YOUTUBE15\n"
|
|
415
|
+
" cliptude product render <job-id> --aspect-ratio 16:9\n"
|
|
416
|
+
" cliptude product status <job-id>"
|
|
417
|
+
),
|
|
418
|
+
)
|
|
419
|
+
prod_sub = prod.add_subparsers(dest="product_cmd", required=True)
|
|
420
|
+
pf = prod_sub.add_parser("fetch", help="Read a product URL (or search a store) and get 3 video angles")
|
|
421
|
+
pf.add_argument("url_or_query")
|
|
422
|
+
pf.add_argument("--store", default="", help="Store domain to search, e.g. acme.com")
|
|
423
|
+
ps = prod_sub.add_parser("script", help="Queue the 80/20 educational script for a product")
|
|
424
|
+
ps.add_argument("product_id")
|
|
425
|
+
ps.add_argument("--angle", default="0", help="Angle index 0-2, or a custom educational title")
|
|
426
|
+
ps.add_argument("--duration", default="6-8", help="6-8, 10-12, 18-20, 30-40, 50-60 or minutes (6-60)")
|
|
427
|
+
ps.add_argument("--template", default="", help="Faceless Documentary template id")
|
|
428
|
+
ps.add_argument("--title", default="")
|
|
429
|
+
ps.add_argument("--discount-code", default="")
|
|
430
|
+
ps.add_argument("--cta-url", default="")
|
|
431
|
+
ps.add_argument("--review", action="append", default=[],
|
|
432
|
+
help='A real customer review, "quote|author|rating" (repeat up to 3 times)')
|
|
433
|
+
pr = prod_sub.add_parser("render", help="Produce the video from a ready product script")
|
|
434
|
+
pr.add_argument("job_id")
|
|
435
|
+
pr.add_argument("--aspect-ratio", default="16:9")
|
|
436
|
+
pst = prod_sub.add_parser("status", help="Stage, script, preview link and MP4 of a product video")
|
|
437
|
+
pst.add_argument("job_id")
|
|
438
|
+
|
|
398
439
|
pj = sub.add_parser(
|
|
399
440
|
"plan-job",
|
|
400
441
|
help="Start an agent-planned job: Cliptude voices the narration and stops at plan_ready",
|
|
@@ -682,6 +723,20 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
682
723
|
_print({"ok": True, "path": str(dest.resolve())})
|
|
683
724
|
elif args.cmd == "continue":
|
|
684
725
|
_print(client.continue_job(args.job_id))
|
|
726
|
+
elif args.cmd == "product":
|
|
727
|
+
if args.product_cmd == "fetch":
|
|
728
|
+
_print(client.fetch_product_context(args.url_or_query, store_domain=args.store or None))
|
|
729
|
+
elif args.product_cmd == "script":
|
|
730
|
+
angle = int(args.angle) if str(args.angle).isdigit() else args.angle
|
|
731
|
+
_print(client.draft_product_script(
|
|
732
|
+
args.product_id, angle=angle, duration=args.duration, template_id=args.template or None,
|
|
733
|
+
title=args.title or None, discount_code=args.discount_code or None, cta_url=args.cta_url or None,
|
|
734
|
+
reviews=[_review_arg(r) for r in args.review] or None,
|
|
735
|
+
))
|
|
736
|
+
elif args.product_cmd == "render":
|
|
737
|
+
_print(client.render_product_video(args.job_id, aspect_ratio=args.aspect_ratio))
|
|
738
|
+
else:
|
|
739
|
+
_print(client.get_product_video_status(args.job_id))
|
|
685
740
|
elif args.cmd == "editor":
|
|
686
741
|
_print(client.open_editor_project(args.job_id))
|
|
687
742
|
elif args.cmd == "agent":
|
package/cliptude_mcp/client.py
CHANGED
|
@@ -651,6 +651,47 @@ class CliptudeClient:
|
|
|
651
651
|
"""Queue a completed script/voiceover job, or a plan job with a locked plan, as a full video."""
|
|
652
652
|
return self.request("POST", f"/api/v1/jobs/{job_id}/continue")
|
|
653
653
|
|
|
654
|
+
# Product videos (store products: Shopify, any store page) --------------------------------------
|
|
655
|
+
|
|
656
|
+
def fetch_product_context(self, product_url_or_query: str, *, store_domain: str | None = None) -> Any:
|
|
657
|
+
"""Read a store product (URL, connected-store id/handle, or a search on store_domain) and get 3 angles."""
|
|
658
|
+
body: dict[str, Any] = {"url_or_query": product_url_or_query}
|
|
659
|
+
if store_domain:
|
|
660
|
+
body["store_domain"] = store_domain
|
|
661
|
+
return self.request("POST", "/api/v1/commerce/products/fetch", json_body=body)
|
|
662
|
+
|
|
663
|
+
def draft_product_script(
|
|
664
|
+
self,
|
|
665
|
+
product_id: str,
|
|
666
|
+
*,
|
|
667
|
+
angle: Any = None,
|
|
668
|
+
duration: str | int | None = None,
|
|
669
|
+
template_id: str | None = None,
|
|
670
|
+
title: str | None = None,
|
|
671
|
+
discount_code: str | None = None,
|
|
672
|
+
cta_url: str | None = None,
|
|
673
|
+
cta_text: str | None = None,
|
|
674
|
+
image_urls: list[str] | None = None,
|
|
675
|
+
reviews: list[dict] | None = None,
|
|
676
|
+
) -> Any:
|
|
677
|
+
"""Queue the 80/20 educational script for a product; returns {script_id, ...} immediately."""
|
|
678
|
+
body: dict[str, Any] = {"product_id": product_id}
|
|
679
|
+
for key, value in (
|
|
680
|
+
("angle", angle), ("duration", duration), ("template_id", template_id), ("title", title),
|
|
681
|
+
("discount_code", discount_code), ("cta_url", cta_url), ("cta_text", cta_text),
|
|
682
|
+
("image_urls", image_urls), ("reviews", reviews),
|
|
683
|
+
):
|
|
684
|
+
if value not in (None, "", []):
|
|
685
|
+
body[key] = value
|
|
686
|
+
return self.request("POST", "/api/v1/commerce/scripts", json_body=body)
|
|
687
|
+
|
|
688
|
+
def render_product_video(self, job_id: str, *, aspect_ratio: str = "16:9") -> Any:
|
|
689
|
+
"""Turn a ready product script into the video on the same job id (returns immediately)."""
|
|
690
|
+
return self.request("POST", f"/api/v1/commerce/videos/{job_id}/render", json_body={"aspect_ratio": aspect_ratio})
|
|
691
|
+
|
|
692
|
+
def get_product_video_status(self, job_id: str) -> Any:
|
|
693
|
+
return self.request("GET", f"/api/v1/commerce/videos/{job_id}")
|
|
694
|
+
|
|
654
695
|
# Agent-planned videos -------------------------------------------------------------------------
|
|
655
696
|
|
|
656
697
|
def upload_plan_media(self, job_id: str, path: str | Path) -> Any:
|
|
@@ -679,6 +720,49 @@ class CliptudeClient:
|
|
|
679
720
|
pass
|
|
680
721
|
raise
|
|
681
722
|
|
|
723
|
+
def _start_signed_upload(self, base: str, *, filename: str, size: int, content_type: str | None) -> dict[str, Any]:
|
|
724
|
+
"""Open a multipart upload and sign every part: [{part, offset, length, url}] for the caller to PUT."""
|
|
725
|
+
if int(size or 0) <= 0:
|
|
726
|
+
raise CliptudeApiError("size (the file size in bytes) is required.")
|
|
727
|
+
ctype = content_type or mimetypes.guess_type(filename)[0] or "application/octet-stream"
|
|
728
|
+
init = self.request("POST", f"{base}/init", json_body={"filename": filename, "size": int(size), "content_type": ctype})
|
|
729
|
+
key, upload_id = str((init or {}).get("key") or ""), str((init or {}).get("upload_id") or "")
|
|
730
|
+
part_size, part_count = int((init or {}).get("part_size") or 0), int((init or {}).get("part_count") or 0)
|
|
731
|
+
if not key or not upload_id or part_size <= 0 or part_count <= 0:
|
|
732
|
+
raise CliptudeApiError("The upload init returned an incomplete plan.")
|
|
733
|
+
parts: list[dict[str, Any]] = []
|
|
734
|
+
for start in range(0, part_count, 50):
|
|
735
|
+
nums = list(range(start + 1, min(start + 50, part_count) + 1))
|
|
736
|
+
signed = self.request("POST", f"{base}/sign-parts", json_body={"key": key, "upload_id": upload_id, "part_numbers": nums})
|
|
737
|
+
urls = (signed or {}).get("urls") if isinstance(signed, dict) else None
|
|
738
|
+
if not isinstance(urls, dict):
|
|
739
|
+
raise CliptudeApiError("Could not sign the upload parts.")
|
|
740
|
+
for num in nums:
|
|
741
|
+
offset = (num - 1) * part_size
|
|
742
|
+
parts.append({"part": num, "offset": offset, "length": min(part_size, int(size) - offset), "url": urls.get(str(num))})
|
|
743
|
+
return {"key": key, "upload_id": upload_id, "part_size": part_size, "part_count": part_count, "size": int(size), "parts": parts}
|
|
744
|
+
|
|
745
|
+
def start_media_upload(self, job_id: str, *, filename: str, size: int, content_type: str | None = None) -> dict[str, Any]:
|
|
746
|
+
"""Signed PUT URLs for a picture or clip of a plan job, for a host that sends the bytes itself."""
|
|
747
|
+
return self._start_signed_upload(f"/api/v1/jobs/{job_id}/media", filename=filename, size=size, content_type=content_type)
|
|
748
|
+
|
|
749
|
+
def finish_media_upload(self, job_id: str, *, key: str, upload_id: str) -> Any:
|
|
750
|
+
return self.request("POST", f"/api/v1/jobs/{job_id}/media/complete", json_body={"key": key, "upload_id": upload_id})
|
|
751
|
+
|
|
752
|
+
def abort_media_upload(self, job_id: str, *, key: str, upload_id: str) -> Any:
|
|
753
|
+
return self.request("POST", f"/api/v1/jobs/{job_id}/media/abort", json_body={"key": key, "upload_id": upload_id})
|
|
754
|
+
|
|
755
|
+
def start_voiceover_upload(self, *, filename: str, size: int, content_type: str | None = None) -> dict[str, Any]:
|
|
756
|
+
"""Signed PUT URLs for a narration file, before the job exists."""
|
|
757
|
+
return self._start_signed_upload("/api/v1/uploads/voiceover", filename=filename, size=size, content_type=content_type)
|
|
758
|
+
|
|
759
|
+
def finish_voiceover_upload(self, *, key: str, upload_id: str) -> Any:
|
|
760
|
+
"""Returns {voiceover_url, key, expires_in_s}: pass voiceover_url to create_job / create_plan_job."""
|
|
761
|
+
return self.request("POST", "/api/v1/uploads/voiceover/complete", json_body={"key": key, "upload_id": upload_id})
|
|
762
|
+
|
|
763
|
+
def abort_voiceover_upload(self, *, key: str, upload_id: str) -> Any:
|
|
764
|
+
return self.request("POST", "/api/v1/uploads/voiceover/abort", json_body={"key": key, "upload_id": upload_id})
|
|
765
|
+
|
|
682
766
|
def get_narration(self, job_id: str) -> Any:
|
|
683
767
|
"""Numbered sentences (with word timings), digest, pricing and template flags of a plan job."""
|
|
684
768
|
return self.request("GET", f"/api/v1/jobs/{job_id}/narration")
|
|
@@ -814,7 +898,7 @@ class CliptudeClient:
|
|
|
814
898
|
return self.request("POST", f"/api/v1/editor-projects/{project_id}/agent/runs/{run_id}/cancel")
|
|
815
899
|
|
|
816
900
|
def render_project(self, project_id: int | str) -> Any:
|
|
817
|
-
"""Render the edited timeline to a new MP4
|
|
901
|
+
"""Render the edited timeline to a new MP4: free the first time, then 10% of the original generation."""
|
|
818
902
|
return self.request("POST", f"/api/v1/editor-projects/{project_id}/render")
|
|
819
903
|
|
|
820
904
|
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. "
|
|
@@ -126,7 +126,13 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
126
126
|
"and Cliptude only voices, sources and renders. create_plan_job, poll get_job until "
|
|
127
127
|
"plan_ready, get_narration (numbered sentences), get_kind_catalog (compact first), write the "
|
|
128
128
|
"plan, check_plan until valid, lock_plan, continue_job, then get_plan_report. See the "
|
|
129
|
-
"cliptude-plan skill."
|
|
129
|
+
"cliptude-plan skill. "
|
|
130
|
+
"PRODUCT VIDEOS (Shopify product URLs, a connected store, or any store's product page): "
|
|
131
|
+
"fetch_product_context, show the user the 3 angles, draft_product_script with their pick and a "
|
|
132
|
+
"duration (6-8 to 50-60 minutes), poll get_product_video_status until script_ready, let the user "
|
|
133
|
+
"review the script, render_product_video, poll until ready_for_review, give the user editor_url, "
|
|
134
|
+
"and only after they approve render with open_editor_project + render_project + get_render. "
|
|
135
|
+
"Never publish anything to a store or YouTube without the user's explicit go-ahead."
|
|
130
136
|
),
|
|
131
137
|
}
|
|
132
138
|
if with_http_auth:
|
|
@@ -139,7 +145,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
139
145
|
|
|
140
146
|
@mcp.tool(
|
|
141
147
|
title="List templates",
|
|
142
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
148
|
+
annotations=ToolAnnotations(title="List templates", read_only_hint=True, open_world_hint=False),
|
|
143
149
|
)
|
|
144
150
|
def list_templates(
|
|
145
151
|
limit: Annotated[int, Field(ge=1, le=100, description="Page size")] = 20,
|
|
@@ -153,7 +159,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
153
159
|
|
|
154
160
|
@mcp.tool(
|
|
155
161
|
title="Get template",
|
|
156
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
162
|
+
annotations=ToolAnnotations(title="Get template", read_only_hint=True, open_world_hint=False),
|
|
157
163
|
)
|
|
158
164
|
def get_template(
|
|
159
165
|
template_id: Annotated[str, Field(min_length=8, description="Template UUID")],
|
|
@@ -166,7 +172,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
166
172
|
|
|
167
173
|
@mcp.tool(
|
|
168
174
|
title="Get template options",
|
|
169
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
175
|
+
annotations=ToolAnnotations(title="Get template options", read_only_hint=True, open_world_hint=False),
|
|
170
176
|
)
|
|
171
177
|
def get_template_options(
|
|
172
178
|
format: Annotated[str, Field(description="Video format, e.g. faceless_documentary or vector_explainer")],
|
|
@@ -179,7 +185,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
179
185
|
|
|
180
186
|
@mcp.tool(
|
|
181
187
|
title="List voices",
|
|
182
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=True),
|
|
188
|
+
annotations=ToolAnnotations(title="List voices", read_only_hint=True, open_world_hint=True),
|
|
183
189
|
)
|
|
184
190
|
def list_voices(
|
|
185
191
|
provider: Annotated[str, Field(description="elevenlabs, minimax, cartesia, inworld or voicetory")] = "elevenlabs",
|
|
@@ -191,7 +197,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
191
197
|
except Exception as exc:
|
|
192
198
|
return _err(exc)
|
|
193
199
|
|
|
194
|
-
@mcp.tool(
|
|
200
|
+
@mcp.tool(
|
|
201
|
+
title="Create template",
|
|
202
|
+
annotations=ToolAnnotations(title="Create template", read_only_hint=False, destructive_hint=False),
|
|
203
|
+
)
|
|
195
204
|
def create_template(
|
|
196
205
|
name: Annotated[str, Field(min_length=1, max_length=120, description="Template name")],
|
|
197
206
|
format: Annotated[str, Field(description="Video format, e.g. faceless_documentary")],
|
|
@@ -219,7 +228,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
219
228
|
|
|
220
229
|
@mcp.tool(
|
|
221
230
|
title="Estimate credits",
|
|
222
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
231
|
+
annotations=ToolAnnotations(title="Estimate credits", read_only_hint=True, open_world_hint=False),
|
|
223
232
|
)
|
|
224
233
|
def estimate_credits(
|
|
225
234
|
template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
|
|
@@ -253,7 +262,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
253
262
|
] = None,
|
|
254
263
|
render_only: Annotated[
|
|
255
264
|
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."),
|
|
265
|
+
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
266
|
] = None,
|
|
258
267
|
vector_reveal_mode: Annotated[
|
|
259
268
|
str | None,
|
|
@@ -287,7 +296,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
287
296
|
|
|
288
297
|
@mcp.tool(
|
|
289
298
|
title="List avatars",
|
|
290
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
299
|
+
annotations=ToolAnnotations(title="List avatars", read_only_hint=True, open_world_hint=False),
|
|
291
300
|
)
|
|
292
301
|
def list_avatars(
|
|
293
302
|
section: Annotated[
|
|
@@ -307,7 +316,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
307
316
|
|
|
308
317
|
@mcp.tool(
|
|
309
318
|
title="List vector characters",
|
|
310
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
319
|
+
annotations=ToolAnnotations(title="List vector characters", read_only_hint=True, open_world_hint=False),
|
|
311
320
|
)
|
|
312
321
|
def list_vector_characters() -> dict[str, Any]:
|
|
313
322
|
"""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 +325,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
316
325
|
except Exception as exc:
|
|
317
326
|
return _err(exc)
|
|
318
327
|
|
|
319
|
-
@mcp.tool(
|
|
328
|
+
@mcp.tool(
|
|
329
|
+
title="Upload vector character",
|
|
330
|
+
annotations=ToolAnnotations(title="Upload vector character", read_only_hint=False, destructive_hint=False),
|
|
331
|
+
)
|
|
320
332
|
def upload_vector_character(
|
|
321
333
|
name: Annotated[str, Field(min_length=1, max_length=120, description="A short name for the character, e.g. 'Dr. Maya'")],
|
|
322
334
|
image_path: Annotated[str | None, Field(description="Local PNG, JPG or WEBP file. Stdio / local MCP only.")] = None,
|
|
@@ -332,7 +344,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
332
344
|
except Exception as exc:
|
|
333
345
|
return _err(exc)
|
|
334
346
|
|
|
335
|
-
@mcp.tool(
|
|
347
|
+
@mcp.tool(
|
|
348
|
+
title="Delete vector character",
|
|
349
|
+
annotations=ToolAnnotations(title="Delete vector character", read_only_hint=False, destructive_hint=True),
|
|
350
|
+
)
|
|
336
351
|
def delete_vector_character(
|
|
337
352
|
character_id: Annotated[str, Field(min_length=8, description="Uploaded character id from list_vector_characters")],
|
|
338
353
|
) -> dict[str, Any]:
|
|
@@ -342,7 +357,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
342
357
|
except Exception as exc:
|
|
343
358
|
return _err(exc)
|
|
344
359
|
|
|
345
|
-
@mcp.tool(
|
|
360
|
+
@mcp.tool(
|
|
361
|
+
title="Create video job",
|
|
362
|
+
annotations=ToolAnnotations(title="Create video job", read_only_hint=False, destructive_hint=False),
|
|
363
|
+
)
|
|
346
364
|
def create_job(
|
|
347
365
|
template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
|
|
348
366
|
title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
|
|
@@ -362,7 +380,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
362
380
|
str | None,
|
|
363
381
|
Field(
|
|
364
382
|
description=(
|
|
365
|
-
"Local path to a talking-head presenter video (MP4, MOV, WEBM, AVI). "
|
|
383
|
+
"Local path to a talking-head presenter video (MP4, MOV, WEBM, AVI), at least 6 minutes long. "
|
|
366
384
|
"Requires a Talking Head template. Cliptude transcribes it and skips TTS. "
|
|
367
385
|
"Do not also send prompt, script, or voiceover_path. "
|
|
368
386
|
"Stdio / local MCP only — remote hosts should use the CLI."
|
|
@@ -425,7 +443,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
425
443
|
] = None,
|
|
426
444
|
voiceover_url: Annotated[
|
|
427
445
|
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.
|
|
446
|
+
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
447
|
] = None,
|
|
430
448
|
thumbnail_prompt: Annotated[
|
|
431
449
|
str | None,
|
|
@@ -492,7 +510,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
492
510
|
except Exception as exc:
|
|
493
511
|
return _err(exc)
|
|
494
512
|
|
|
495
|
-
@mcp.tool(
|
|
513
|
+
@mcp.tool(
|
|
514
|
+
title="Create script job",
|
|
515
|
+
annotations=ToolAnnotations(title="Create script job", read_only_hint=False, destructive_hint=False),
|
|
516
|
+
)
|
|
496
517
|
def create_script(
|
|
497
518
|
template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
|
|
498
519
|
title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
|
|
@@ -514,7 +535,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
514
535
|
except Exception as exc:
|
|
515
536
|
return _err(exc)
|
|
516
537
|
|
|
517
|
-
@mcp.tool(
|
|
538
|
+
@mcp.tool(
|
|
539
|
+
title="Create voiceover job",
|
|
540
|
+
annotations=ToolAnnotations(title="Create voiceover job", read_only_hint=False, destructive_hint=False),
|
|
541
|
+
)
|
|
518
542
|
def create_voiceover(
|
|
519
543
|
template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
|
|
520
544
|
title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
|
|
@@ -540,7 +564,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
540
564
|
except Exception as exc:
|
|
541
565
|
return _err(exc)
|
|
542
566
|
|
|
543
|
-
@mcp.tool(
|
|
567
|
+
@mcp.tool(
|
|
568
|
+
title="Continue job into video",
|
|
569
|
+
annotations=ToolAnnotations(title="Continue job into video", read_only_hint=False, destructive_hint=False),
|
|
570
|
+
)
|
|
544
571
|
def continue_job(
|
|
545
572
|
job_id: Annotated[str, Field(min_length=8, description="Completed script or voiceover job UUID, or a plan job with a locked plan")],
|
|
546
573
|
) -> dict[str, Any]:
|
|
@@ -550,16 +577,100 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
550
577
|
except Exception as exc:
|
|
551
578
|
return _err(exc)
|
|
552
579
|
|
|
553
|
-
@mcp.tool(
|
|
580
|
+
@mcp.tool(
|
|
581
|
+
title="Fetch product context",
|
|
582
|
+
annotations=ToolAnnotations(title="Fetch product context", read_only_hint=True, destructive_hint=False,
|
|
583
|
+
open_world_hint=True),
|
|
584
|
+
)
|
|
585
|
+
def fetch_product_context(
|
|
586
|
+
product_url_or_query: Annotated[str, Field(min_length=1, description=(
|
|
587
|
+
"A product page URL (any Shopify store, e.g. https://store.com/products/handle; other stores "
|
|
588
|
+
"such as WooCommerce or Etsy work through the page's structured data), a connected store's "
|
|
589
|
+
"product id/handle, or a search term together with store_domain."))],
|
|
590
|
+
store_domain: Annotated[str | None, Field(description=(
|
|
591
|
+
"Store to search or read from, e.g. acme.com or acme.myshopify.com. Uses the user's connected "
|
|
592
|
+
"store when it matches."))] = None,
|
|
593
|
+
) -> dict[str, Any]:
|
|
594
|
+
"""Read a store product: title, price, variants, description and its real image URLs, saved as product_id, plus 3 educational YouTube video angles (80% teaching, 20% product). A search that matches several products returns candidates; fetch again with the chosen URL. Show the user the angles before drafting."""
|
|
595
|
+
try:
|
|
596
|
+
return _client().fetch_product_context(product_url_or_query, store_domain=store_domain)
|
|
597
|
+
except Exception as exc:
|
|
598
|
+
return _err(exc)
|
|
599
|
+
|
|
600
|
+
@mcp.tool(
|
|
601
|
+
title="Draft product video script",
|
|
602
|
+
annotations=ToolAnnotations(title="Draft product video script", read_only_hint=False, destructive_hint=False),
|
|
603
|
+
)
|
|
604
|
+
def draft_product_script(
|
|
605
|
+
product_id: Annotated[str, Field(min_length=8, description="product_id from fetch_product_context")],
|
|
606
|
+
angle: Annotated[int | str | dict | None, Field(description=(
|
|
607
|
+
"Index (0-2) of an angle from fetch_product_context, an angle object {title, problem, hook}, or "
|
|
608
|
+
"a custom educational title. Default 0."))] = None,
|
|
609
|
+
duration: Annotated[str | int | None, Field(description=(
|
|
610
|
+
"Length: 6-8, 10-12, 18-20, 30-40 or 50-60 (minutes), or a number of minutes from 6 to 60. "
|
|
611
|
+
"Default 6-8."))] = None,
|
|
612
|
+
template_id: Annotated[str | None, Field(description=(
|
|
613
|
+
"Faceless Documentary template to use (voice, look, music). Omit to use the latest one, or a "
|
|
614
|
+
"default Product Explainer template."))] = None,
|
|
615
|
+
title: Annotated[str | None, Field(description="Video title. Defaults to the angle title.")] = None,
|
|
616
|
+
discount_code: Annotated[str | None, Field(description="Discount code the merchant gave. Never invent one.")] = None,
|
|
617
|
+
cta_url: Annotated[str | None, Field(description="Where viewers should go. Defaults to the product page.")] = None,
|
|
618
|
+
image_urls: Annotated[list[str] | None, Field(description=(
|
|
619
|
+
"Which of the product's image URLs to show (defaults to all of them)."))] = None,
|
|
620
|
+
reviews: Annotated[list[dict] | None, Field(description=(
|
|
621
|
+
"Up to 3 real customer reviews the merchant gave you, word for word: "
|
|
622
|
+
"[{quote, author, rating (1-5), verified}]. Enables the review card. Never write or "
|
|
623
|
+
"paraphrase a review."))] = None,
|
|
624
|
+
) -> dict[str, Any]:
|
|
625
|
+
"""Queue the narration for a product video: an educational documentary for about 80% of its length, then a natural bridge to the product (real specs, price, offer) in the last 20%. Returns script_id (the job id) immediately; poll get_product_video_status until stage is script_ready, then show the user the script."""
|
|
626
|
+
try:
|
|
627
|
+
return _client().draft_product_script(
|
|
628
|
+
product_id, angle=angle, duration=duration, template_id=template_id, title=title,
|
|
629
|
+
discount_code=discount_code, cta_url=cta_url, image_urls=image_urls, reviews=reviews,
|
|
630
|
+
)
|
|
631
|
+
except Exception as exc:
|
|
632
|
+
return _err(exc)
|
|
633
|
+
|
|
634
|
+
@mcp.tool(
|
|
635
|
+
title="Render product video",
|
|
636
|
+
annotations=ToolAnnotations(title="Render product video", read_only_hint=False, destructive_hint=False),
|
|
637
|
+
)
|
|
638
|
+
def render_product_video(
|
|
639
|
+
script_id: Annotated[str, Field(min_length=8, description="script_id / job_id from draft_product_script, once script_ready")],
|
|
640
|
+
aspect_ratio: Annotated[str, Field(description="16:9 (YouTube), 9:16, 1:1 or 4:5")] = "16:9",
|
|
641
|
+
) -> dict[str, Any]:
|
|
642
|
+
"""Produce the video from the approved script on the same job id: voiceover, sourcing, motion graphics, and the merchant's real product photos composited into the closing product boards. Returns {job_id, status, editor_url, estimated_minutes} immediately; never wait in this call. Poll get_product_video_status."""
|
|
643
|
+
try:
|
|
644
|
+
return _client().render_product_video(script_id, aspect_ratio=aspect_ratio)
|
|
645
|
+
except Exception as exc:
|
|
646
|
+
return _err(exc)
|
|
647
|
+
|
|
648
|
+
@mcp.tool(
|
|
649
|
+
title="Get product video status",
|
|
650
|
+
annotations=ToolAnnotations(title="Get product video status", read_only_hint=True, destructive_hint=False),
|
|
651
|
+
)
|
|
652
|
+
def get_product_video_status(
|
|
653
|
+
job_id: Annotated[str, Field(min_length=8, description="Job id from draft_product_script / render_product_video")],
|
|
654
|
+
) -> dict[str, Any]:
|
|
655
|
+
"""Stage of a product video (script_drafting, script_ready, producing, ready_for_review, rendered, failed) with the script once written, the editor_url to preview, the MP4 URL once rendered, and next_step telling you what to do."""
|
|
656
|
+
try:
|
|
657
|
+
return _client().get_product_video_status(job_id)
|
|
658
|
+
except Exception as exc:
|
|
659
|
+
return _err(exc)
|
|
660
|
+
|
|
661
|
+
@mcp.tool(
|
|
662
|
+
title="Create agent-planned job",
|
|
663
|
+
annotations=ToolAnnotations(title="Create agent-planned job", read_only_hint=False, destructive_hint=False),
|
|
664
|
+
)
|
|
554
665
|
def create_plan_job(
|
|
555
666
|
template_id: Annotated[str, Field(min_length=8, description="Saved Faceless Documentary, Faceless Top 10, Avatar Video or Vector Explainer template UUID")],
|
|
556
667
|
title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
|
|
557
668
|
prompt: Annotated[str | None, Field(description="Topic/brief; Cliptude writes the narration. Never the video title.")] = None,
|
|
558
669
|
script: Annotated[str | None, Field(description="Spoken narration to voice as-is. Omit prompt when you pass this.")] = None,
|
|
559
|
-
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,
|
|
670
|
+
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,
|
|
560
671
|
voiceover_url: Annotated[
|
|
561
672
|
str | None,
|
|
562
|
-
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.
|
|
673
|
+
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."),
|
|
563
674
|
] = None,
|
|
564
675
|
duration: Annotated[str | None, Field(description="Duration bucket such as 6-8. Omit to use the template.")] = None,
|
|
565
676
|
avatar_profile_id: Annotated[
|
|
@@ -572,7 +683,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
572
683
|
] = None,
|
|
573
684
|
render_only: Annotated[
|
|
574
685
|
bool | None,
|
|
575
|
-
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."),
|
|
686
|
+
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."),
|
|
576
687
|
] = None,
|
|
577
688
|
thumbnail_prompt: Annotated[
|
|
578
689
|
str | None,
|
|
@@ -621,7 +732,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
621
732
|
|
|
622
733
|
@mcp.tool(
|
|
623
734
|
title="Get narration",
|
|
624
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
735
|
+
annotations=ToolAnnotations(title="Get narration", read_only_hint=True, open_world_hint=False),
|
|
625
736
|
)
|
|
626
737
|
def get_narration(
|
|
627
738
|
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
|
|
@@ -634,7 +745,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
634
745
|
|
|
635
746
|
@mcp.tool(
|
|
636
747
|
title="Get graphics catalog",
|
|
637
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
748
|
+
annotations=ToolAnnotations(title="Get graphics catalog", read_only_hint=True, open_world_hint=False),
|
|
638
749
|
)
|
|
639
750
|
def get_kind_catalog(
|
|
640
751
|
format: Annotated[str | None, Field(description="faceless_documentary, faceless_top_10, avatar_video or vector_explainer")] = None,
|
|
@@ -651,7 +762,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
651
762
|
|
|
652
763
|
@mcp.tool(
|
|
653
764
|
title="Check plan",
|
|
654
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
765
|
+
annotations=ToolAnnotations(title="Check plan", read_only_hint=True, open_world_hint=False),
|
|
655
766
|
)
|
|
656
767
|
def check_plan(
|
|
657
768
|
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
|
|
@@ -663,7 +774,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
663
774
|
except Exception as exc:
|
|
664
775
|
return _err(exc)
|
|
665
776
|
|
|
666
|
-
@mcp.tool(
|
|
777
|
+
@mcp.tool(
|
|
778
|
+
title="Lock plan",
|
|
779
|
+
annotations=ToolAnnotations(title="Lock plan", read_only_hint=False, destructive_hint=False),
|
|
780
|
+
)
|
|
667
781
|
def lock_plan(
|
|
668
782
|
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
|
|
669
783
|
plan: Annotated[dict[str, Any], Field(description="The plan that check_plan reported valid")],
|
|
@@ -676,7 +790,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
676
790
|
|
|
677
791
|
@mcp.tool(
|
|
678
792
|
title="Get locked plan",
|
|
679
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
793
|
+
annotations=ToolAnnotations(title="Get locked plan", read_only_hint=True, open_world_hint=False),
|
|
680
794
|
)
|
|
681
795
|
def get_plan(
|
|
682
796
|
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID")],
|
|
@@ -689,7 +803,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
689
803
|
|
|
690
804
|
@mcp.tool(
|
|
691
805
|
title="Review the built video",
|
|
692
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
806
|
+
annotations=ToolAnnotations(title="Review the built video", read_only_hint=True, open_world_hint=False),
|
|
693
807
|
)
|
|
694
808
|
def get_plan_review(
|
|
695
809
|
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status ready_for_edit)")],
|
|
@@ -702,13 +816,13 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
702
816
|
|
|
703
817
|
@mcp.tool(
|
|
704
818
|
title="Upload plan media",
|
|
705
|
-
annotations=ToolAnnotations(read_only_hint=False, open_world_hint=False),
|
|
819
|
+
annotations=ToolAnnotations(title="Upload plan media", read_only_hint=False, destructive_hint=False, open_world_hint=False),
|
|
706
820
|
)
|
|
707
821
|
def upload_plan_media(
|
|
708
822
|
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID")],
|
|
709
823
|
path: Annotated[
|
|
710
824
|
str,
|
|
711
|
-
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
|
|
825
|
+
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."),
|
|
712
826
|
],
|
|
713
827
|
) -> dict[str, Any]:
|
|
714
828
|
"""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."""
|
|
@@ -717,9 +831,88 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
717
831
|
except Exception as exc:
|
|
718
832
|
return _err(exc)
|
|
719
833
|
|
|
834
|
+
@mcp.tool(
|
|
835
|
+
title="Start media upload",
|
|
836
|
+
annotations=ToolAnnotations(title="Start media upload", read_only_hint=False, destructive_hint=False, open_world_hint=False),
|
|
837
|
+
)
|
|
838
|
+
def start_media_upload(
|
|
839
|
+
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID")],
|
|
840
|
+
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).")],
|
|
841
|
+
size: Annotated[int, Field(gt=0, description="The file's size in bytes (e.g. `wc -c < file` or `stat`).")],
|
|
842
|
+
content_type: Annotated[str | None, Field(description="MIME type; omit to infer it from the file name.")] = None,
|
|
843
|
+
) -> dict[str, Any]:
|
|
844
|
+
"""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."""
|
|
845
|
+
try:
|
|
846
|
+
out = _client().start_media_upload(job_id, filename=filename, size=size, content_type=content_type)
|
|
847
|
+
out["next"] = "PUT every part to its url, then finish_media_upload(job_id, key, upload_id)."
|
|
848
|
+
return out
|
|
849
|
+
except Exception as exc:
|
|
850
|
+
return _err(exc)
|
|
851
|
+
|
|
852
|
+
@mcp.tool(
|
|
853
|
+
title="Finish media upload",
|
|
854
|
+
annotations=ToolAnnotations(title="Finish media upload", read_only_hint=False, destructive_hint=False, open_world_hint=False),
|
|
855
|
+
)
|
|
856
|
+
def finish_media_upload(
|
|
857
|
+
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID")],
|
|
858
|
+
key: Annotated[str, Field(min_length=1, description="key from start_media_upload")],
|
|
859
|
+
upload_id: Annotated[str, Field(min_length=1, description="upload_id from start_media_upload")],
|
|
860
|
+
) -> dict[str, Any]:
|
|
861
|
+
"""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)."""
|
|
862
|
+
try:
|
|
863
|
+
return _client().finish_media_upload(job_id, key=key, upload_id=upload_id)
|
|
864
|
+
except Exception as exc:
|
|
865
|
+
return _err(exc)
|
|
866
|
+
|
|
867
|
+
@mcp.tool(
|
|
868
|
+
title="Abort media upload",
|
|
869
|
+
annotations=ToolAnnotations(title="Abort media upload", read_only_hint=False, destructive_hint=True, open_world_hint=False),
|
|
870
|
+
)
|
|
871
|
+
def abort_media_upload(
|
|
872
|
+
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID")],
|
|
873
|
+
key: Annotated[str, Field(min_length=1, description="key from start_media_upload")],
|
|
874
|
+
upload_id: Annotated[str, Field(min_length=1, description="upload_id from start_media_upload")],
|
|
875
|
+
) -> dict[str, Any]:
|
|
876
|
+
"""Cancel an upload you will not finish (frees the parts already sent)."""
|
|
877
|
+
try:
|
|
878
|
+
return _client().abort_media_upload(job_id, key=key, upload_id=upload_id)
|
|
879
|
+
except Exception as exc:
|
|
880
|
+
return _err(exc)
|
|
881
|
+
|
|
882
|
+
@mcp.tool(
|
|
883
|
+
title="Start voiceover upload",
|
|
884
|
+
annotations=ToolAnnotations(title="Start voiceover upload", read_only_hint=False, destructive_hint=False, open_world_hint=False),
|
|
885
|
+
)
|
|
886
|
+
def start_voiceover_upload(
|
|
887
|
+
filename: Annotated[str, Field(min_length=1, description="The narration file's name: MP3, M4A, WAV, OGG, FLAC or WEBM (up to 200 MB).")],
|
|
888
|
+
size: Annotated[int, Field(gt=0, description="The file's size in bytes.")],
|
|
889
|
+
content_type: Annotated[str | None, Field(description="MIME type; omit to infer it from the file name.")] = None,
|
|
890
|
+
) -> dict[str, Any]:
|
|
891
|
+
"""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."""
|
|
892
|
+
try:
|
|
893
|
+
out = _client().start_voiceover_upload(filename=filename, size=size, content_type=content_type)
|
|
894
|
+
out["next"] = "PUT every part to its url, then finish_voiceover_upload(key, upload_id) for the voiceover_url."
|
|
895
|
+
return out
|
|
896
|
+
except Exception as exc:
|
|
897
|
+
return _err(exc)
|
|
898
|
+
|
|
899
|
+
@mcp.tool(
|
|
900
|
+
title="Finish voiceover upload",
|
|
901
|
+
annotations=ToolAnnotations(title="Finish voiceover upload", read_only_hint=False, destructive_hint=False, open_world_hint=False),
|
|
902
|
+
)
|
|
903
|
+
def finish_voiceover_upload(
|
|
904
|
+
key: Annotated[str, Field(min_length=1, description="key from start_voiceover_upload")],
|
|
905
|
+
upload_id: Annotated[str, Field(min_length=1, description="upload_id from start_voiceover_upload")],
|
|
906
|
+
) -> dict[str, Any]:
|
|
907
|
+
"""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."""
|
|
908
|
+
try:
|
|
909
|
+
return _client().finish_voiceover_upload(key=key, upload_id=upload_id)
|
|
910
|
+
except Exception as exc:
|
|
911
|
+
return _err(exc)
|
|
912
|
+
|
|
720
913
|
@mcp.tool(
|
|
721
914
|
title="Get plan sourcing report",
|
|
722
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
915
|
+
annotations=ToolAnnotations(title="Get plan sourcing report", read_only_hint=True, open_world_hint=False),
|
|
723
916
|
)
|
|
724
917
|
def get_plan_report(
|
|
725
918
|
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (after continue_job)")],
|
|
@@ -732,7 +925,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
732
925
|
|
|
733
926
|
@mcp.tool(
|
|
734
927
|
title="Get job",
|
|
735
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
928
|
+
annotations=ToolAnnotations(title="Get job", read_only_hint=True, open_world_hint=False),
|
|
736
929
|
)
|
|
737
930
|
def get_job(
|
|
738
931
|
job_id: Annotated[str, Field(min_length=8, description="Job / video UUID")],
|
|
@@ -745,7 +938,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
745
938
|
|
|
746
939
|
@mcp.tool(
|
|
747
940
|
title="List jobs",
|
|
748
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
941
|
+
annotations=ToolAnnotations(title="List jobs", read_only_hint=True, open_world_hint=False),
|
|
749
942
|
)
|
|
750
943
|
def list_jobs(
|
|
751
944
|
status: Annotated[str | None, Field(description="Optional status filter")] = None,
|
|
@@ -760,7 +953,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
760
953
|
|
|
761
954
|
@mcp.tool(
|
|
762
955
|
title="Cancel job",
|
|
763
|
-
annotations=ToolAnnotations(destructive_hint=True, open_world_hint=False),
|
|
956
|
+
annotations=ToolAnnotations(title="Cancel job", read_only_hint=False, destructive_hint=True, open_world_hint=False),
|
|
764
957
|
)
|
|
765
958
|
def cancel_job(
|
|
766
959
|
job_id: Annotated[str, Field(min_length=8, description="Job UUID")],
|
|
@@ -773,12 +966,12 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
773
966
|
|
|
774
967
|
@mcp.tool(
|
|
775
968
|
title="Open editor project",
|
|
776
|
-
annotations=ToolAnnotations(read_only_hint=False, open_world_hint=False),
|
|
969
|
+
annotations=ToolAnnotations(title="Open editor project", read_only_hint=False, destructive_hint=False, open_world_hint=False),
|
|
777
970
|
)
|
|
778
971
|
def open_editor_project(
|
|
779
972
|
job_id: Annotated[str, Field(min_length=8, description="Completed video job id")],
|
|
780
973
|
) -> dict[str, Any]:
|
|
781
|
-
"""Open (or create) the timeline editor project for a completed video job. Returns project id, revision
|
|
974
|
+
"""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."""
|
|
782
975
|
try:
|
|
783
976
|
return _client().open_editor_project(job_id)
|
|
784
977
|
except Exception as exc:
|
|
@@ -786,18 +979,21 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
786
979
|
|
|
787
980
|
@mcp.tool(
|
|
788
981
|
title="Get editor project",
|
|
789
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
982
|
+
annotations=ToolAnnotations(title="Get editor project", read_only_hint=True, open_world_hint=False),
|
|
790
983
|
)
|
|
791
984
|
def get_editor_project(
|
|
792
985
|
project_id: Annotated[int, Field(description="Editor project id")],
|
|
793
986
|
) -> dict[str, Any]:
|
|
794
|
-
"""Current revision, compact timeline
|
|
987
|
+
"""Current revision, compact timeline, latest render and export_credits_due (what render_project would charge now) of an editor project."""
|
|
795
988
|
try:
|
|
796
989
|
return _client().get_editor_project(project_id)
|
|
797
990
|
except Exception as exc:
|
|
798
991
|
return _err(exc)
|
|
799
992
|
|
|
800
|
-
@mcp.tool(
|
|
993
|
+
@mcp.tool(
|
|
994
|
+
title="Run Cliptude Agent",
|
|
995
|
+
annotations=ToolAnnotations(title="Run Cliptude Agent", read_only_hint=False, destructive_hint=False),
|
|
996
|
+
)
|
|
801
997
|
def run_agent(
|
|
802
998
|
project_id: Annotated[int, Field(description="Editor project id")],
|
|
803
999
|
prompt: Annotated[str, Field(min_length=1, description="Edit request in plain English")],
|
|
@@ -817,7 +1013,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
817
1013
|
|
|
818
1014
|
@mcp.tool(
|
|
819
1015
|
title="Get agent run",
|
|
820
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
1016
|
+
annotations=ToolAnnotations(title="Get agent run", read_only_hint=True, open_world_hint=False),
|
|
821
1017
|
)
|
|
822
1018
|
def get_agent_run(
|
|
823
1019
|
project_id: Annotated[int, Field(description="Editor project id")],
|
|
@@ -829,7 +1025,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
829
1025
|
except Exception as exc:
|
|
830
1026
|
return _err(exc)
|
|
831
1027
|
|
|
832
|
-
@mcp.tool(
|
|
1028
|
+
@mcp.tool(
|
|
1029
|
+
title="Cancel agent run",
|
|
1030
|
+
annotations=ToolAnnotations(title="Cancel agent run", read_only_hint=False, destructive_hint=True),
|
|
1031
|
+
)
|
|
833
1032
|
def cancel_agent_run(
|
|
834
1033
|
project_id: Annotated[int, Field(description="Editor project id")],
|
|
835
1034
|
run_id: Annotated[str, Field(min_length=8, description="Agent run id")],
|
|
@@ -840,11 +1039,14 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
840
1039
|
except Exception as exc:
|
|
841
1040
|
return _err(exc)
|
|
842
1041
|
|
|
843
|
-
@mcp.tool(
|
|
1042
|
+
@mcp.tool(
|
|
1043
|
+
title="Render editor project",
|
|
1044
|
+
annotations=ToolAnnotations(title="Render editor project", read_only_hint=False, destructive_hint=False),
|
|
1045
|
+
)
|
|
844
1046
|
def render_project(
|
|
845
1047
|
project_id: Annotated[int, Field(description="Editor project id")],
|
|
846
1048
|
) -> dict[str, Any]:
|
|
847
|
-
"""Render the edited timeline to a new MP4 (
|
|
1049
|
+
"""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."""
|
|
848
1050
|
try:
|
|
849
1051
|
return _client().render_project(project_id)
|
|
850
1052
|
except Exception as exc:
|
|
@@ -852,12 +1054,12 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
852
1054
|
|
|
853
1055
|
@mcp.tool(
|
|
854
1056
|
title="Get render",
|
|
855
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
1057
|
+
annotations=ToolAnnotations(title="Get render", read_only_hint=True, open_world_hint=False),
|
|
856
1058
|
)
|
|
857
1059
|
def get_render(
|
|
858
1060
|
render_id: Annotated[int, Field(description="Editor render id")],
|
|
859
1061
|
) -> dict[str, Any]:
|
|
860
|
-
"""Status of an editor render; output_url when completed."""
|
|
1062
|
+
"""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."""
|
|
861
1063
|
try:
|
|
862
1064
|
return _client().get_render(render_id)
|
|
863
1065
|
except Exception as exc:
|
|
@@ -865,7 +1067,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
865
1067
|
|
|
866
1068
|
@mcp.tool(
|
|
867
1069
|
title="Get account",
|
|
868
|
-
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
1070
|
+
annotations=ToolAnnotations(title="Get account", read_only_hint=True, open_world_hint=False),
|
|
869
1071
|
)
|
|
870
1072
|
def get_account() -> dict[str, Any]:
|
|
871
1073
|
"""Plan, credits remaining, and concurrency in use."""
|
package/package.json
CHANGED
package/pyproject.toml
CHANGED