@cliptude/cli 0.1.11 → 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 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`.
@@ -270,13 +270,13 @@ def main(argv: list[str] | None = None) -> None:
270
270
  g.add_argument(
271
271
  "--voiceover",
272
272
  default="",
273
- 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.",
274
274
  )
275
- 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.")
276
276
  g.add_argument(
277
277
  "--talking-head",
278
278
  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.",
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.",
280
280
  )
281
281
  g.add_argument(
282
282
  "--duration",
@@ -679,6 +679,49 @@ class CliptudeClient:
679
679
  pass
680
680
  raise
681
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
+
682
725
  def get_narration(self, job_id: str) -> Any:
683
726
  """Numbered sentences (with word timings), digest, pricing and template flags of a plan job."""
684
727
  return self.request("GET", f"/api/v1/jobs/{job_id}/narration")
@@ -814,7 +857,7 @@ class CliptudeClient:
814
857
  return self.request("POST", f"/api/v1/editor-projects/{project_id}/agent/runs/{run_id}/cancel")
815
858
 
816
859
  def render_project(self, project_id: int | str) -> Any:
817
- """Render the edited timeline to a new MP4 (charged like an editor export)."""
860
+ """Render the edited timeline to a new MP4: free the first time, then 10% of the original generation."""
818
861
  return self.request("POST", f"/api/v1/editor-projects/{project_id}/render")
819
862
 
820
863
  def get_render(self, render_id: int | str) -> Any:
@@ -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(title="Create template")
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")],
@@ -253,7 +256,7 @@ def build_server(*, with_http_auth: bool = False):
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(title="Upload vector character")
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(title="Delete vector character")
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(title="Create video job")
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."
@@ -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. Use this on remote hosts, which cannot send a local file. Omit prompt/script and voiceover_path."),
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,
@@ -492,7 +504,10 @@ def build_server(*, with_http_auth: bool = False):
492
504
  except Exception as exc:
493
505
  return _err(exc)
494
506
 
495
- @mcp.tool(title="Create script job")
507
+ @mcp.tool(
508
+ title="Create script job",
509
+ annotations=ToolAnnotations(title="Create script job", read_only_hint=False, destructive_hint=False),
510
+ )
496
511
  def create_script(
497
512
  template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
498
513
  title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
@@ -514,7 +529,10 @@ def build_server(*, with_http_auth: bool = False):
514
529
  except Exception as exc:
515
530
  return _err(exc)
516
531
 
517
- @mcp.tool(title="Create voiceover job")
532
+ @mcp.tool(
533
+ title="Create voiceover job",
534
+ annotations=ToolAnnotations(title="Create voiceover job", read_only_hint=False, destructive_hint=False),
535
+ )
518
536
  def create_voiceover(
519
537
  template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
520
538
  title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
@@ -540,7 +558,10 @@ def build_server(*, with_http_auth: bool = False):
540
558
  except Exception as exc:
541
559
  return _err(exc)
542
560
 
543
- @mcp.tool(title="Continue job into video")
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
+ )
544
565
  def continue_job(
545
566
  job_id: Annotated[str, Field(min_length=8, description="Completed script or voiceover job UUID, or a plan job with a locked plan")],
546
567
  ) -> dict[str, Any]:
@@ -550,16 +571,19 @@ def build_server(*, with_http_auth: bool = False):
550
571
  except Exception as exc:
551
572
  return _err(exc)
552
573
 
553
- @mcp.tool(title="Create agent-planned job")
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
+ )
554
578
  def create_plan_job(
555
579
  template_id: Annotated[str, Field(min_length=8, description="Saved Faceless Documentary, Faceless Top 10, Avatar Video or Vector Explainer template UUID")],
556
580
  title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
557
581
  prompt: Annotated[str | None, Field(description="Topic/brief; Cliptude writes the narration. Never the video title.")] = None,
558
582
  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,
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,
560
584
  voiceover_url: Annotated[
561
585
  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. Use this on remote hosts, which cannot send a local file. Omit prompt/script and voiceover_path."),
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."),
563
587
  ] = None,
564
588
  duration: Annotated[str | None, Field(description="Duration bucket such as 6-8. Omit to use the template.")] = None,
565
589
  avatar_profile_id: Annotated[
@@ -572,7 +596,7 @@ def build_server(*, with_http_auth: bool = False):
572
596
  ] = None,
573
597
  render_only: Annotated[
574
598
  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."),
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."),
576
600
  ] = None,
577
601
  thumbnail_prompt: Annotated[
578
602
  str | None,
@@ -621,7 +645,7 @@ def build_server(*, with_http_auth: bool = False):
621
645
 
622
646
  @mcp.tool(
623
647
  title="Get narration",
624
- annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
648
+ annotations=ToolAnnotations(title="Get narration", read_only_hint=True, open_world_hint=False),
625
649
  )
626
650
  def get_narration(
627
651
  job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
@@ -634,7 +658,7 @@ def build_server(*, with_http_auth: bool = False):
634
658
 
635
659
  @mcp.tool(
636
660
  title="Get graphics catalog",
637
- 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),
638
662
  )
639
663
  def get_kind_catalog(
640
664
  format: Annotated[str | None, Field(description="faceless_documentary, faceless_top_10, avatar_video or vector_explainer")] = None,
@@ -651,7 +675,7 @@ def build_server(*, with_http_auth: bool = False):
651
675
 
652
676
  @mcp.tool(
653
677
  title="Check plan",
654
- annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
678
+ annotations=ToolAnnotations(title="Check plan", read_only_hint=True, open_world_hint=False),
655
679
  )
656
680
  def check_plan(
657
681
  job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
@@ -663,7 +687,10 @@ def build_server(*, with_http_auth: bool = False):
663
687
  except Exception as exc:
664
688
  return _err(exc)
665
689
 
666
- @mcp.tool(title="Lock plan")
690
+ @mcp.tool(
691
+ title="Lock plan",
692
+ annotations=ToolAnnotations(title="Lock plan", read_only_hint=False, destructive_hint=False),
693
+ )
667
694
  def lock_plan(
668
695
  job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
669
696
  plan: Annotated[dict[str, Any], Field(description="The plan that check_plan reported valid")],
@@ -676,7 +703,7 @@ def build_server(*, with_http_auth: bool = False):
676
703
 
677
704
  @mcp.tool(
678
705
  title="Get locked plan",
679
- 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),
680
707
  )
681
708
  def get_plan(
682
709
  job_id: Annotated[str, Field(min_length=8, description="Plan job UUID")],
@@ -689,7 +716,7 @@ def build_server(*, with_http_auth: bool = False):
689
716
 
690
717
  @mcp.tool(
691
718
  title="Review the built video",
692
- 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),
693
720
  )
694
721
  def get_plan_review(
695
722
  job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status ready_for_edit)")],
@@ -702,13 +729,13 @@ def build_server(*, with_http_auth: bool = False):
702
729
 
703
730
  @mcp.tool(
704
731
  title="Upload plan media",
705
- 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),
706
733
  )
707
734
  def upload_plan_media(
708
735
  job_id: Annotated[str, Field(min_length=8, description="Plan job UUID")],
709
736
  path: Annotated[
710
737
  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 — remote hosts should use the CLI (cliptude upload-media) or give a public file link as media.url."),
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."),
712
739
  ],
713
740
  ) -> dict[str, Any]:
714
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."""
@@ -717,9 +744,88 @@ def build_server(*, with_http_auth: bool = False):
717
744
  except Exception as exc:
718
745
  return _err(exc)
719
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
+
720
826
  @mcp.tool(
721
827
  title="Get plan sourcing report",
722
- 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),
723
829
  )
724
830
  def get_plan_report(
725
831
  job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (after continue_job)")],
@@ -732,7 +838,7 @@ def build_server(*, with_http_auth: bool = False):
732
838
 
733
839
  @mcp.tool(
734
840
  title="Get job",
735
- annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
841
+ annotations=ToolAnnotations(title="Get job", read_only_hint=True, open_world_hint=False),
736
842
  )
737
843
  def get_job(
738
844
  job_id: Annotated[str, Field(min_length=8, description="Job / video UUID")],
@@ -745,7 +851,7 @@ def build_server(*, with_http_auth: bool = False):
745
851
 
746
852
  @mcp.tool(
747
853
  title="List jobs",
748
- annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
854
+ annotations=ToolAnnotations(title="List jobs", read_only_hint=True, open_world_hint=False),
749
855
  )
750
856
  def list_jobs(
751
857
  status: Annotated[str | None, Field(description="Optional status filter")] = None,
@@ -760,7 +866,7 @@ def build_server(*, with_http_auth: bool = False):
760
866
 
761
867
  @mcp.tool(
762
868
  title="Cancel job",
763
- 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),
764
870
  )
765
871
  def cancel_job(
766
872
  job_id: Annotated[str, Field(min_length=8, description="Job UUID")],
@@ -773,12 +879,12 @@ def build_server(*, with_http_auth: bool = False):
773
879
 
774
880
  @mcp.tool(
775
881
  title="Open editor project",
776
- 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),
777
883
  )
778
884
  def open_editor_project(
779
885
  job_id: Annotated[str, Field(min_length=8, description="Completed video job id")],
780
886
  ) -> dict[str, Any]:
781
- """Open (or create) the timeline editor project for a completed video job. Returns project id, revision and a compact timeline (item id, type, start_s, end_s, text) to reference in run_agent."""
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."""
782
888
  try:
783
889
  return _client().open_editor_project(job_id)
784
890
  except Exception as exc:
@@ -786,18 +892,21 @@ def build_server(*, with_http_auth: bool = False):
786
892
 
787
893
  @mcp.tool(
788
894
  title="Get editor project",
789
- 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),
790
896
  )
791
897
  def get_editor_project(
792
898
  project_id: Annotated[int, Field(description="Editor project id")],
793
899
  ) -> dict[str, Any]:
794
- """Current revision, compact timeline and latest render of an editor project."""
900
+ """Current revision, compact timeline, latest render and export_credits_due (what render_project would charge now) of an editor project."""
795
901
  try:
796
902
  return _client().get_editor_project(project_id)
797
903
  except Exception as exc:
798
904
  return _err(exc)
799
905
 
800
- @mcp.tool(title="Run Cliptude Agent")
906
+ @mcp.tool(
907
+ title="Run Cliptude Agent",
908
+ annotations=ToolAnnotations(title="Run Cliptude Agent", read_only_hint=False, destructive_hint=False),
909
+ )
801
910
  def run_agent(
802
911
  project_id: Annotated[int, Field(description="Editor project id")],
803
912
  prompt: Annotated[str, Field(min_length=1, description="Edit request in plain English")],
@@ -817,7 +926,7 @@ def build_server(*, with_http_auth: bool = False):
817
926
 
818
927
  @mcp.tool(
819
928
  title="Get agent run",
820
- 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),
821
930
  )
822
931
  def get_agent_run(
823
932
  project_id: Annotated[int, Field(description="Editor project id")],
@@ -829,7 +938,10 @@ def build_server(*, with_http_auth: bool = False):
829
938
  except Exception as exc:
830
939
  return _err(exc)
831
940
 
832
- @mcp.tool(title="Cancel agent run")
941
+ @mcp.tool(
942
+ title="Cancel agent run",
943
+ annotations=ToolAnnotations(title="Cancel agent run", read_only_hint=False, destructive_hint=True),
944
+ )
833
945
  def cancel_agent_run(
834
946
  project_id: Annotated[int, Field(description="Editor project id")],
835
947
  run_id: Annotated[str, Field(min_length=8, description="Agent run id")],
@@ -840,11 +952,14 @@ def build_server(*, with_http_auth: bool = False):
840
952
  except Exception as exc:
841
953
  return _err(exc)
842
954
 
843
- @mcp.tool(title="Render editor project")
955
+ @mcp.tool(
956
+ title="Render editor project",
957
+ annotations=ToolAnnotations(title="Render editor project", read_only_hint=False, destructive_hint=False),
958
+ )
844
959
  def render_project(
845
960
  project_id: Annotated[int, Field(description="Editor project id")],
846
961
  ) -> dict[str, Any]:
847
- """Render the edited timeline to a new MP4 (charged like an editor export). Poll get_render for output_url."""
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."""
848
963
  try:
849
964
  return _client().render_project(project_id)
850
965
  except Exception as exc:
@@ -852,12 +967,12 @@ def build_server(*, with_http_auth: bool = False):
852
967
 
853
968
  @mcp.tool(
854
969
  title="Get render",
855
- annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
970
+ annotations=ToolAnnotations(title="Get render", read_only_hint=True, open_world_hint=False),
856
971
  )
857
972
  def get_render(
858
973
  render_id: Annotated[int, Field(description="Editor render id")],
859
974
  ) -> dict[str, Any]:
860
- """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."""
861
976
  try:
862
977
  return _client().get_render(render_id)
863
978
  except Exception as exc:
@@ -865,7 +980,7 @@ def build_server(*, with_http_auth: bool = False):
865
980
 
866
981
  @mcp.tool(
867
982
  title="Get account",
868
- annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
983
+ annotations=ToolAnnotations(title="Get account", read_only_hint=True, open_world_hint=False),
869
984
  )
870
985
  def get_account() -> dict[str, Any]:
871
986
  """Plan, credits remaining, and concurrency in use."""
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cliptude/cli",
3
- "version": "0.1.11",
3
+ "version": "0.1.12",
4
4
  "description": "Cliptude CLI — generate videos from saved templates.",
5
5
  "homepage": "https://github.com/cliptude/cliptude#readme",
6
6
  "bin": {
package/pyproject.toml CHANGED
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "cliptude-mcp"
7
- version = "0.1.11"
7
+ version = "0.1.12"
8
8
  description = "Cliptude jobs CLI and MCP server (thin client of /api/v1)."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"