@cliptude/cli 0.1.7 → 0.1.9

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
@@ -6,7 +6,7 @@ Generate videos from a saved template. Same account and credits as cliptude.com.
6
6
 
7
7
  1. Install the CLI: run `npm i -g @cliptude/cli`.
8
8
  2. Authenticate: run `cliptude auth login` and complete the sign-in in the browser it opens.
9
- 3. Install the companion skills: run `npx skills add cliptude/cliptude --path mcp_server/skills`.
9
+ 3. Install the companion skills: run `npx skills add cliptude/cliptude`.
10
10
 
11
11
  From this repo without npm:
12
12
 
@@ -24,6 +24,9 @@ cliptude voices --provider elevenlabs
24
24
  cliptude template-create --name "TSMC doc" --format faceless_documentary --set voice_id=<id> --set voice_name=George --set generation_model=pro --set faceless_documentary_style=investigative
25
25
  cliptude template-create --name "TSMC doc" --format faceless_documentary --settings-file settings.json
26
26
  cliptude generate --template "Finance vector weekly" --title "Why index funds win" --prompt "why most retail traders underperform the S&P over 10 years, keep it for beginners" --duration 3-4
27
+ cliptude estimate --template "Finance vector weekly" --script-file script.txt
28
+ cliptude avatars --section mine
29
+ cliptude generate --template "My avatar weekly" --title "Episode one" --script-file script.txt --avatar 42
27
30
  cliptude generate --template "Finance vector weekly" --title "Why index funds win" --script-file script.txt
28
31
  cliptude generate --template "Finance vector weekly" --title "Why index funds win" --voiceover narration.mp3
29
32
  cliptude generate --template "My talking head" --title "Weekly recap" --talking-head clip.mp4
@@ -38,13 +41,15 @@ cliptude continue <job-id>
38
41
  cliptude status <job-id>
39
42
  ```
40
43
 
41
- No template yet? `template-create` makes one without the create wizard: pick a `voice_id` from `voices`, and see `template-options` for every other field, its choices and its default (unset fields take the wizard default). Values are validated like the wizard; uploads (custom music, avatars, characters) still need the wizard. MCP tools: `get_template_options`, `list_voices`, `create_template`.
44
+ No template yet? `template-create` makes one without the create wizard: pick a `voice_id` from `voices`, and see `template-options` for every other field, its choices and its default (unset fields take the wizard default). Values are validated like the wizard; uploads (custom music, avatars, characters) still need the wizard. MCP tools: `get_template_options`, `list_voices`, `create_template`. For Avatar Video, `avatars` (MCP `list_avatars`) lists your avatars; set one with `--set avatar_profile_id=<id>` on `template-create`, or override it per video with `--avatar <id>` (and `--avatar-engine iii|iv|v`) on `generate`, `plan-job` and `estimate`. The avatar's gender must match the voice. For Vector Explainer, `vector-characters` lists the built-in cast and your uploads, `vector-character-upload --name "Dr. Maya" --file maya.png` (or `--url`) adds your own, and `--set vector_character_id=<id>` on `template-create` (or `--vector-character <id>` on `generate` / `plan-job`) uses it. Motion: `--set vector_reveal_mode=none|video` on the template, or `--vector-motion none|video` on `generate`, `plan-job` and `estimate` (`none` = stills with camera moves, `video` = AI clips). Thumbnails: `--thumbnail-reference <YouTube link or image URL>` or `--thumbnail-prompt "<brief>"` on `template-create` sets the template's look; the same flags on `generate` and `plan-job` set one video's. With neither, each video picks a style reference for its own title.
45
+
46
+ To check the price first, `estimate` (MCP `estimate_credits`, REST `POST /api/v1/jobs/estimate`) takes the same template and prompt/script as `generate` (an upload as `--voiceover-seconds` / `--talking-head-seconds`) and returns the credits the job would need and whether the account has them. It creates and charges nothing.
42
47
 
43
48
  To revise a finished video, `editor` opens its timeline (item ids, times, text), `agent` asks Cliptude Agent for an edit (it charges agent credits; reference item ids with `--items`), and `render` exports a new MP4. MCP tools: `open_editor_project`, `get_editor_project`, `run_agent`, `get_agent_run`, `cancel_agent_run`, `render_project`, `get_render`.
44
49
 
45
50
  ### Agent-planned videos
46
51
 
47
- On Faceless Documentary, Faceless Top 10 and Avatar Video templates an agent can plan every visual and leave Cliptude
52
+ On Faceless Documentary, Faceless Top 10, Avatar Video and Vector Explainer templates an agent can plan every visual and leave Cliptude
48
53
  only the voicing, sourcing and rendering:
49
54
 
50
55
  1. `cliptude plan-job` (stops at `plan_ready`), `cliptude narration <job>`.
@@ -1,4 +1,4 @@
1
- """Tiny CLI wrapping /api/v1: auth | templates | template-create | template-options | voices | generate | editor | agent | render | script | voiceover | continue | status | jobs | account | cancel."""
1
+ """Tiny CLI wrapping /api/v1: auth | templates | template-create | template-options | voices | avatars | estimate | generate | editor | agent | render | script | voiceover | continue | status | jobs | account | cancel."""
2
2
 
3
3
  from __future__ import annotations
4
4
 
@@ -35,6 +35,34 @@ def _resolve_template_id(client: CliptudeClient, value: str) -> str:
35
35
  raise CliptudeApiError(f"Template not found: {value}")
36
36
 
37
37
 
38
+ def _add_thumbnail_args(parser: argparse.ArgumentParser, *, scope: str) -> None:
39
+ parser.add_argument(
40
+ "--thumbnail-prompt",
41
+ default="",
42
+ help=f"Thumbnail brief for {scope} (people, style, text). Not with --thumbnail-reference.",
43
+ )
44
+ parser.add_argument(
45
+ "--thumbnail-reference",
46
+ default="",
47
+ help=(
48
+ f"YouTube video link or https image whose thumbnail style {scope} copies. Without a brief or "
49
+ "reference, each video picks a reference for its own title."
50
+ ),
51
+ )
52
+
53
+
54
+ def _thumbnail_from_args(args) -> dict | None:
55
+ thumbnail = {
56
+ key: value.strip()
57
+ for key, value in (
58
+ ("custom_prompt", getattr(args, "thumbnail_prompt", "")),
59
+ ("reference_url", getattr(args, "thumbnail_reference", "")),
60
+ )
61
+ if value and value.strip()
62
+ }
63
+ return thumbnail or None
64
+
65
+
38
66
  def _parse_set_args(pairs: list[str]) -> dict:
39
67
  out = {}
40
68
  for pair in pairs:
@@ -85,7 +113,7 @@ def _run_auth(auth_cmd: str) -> None:
85
113
  print("Not authenticated. Run: cliptude auth login", file=sys.stderr)
86
114
  raise SystemExit(1)
87
115
  try:
88
- account = CliptudeClient().get_account()
116
+ account = CliptudeClient(client_kind="cli").get_account()
89
117
  except Exception as exc:
90
118
  _die(exc)
91
119
  email = account.get("email") if isinstance(account, dict) else None
@@ -139,6 +167,7 @@ def main(argv: list[str] | None = None) -> None:
139
167
  metavar="KEY=VALUE",
140
168
  help="One setting; VALUE is parsed as JSON when possible (true, 0.4, [\"a\"]), else a string. Repeatable.",
141
169
  )
170
+ _add_thumbnail_args(tc, scope="every video from this template")
142
171
 
143
172
  to = sub.add_parser("template-options", help="Fields, choices and defaults for template-create")
144
173
  to.add_argument("--format", required=True)
@@ -147,6 +176,48 @@ def main(argv: list[str] | None = None) -> None:
147
176
  vc.add_argument("--provider", default="elevenlabs", help="elevenlabs, minimax, cartesia, inworld, voicetory")
148
177
  vc.add_argument("--language", default="")
149
178
 
179
+ av = sub.add_parser("avatars", help="List avatars for Avatar Video (id for --avatar / avatar_profile_id)")
180
+ av.add_argument("--section", default="", choices=["", "mine", "builtin", "public", "favorites"])
181
+ av.add_argument("--search", default="", help="Part of the avatar's name")
182
+ av.add_argument("--gender", default="", choices=["", "male", "female"])
183
+ av.add_argument("--limit", type=int, default=50)
184
+
185
+ vcl = sub.add_parser("vector-characters", help="List Vector Explainer characters (built-in and your uploads)")
186
+ vcu = sub.add_parser(
187
+ "vector-character-upload",
188
+ help="Add your own Vector Explainer character from a local image or a public URL; prints its id",
189
+ )
190
+ vcu.add_argument("--name", required=True, help="Short name for the character")
191
+ vcu.add_argument("--file", default="", help="Local PNG, JPG or WEBP")
192
+ vcu.add_argument("--url", default="", help="Public https link to the image")
193
+ vcd = sub.add_parser("vector-character-delete", help="Delete one of your uploaded Vector Explainer characters")
194
+ vcd.add_argument("character_id")
195
+
196
+ est = sub.add_parser(
197
+ "estimate",
198
+ help="Credits a job would need (creates nothing)",
199
+ formatter_class=argparse.RawDescriptionHelpFormatter,
200
+ epilog=(
201
+ "example:\n"
202
+ ' cliptude estimate --template "Finance vector weekly" --script-file script.txt\n'
203
+ ' cliptude estimate --template "Finance vector weekly" --voiceover-seconds 3600'
204
+ ),
205
+ )
206
+ est.add_argument("--template", required=True, help="Template name or UUID")
207
+ est.add_argument("--prompt", default="")
208
+ est.add_argument("--script", default="")
209
+ est.add_argument("--script-file", default="")
210
+ est.add_argument("--duration", default="", help="Duration bucket, e.g. 6-8. Default: template (or from --script)")
211
+ est.add_argument("--voiceover-seconds", type=float, default=None, help="Length of the voiceover you would upload")
212
+ est.add_argument("--talking-head-seconds", type=float, default=None, help="Length of the talking-head video you would upload")
213
+ est.add_argument("--output", default="", choices=["", "video", "plan", "script", "voiceover"])
214
+ est.add_argument("--avatar-intro-only", action=argparse.BooleanOptionalAction, default=None)
215
+ est.add_argument("--avatar-ai-footage", action=argparse.BooleanOptionalAction, default=None)
216
+ est.add_argument("--avatar", type=int, default=None, help="Avatar Video: avatar id from `cliptude avatars`. Default: the template's avatar")
217
+ est.add_argument("--avatar-engine", default="", choices=["", "iii", "iv", "v"], help="Avatar Video: HeyGen engine. Default: the template's")
218
+ est.add_argument("--vector-motion", default="", choices=["", "none", "video"], help="Vector Explainer: price stills (none) or AI clips (video)")
219
+ est.add_argument("--render-only", action="store_true", help="Plan job where you bring the voiceover, pictures, clips and graphics (with --output plan --voiceover-seconds)")
220
+
150
221
  g = sub.add_parser(
151
222
  "generate",
152
223
  help="Start a job",
@@ -178,6 +249,7 @@ def main(argv: list[str] | None = None) -> None:
178
249
  default="",
179
250
  help="Path to a narration audio file (MP3, M4A, WAV, …). Transcribed; skips TTS. Do not combine with --prompt or --script.",
180
251
  )
252
+ g.add_argument("--voiceover-url", default="", help="Public https link to the narration audio; Cliptude downloads it.")
181
253
  g.add_argument(
182
254
  "--talking-head",
183
255
  default="",
@@ -202,10 +274,12 @@ def main(argv: list[str] | None = None) -> None:
202
274
  action=argparse.BooleanOptionalAction,
203
275
  default=None,
204
276
  help=(
205
- "Avatar Video: AI Image + AI Video instead of stock/YouTube. "
277
+ "Avatar Video: AI Image + AI Video instead of stock and web footage. "
206
278
  "Omit to use the template. Only valid for Avatar Video templates."
207
279
  ),
208
280
  )
281
+ g.add_argument("--avatar", type=int, default=None, help="Avatar Video: avatar id from `cliptude avatars`. Default: the template's avatar")
282
+ g.add_argument("--avatar-engine", default="", choices=["", "iii", "iv", "v"], help="Avatar Video: HeyGen engine. Default: the template's")
209
283
  g.add_argument(
210
284
  "--disable-animations",
211
285
  action=argparse.BooleanOptionalAction,
@@ -246,6 +320,9 @@ def main(argv: list[str] | None = None) -> None:
246
320
  metavar="SLUG",
247
321
  help="Exclude a transition (e.g. flip-horizontal) from auto-selection. Repeatable. Omit to use the template.",
248
322
  )
323
+ _add_thumbnail_args(g, scope="this video")
324
+ g.add_argument("--vector-motion", default="", choices=["", "none", "video"], help='Vector Explainer: "none" = stills with camera moves, "video" = AI clips. Default: the template\'s')
325
+ g.add_argument("--vector-character", default="", help='Vector Explainer: character id from `cliptude vector-characters`, or "none". Default: the template\'s')
249
326
 
250
327
  sc = sub.add_parser(
251
328
  "script",
@@ -314,13 +391,20 @@ def main(argv: list[str] | None = None) -> None:
314
391
  pj.add_argument("--script", default="")
315
392
  pj.add_argument("--script-file", default="")
316
393
  pj.add_argument("--voiceover", default="", help="Local audio to use as the narration (aligned, not re-voiced)")
394
+ pj.add_argument("--voiceover-url", default="", help="Public https link to the narration audio; Cliptude downloads it")
317
395
  pj.add_argument("--duration", default="", help="Wizard duration bucket, e.g. 6-8")
396
+ pj.add_argument("--avatar", type=int, default=None, help="Avatar Video: avatar id from `cliptude avatars`. Default: the template's avatar")
397
+ pj.add_argument("--avatar-engine", default="", choices=["", "iii", "iv", "v"], help="Avatar Video: HeyGen engine. Default: the template's")
398
+ pj.add_argument("--render-only", action="store_true", help="You bring everything (needs --voiceover); Cliptude only builds and renders, at the render-only rate")
399
+ _add_thumbnail_args(pj, scope="this video")
400
+ pj.add_argument("--vector-motion", default="", choices=["", "none", "video"], help='Vector Explainer: "none" = stills with camera moves, "video" = AI clips. Default: the template\'s')
401
+ pj.add_argument("--vector-character", default="", help='Vector Explainer: character id from `cliptude vector-characters`, or "none". Default: the template\'s')
318
402
 
319
403
  nr = sub.add_parser("narration", help="Numbered sentences and word timings of a plan_ready job")
320
404
  nr.add_argument("job_id")
321
405
 
322
406
  cat = sub.add_parser("catalog", help="Graphics an agent can place (kinds, types, overlay styles)")
323
- cat.add_argument("--format", default="", help="faceless_documentary, faceless_top_10 or avatar_video")
407
+ cat.add_argument("--format", default="", help="faceless_documentary, faceless_top_10, avatar_video or vector_explainer")
324
408
  cat.add_argument("--theme", default="")
325
409
  cat.add_argument("--compact", action="store_true", help="One summary line per graphic")
326
410
  cat.add_argument("--types", default="", help="Comma-separated types/styles for full entries")
@@ -337,6 +421,9 @@ def main(argv: list[str] | None = None) -> None:
337
421
  pv.add_argument("job_id")
338
422
  pr = sub.add_parser("plan-report", help="What sourcing used for each media request of the locked plan")
339
423
  pr.add_argument("job_id")
424
+ um = sub.add_parser("upload-media", help="Send a picture or clip you found to a plan job; prints its keep id for media.keep")
425
+ um.add_argument("job_id")
426
+ um.add_argument("path", help="Local JPG/PNG/WEBP/GIF (up to 15 MB) or MP4/MOV/WEBM/M4V (up to 300 MB)")
340
427
 
341
428
  ed = sub.add_parser("editor", help="Open the timeline editor project for a completed job (prints the timeline)")
342
429
  ed.add_argument("job_id")
@@ -392,7 +479,7 @@ def main(argv: list[str] | None = None) -> None:
392
479
  if args.cmd == "auth":
393
480
  _run_auth(args.auth_cmd)
394
481
  return
395
- client = CliptudeClient()
482
+ client = CliptudeClient(client_kind="cli")
396
483
  try:
397
484
  if args.cmd == "templates":
398
485
  _print(client.list_templates(limit=args.limit, offset=args.offset))
@@ -403,18 +490,56 @@ def main(argv: list[str] | None = None) -> None:
403
490
  if not isinstance(settings, dict):
404
491
  raise CliptudeApiError("--settings-file must contain a JSON object.")
405
492
  settings.update(_parse_set_args(args.set))
493
+ thumbnail = _thumbnail_from_args(args)
494
+ if thumbnail:
495
+ settings["thumbnail"] = thumbnail
406
496
  _print(client.create_template(name=args.name, format=args.format, settings=settings))
407
497
  elif args.cmd == "template-options":
408
498
  _print(client.template_options(args.format))
409
499
  elif args.cmd == "voices":
410
500
  _print(client.list_voices(provider=args.provider, language=args.language or None))
501
+ elif args.cmd == "vector-characters":
502
+ _print(client.list_vector_characters())
503
+ elif args.cmd == "vector-character-upload":
504
+ if bool(args.file) == bool(args.url):
505
+ raise CliptudeApiError("Give --file or --url (one of them).")
506
+ _print(client.upload_vector_character(
507
+ image_path=args.file or None, image_url=args.url or None, name=args.name,
508
+ ))
509
+ elif args.cmd == "vector-character-delete":
510
+ _print(client.delete_vector_character(args.character_id))
511
+ elif args.cmd == "avatars":
512
+ _print(client.list_avatars(
513
+ section=args.section or None, search=args.search or None,
514
+ gender=args.gender or None, limit=args.limit,
515
+ ))
516
+ elif args.cmd == "estimate":
517
+ script = args.script
518
+ if args.script_file:
519
+ script = Path(args.script_file).read_text(encoding="utf-8")
520
+ _print(client.estimate_credits(
521
+ template_id=_resolve_template_id(client, args.template),
522
+ prompt=args.prompt or None,
523
+ script=script or None,
524
+ duration=args.duration or None,
525
+ voiceover_seconds=args.voiceover_seconds,
526
+ talking_head_seconds=args.talking_head_seconds,
527
+ output=args.output or None,
528
+ avatar_intro_only=args.avatar_intro_only,
529
+ avatar_ai_footage=args.avatar_ai_footage,
530
+ avatar_profile_id=args.avatar,
531
+ avatar_engine=args.avatar_engine or None,
532
+ render_only=args.render_only or None,
533
+ vector_reveal_mode=args.vector_motion or None,
534
+ ))
411
535
  elif args.cmd == "generate":
412
536
  script = args.script
413
537
  if args.script_file:
414
538
  script = Path(args.script_file).read_text(encoding="utf-8")
415
539
  voiceover = (args.voiceover or "").strip()
540
+ voiceover_url = (args.voiceover_url or "").strip()
416
541
  talking_head = (args.talking_head or "").strip()
417
- if talking_head and voiceover:
542
+ if talking_head and (voiceover or voiceover_url):
418
543
  raise CliptudeApiError("Use --talking-head or --voiceover, not both.")
419
544
  if talking_head and (args.prompt or script):
420
545
  raise CliptudeApiError(
@@ -438,15 +563,21 @@ def main(argv: list[str] | None = None) -> None:
438
563
  script=script or None,
439
564
  duration=(args.duration or None),
440
565
  voiceover_path=voiceover or None,
566
+ voiceover_url=voiceover_url or None,
441
567
  talking_head_path=talking_head or None,
442
568
  avatar_intro_only=args.avatar_intro_only,
443
569
  avatar_ai_footage=args.avatar_ai_footage,
570
+ avatar_profile_id=args.avatar,
571
+ avatar_engine=args.avatar_engine or None,
444
572
  disable_animations=args.disable_animations,
445
573
  disable_overlays=args.disable_overlays,
446
574
  disable_effects=args.disable_effects,
447
575
  disable_transitions=args.disable_transitions,
448
576
  excluded_animation_types=args.excluded_animation_types,
449
577
  excluded_transition_kinds=args.excluded_transition_kinds,
578
+ thumbnail=_thumbnail_from_args(args),
579
+ vector_character_id=args.vector_character or None,
580
+ vector_reveal_mode=args.vector_motion or None,
450
581
  ))
451
582
  elif args.cmd == "script":
452
583
  if not (args.prompt or "").strip():
@@ -479,8 +610,9 @@ def main(argv: list[str] | None = None) -> None:
479
610
  if args.script_file:
480
611
  script = Path(args.script_file).read_text(encoding="utf-8")
481
612
  voiceover = (args.voiceover or "").strip()
482
- if not (args.prompt or "").strip() and not (script or "").strip() and not voiceover:
483
- raise CliptudeApiError("Provide --prompt, --script / --script-file, or --voiceover.")
613
+ voiceover_url = (args.voiceover_url or "").strip()
614
+ if not (args.prompt or "").strip() and not (script or "").strip() and not voiceover and not voiceover_url:
615
+ raise CliptudeApiError("Provide --prompt, --script / --script-file, --voiceover or --voiceover-url.")
484
616
  template_id = _resolve_template_id(client, args.template)
485
617
  _print(client.create_job(
486
618
  template_id=template_id,
@@ -488,8 +620,15 @@ def main(argv: list[str] | None = None) -> None:
488
620
  prompt=args.prompt or None,
489
621
  script=script or None,
490
622
  voiceover_path=voiceover or None,
623
+ voiceover_url=voiceover_url or None,
491
624
  duration=(args.duration or None),
492
625
  output="plan",
626
+ avatar_profile_id=args.avatar,
627
+ avatar_engine=args.avatar_engine or None,
628
+ render_only=args.render_only or None,
629
+ thumbnail=_thumbnail_from_args(args),
630
+ vector_character_id=args.vector_character or None,
631
+ vector_reveal_mode=args.vector_motion or None,
493
632
  ))
494
633
  elif args.cmd == "narration":
495
634
  _print(client.get_narration(args.job_id))
@@ -508,6 +647,8 @@ def main(argv: list[str] | None = None) -> None:
508
647
  _print(client.get_plan_review(args.job_id))
509
648
  elif args.cmd == "plan-report":
510
649
  _print(client.get_plan_report(args.job_id))
650
+ elif args.cmd == "upload-media":
651
+ _print(client.upload_plan_media(args.job_id, args.path))
511
652
  elif args.cmd == "download-voiceover":
512
653
  dest = Path(args.out)
513
654
  client.download_voiceover_file(args.job_id, dest)
@@ -3,6 +3,7 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  import json
6
+ import mimetypes
6
7
  import os
7
8
  from contextvars import ContextVar
8
9
  from pathlib import Path
@@ -129,8 +130,14 @@ def _avatar_job_fields(
129
130
  avatar_ai_footage: bool | None,
130
131
  *,
131
132
  as_strings: bool = False,
133
+ avatar_profile_id: int | str | None = None,
134
+ avatar_engine: str | None = None,
132
135
  ) -> dict[str, Any]:
133
136
  fields: dict[str, Any] = {}
137
+ if avatar_profile_id not in (None, ""):
138
+ fields["avatar_profile_id"] = str(avatar_profile_id) if as_strings else int(avatar_profile_id)
139
+ if avatar_engine:
140
+ fields["avatar_engine"] = str(avatar_engine).strip().lower()
134
141
  if avatar_intro_only is not None:
135
142
  fields["avatar_intro_only"] = (
136
143
  ("true" if avatar_intro_only else "false") if as_strings else bool(avatar_intro_only)
@@ -142,6 +149,14 @@ def _avatar_job_fields(
142
149
  return fields
143
150
 
144
151
 
152
+ def _thumbnail_job_field(thumbnail: dict[str, str] | None, *, as_string: bool = False) -> dict[str, Any]:
153
+ """create_job's per-job thumbnail ({custom_prompt} or {reference_url}); multipart sends it as JSON text."""
154
+ cleaned = {k: str(v).strip() for k, v in (thumbnail or {}).items() if v is not None and str(v).strip()}
155
+ if not cleaned:
156
+ return {}
157
+ return {"thumbnail": json.dumps(cleaned) if as_string else cleaned}
158
+
159
+
145
160
  def _motion_control_job_fields(
146
161
  *,
147
162
  disable_animations: bool | None = None,
@@ -173,8 +188,16 @@ def _motion_control_job_fields(
173
188
 
174
189
 
175
190
  class CliptudeClient:
176
- def __init__(self, base_url: str | None = None, api_key: str | None = None, timeout: float = 30.0):
191
+ def __init__(
192
+ self,
193
+ base_url: str | None = None,
194
+ api_key: str | None = None,
195
+ timeout: float = 30.0,
196
+ client_kind: str | None = None,
197
+ ):
177
198
  self.base_url = (base_url or resolve_base_url()).rstrip("/")
199
+ # "cli" or "mcp": sent as X-Cliptude-Client so Cliptude records where a job was started.
200
+ self.client_kind = (client_kind or os.environ.get("CLIPTUDE_CLIENT_KIND") or "").strip().lower()
178
201
  self.api_key = _resolve_token(api_key)
179
202
  self.timeout = timeout
180
203
  self._session_file = not bool(
@@ -191,6 +214,8 @@ class CliptudeClient:
191
214
  "Accept": "application/json",
192
215
  **django_proxy_headers(self.base_url),
193
216
  }
217
+ if self.client_kind:
218
+ headers["X-Cliptude-Client"] = self.client_kind
194
219
  if json_content:
195
220
  headers["Content-Type"] = "application/json"
196
221
  return headers
@@ -266,17 +291,31 @@ class CliptudeClient:
266
291
  script: str | None = None,
267
292
  duration: str | None = None,
268
293
  voiceover_path: str | Path | None = None,
294
+ voiceover_url: str | None = None,
269
295
  talking_head_path: str | Path | None = None,
270
296
  output: str | None = None,
271
297
  avatar_intro_only: bool | None = None,
272
298
  avatar_ai_footage: bool | None = None,
299
+ avatar_profile_id: int | str | None = None,
300
+ avatar_engine: str | None = None,
273
301
  disable_animations: bool | None = None,
274
302
  disable_overlays: bool | None = None,
275
303
  disable_effects: bool | None = None,
276
304
  disable_transitions: bool | None = None,
277
305
  excluded_animation_types: list[str] | None = None,
278
306
  excluded_transition_kinds: list[str] | None = None,
307
+ render_only: bool | None = None,
308
+ thumbnail: dict[str, str] | None = None,
309
+ vector_character_id: str | None = None,
310
+ vector_reveal_mode: str | None = None,
279
311
  ) -> Any:
312
+ if voiceover_path and voiceover_url:
313
+ raise CliptudeApiError("Give voiceover_path or voiceover_url, not both.")
314
+ if render_only and ((output or "").strip().lower() != "plan" or not (voiceover_path or voiceover_url)):
315
+ raise CliptudeApiError(
316
+ "render_only is a plan job with your own narration: pass output=\"plan\" and a voiceover "
317
+ "(voiceover_path, or voiceover_url for a public link)."
318
+ )
280
319
  motion_fields = _motion_control_job_fields(
281
320
  disable_animations=disable_animations,
282
321
  disable_overlays=disable_overlays,
@@ -328,12 +367,20 @@ class CliptudeClient:
328
367
  disable_transitions=disable_transitions,
329
368
  excluded_animation_types=excluded_animation_types,
330
369
  excluded_transition_kinds=excluded_transition_kinds,
370
+ thumbnail=thumbnail,
331
371
  )
332
372
  if vo_path:
333
373
  extra_data = {
334
- **_avatar_job_fields(avatar_intro_only, avatar_ai_footage, as_strings=True),
374
+ **_avatar_job_fields(
375
+ avatar_intro_only, avatar_ai_footage, as_strings=True,
376
+ avatar_profile_id=avatar_profile_id, avatar_engine=avatar_engine,
377
+ ),
335
378
  **motion_fields_str,
336
379
  **({"output": output_kind} if output_kind == "plan" else {}),
380
+ **({"render_only": "true"} if render_only else {}),
381
+ **_thumbnail_job_field(thumbnail, as_string=True),
382
+ **({"vector_character_id": str(vector_character_id)} if vector_character_id else {}),
383
+ **({"vector_reveal_mode": str(vector_reveal_mode)} if vector_reveal_mode else {}),
337
384
  }
338
385
  return self._create_job_multipart(
339
386
  template_id=template_id,
@@ -353,8 +400,21 @@ class CliptudeClient:
353
400
  body["duration"] = duration
354
401
  if output_kind and output_kind != "video":
355
402
  body["output"] = output_kind
356
- body.update(_avatar_job_fields(avatar_intro_only, avatar_ai_footage))
403
+ if voiceover_url:
404
+ # A public link to the narration: Cliptude downloads it (remote hosts cannot upload a file).
405
+ body["voiceover_url"] = str(voiceover_url).strip()
406
+ if render_only:
407
+ body["render_only"] = True
408
+ body.update(_avatar_job_fields(
409
+ avatar_intro_only, avatar_ai_footage,
410
+ avatar_profile_id=avatar_profile_id, avatar_engine=avatar_engine,
411
+ ))
357
412
  body.update(motion_fields)
413
+ body.update(_thumbnail_job_field(thumbnail))
414
+ if vector_character_id:
415
+ body["vector_character_id"] = str(vector_character_id)
416
+ if vector_reveal_mode:
417
+ body["vector_reveal_mode"] = str(vector_reveal_mode)
358
418
  return self.request("POST", "/api/v1/jobs", json_body=body)
359
419
 
360
420
  def _raise_http(self, resp, *, payload=None) -> None:
@@ -450,6 +510,7 @@ class CliptudeClient:
450
510
  disable_transitions: bool | None = None,
451
511
  excluded_animation_types: list[str] | None = None,
452
512
  excluded_transition_kinds: list[str] | None = None,
513
+ thumbnail: dict[str, str] | None = None,
453
514
  ) -> Any:
454
515
  motion_extra = _motion_control_job_fields(
455
516
  disable_animations=disable_animations,
@@ -483,6 +544,7 @@ class CliptudeClient:
483
544
  extra_data = {
484
545
  **_avatar_job_fields(avatar_intro_only, avatar_ai_footage, as_strings=True),
485
546
  **motion_extra,
547
+ **_thumbnail_job_field(thumbnail, as_string=True),
486
548
  }
487
549
  return self._create_job_multipart(
488
550
  template_id=template_id,
@@ -500,6 +562,7 @@ class CliptudeClient:
500
562
  extra_data = {
501
563
  **_avatar_job_fields(avatar_intro_only, avatar_ai_footage, as_strings=True),
502
564
  **motion_extra,
565
+ **_thumbnail_job_field(thumbnail, as_string=True),
503
566
  }
504
567
  return self._create_job_multipart(
505
568
  template_id=template_id,
@@ -527,6 +590,7 @@ class CliptudeClient:
527
590
  "talking_head_duration": str(duration),
528
591
  }
529
592
  body.update(_avatar_job_fields(avatar_intro_only, avatar_ai_footage))
593
+ body.update(_thumbnail_job_field(thumbnail))
530
594
  body.update(
531
595
  _motion_control_job_fields(
532
596
  disable_animations=disable_animations,
@@ -540,23 +604,27 @@ class CliptudeClient:
540
604
  return self.request("POST", "/api/v1/jobs", json_body=body)
541
605
 
542
606
  def _upload_talking_head_parts(self, path: Path, init: dict[str, Any]) -> None:
607
+ self._upload_parts(path, init, "/api/v1/uploads/talking-head/sign-parts", "talking head")
608
+
609
+ def _upload_parts(self, path: Path, init: dict[str, Any], sign_path: str, label: str) -> None:
610
+ """PUT the file straight to R2, part by part, on URLs Cliptude signs (no R2 keys here)."""
543
611
  key = str(init.get("key") or "").strip()
544
612
  upload_id = str(init.get("upload_id") or "").strip()
545
613
  part_size = int(init.get("part_size") or 0)
546
614
  part_count = int(init.get("part_count") or 0)
547
615
  if not key or not upload_id or part_size <= 0 or part_count <= 0:
548
- raise CliptudeApiError("Talking head upload init returned an incomplete plan.")
616
+ raise CliptudeApiError(f"The {label} upload init returned an incomplete plan.")
549
617
  with path.open("rb") as fh:
550
618
  for start in range(0, part_count, 50):
551
619
  nums = list(range(start + 1, min(start + 50, part_count) + 1))
552
620
  signed = self.request(
553
621
  "POST",
554
- "/api/v1/uploads/talking-head/sign-parts",
622
+ sign_path,
555
623
  json_body={"key": key, "upload_id": upload_id, "part_numbers": nums},
556
624
  )
557
625
  urls = (signed or {}).get("urls") if isinstance(signed, dict) else None
558
626
  if not isinstance(urls, dict):
559
- raise CliptudeApiError("Could not sign talking head upload parts.")
627
+ raise CliptudeApiError(f"Could not sign {label} upload parts.")
560
628
  for num in nums:
561
629
  url = urls.get(str(num))
562
630
  if not url:
@@ -568,7 +636,7 @@ class CliptudeClient:
568
636
  raise CliptudeApiError(str(exc)) from exc
569
637
  if resp.status_code >= 400:
570
638
  raise CliptudeApiError(
571
- f"Failed to upload talking head part {num}.",
639
+ f"Failed to upload {label} part {num}.",
572
640
  status=resp.status_code,
573
641
  )
574
642
 
@@ -581,6 +649,32 @@ class CliptudeClient:
581
649
 
582
650
  # Agent-planned videos -------------------------------------------------------------------------
583
651
 
652
+ def upload_plan_media(self, job_id: str, path: str | Path) -> Any:
653
+ """Send a picture or clip you found to a plan job; returns {keep, file, media_type, size} for media.keep."""
654
+ path = Path(path)
655
+ if not path.is_file():
656
+ raise CliptudeApiError(f"File not found: {path}")
657
+ base = f"/api/v1/jobs/{job_id}/media"
658
+ init = self.request(
659
+ "POST",
660
+ f"{base}/init",
661
+ json_body={
662
+ "filename": path.name,
663
+ "size": path.stat().st_size,
664
+ "content_type": mimetypes.guess_type(path.name)[0] or "application/octet-stream",
665
+ },
666
+ )
667
+ body = {"key": (init or {}).get("key"), "upload_id": (init or {}).get("upload_id")}
668
+ try:
669
+ self._upload_parts(path, init, f"{base}/sign-parts", "media")
670
+ return self.request("POST", f"{base}/complete", json_body=body)
671
+ except Exception:
672
+ try:
673
+ self.request("POST", f"{base}/abort", json_body=body)
674
+ except Exception:
675
+ pass
676
+ raise
677
+
584
678
  def get_narration(self, job_id: str) -> Any:
585
679
  """Numbered sentences (with word timings), digest, pricing and template flags of a plan job."""
586
680
  return self.request("GET", f"/api/v1/jobs/{job_id}/narration")
@@ -724,3 +818,105 @@ class CliptudeClient:
724
818
 
725
819
  def get_account(self) -> Any:
726
820
  return self.request("GET", "/api/v1/account")
821
+
822
+ def estimate_credits(
823
+ self,
824
+ *,
825
+ template_id: str,
826
+ prompt: str | None = None,
827
+ script: str | None = None,
828
+ duration: str | None = None,
829
+ voiceover_seconds: float | None = None,
830
+ talking_head_seconds: float | None = None,
831
+ output: str | None = None,
832
+ avatar_intro_only: bool | None = None,
833
+ avatar_ai_footage: bool | None = None,
834
+ avatar_profile_id: int | str | None = None,
835
+ avatar_engine: str | None = None,
836
+ render_only: bool | None = None,
837
+ vector_reveal_mode: str | None = None,
838
+ ) -> Any:
839
+ """Credits a job would need; creates nothing."""
840
+ body: dict[str, Any] = {"template_id": template_id}
841
+ if render_only:
842
+ body["render_only"] = True
843
+ for key, value in (
844
+ ("prompt", prompt),
845
+ ("script", script),
846
+ ("duration", duration),
847
+ ("voiceover_seconds", voiceover_seconds),
848
+ ("talking_head_seconds", talking_head_seconds),
849
+ ("output", output),
850
+ ("vector_reveal_mode", vector_reveal_mode),
851
+ ):
852
+ if value is not None and value != "":
853
+ body[key] = value
854
+ body.update(_avatar_job_fields(
855
+ avatar_intro_only, avatar_ai_footage,
856
+ avatar_profile_id=avatar_profile_id, avatar_engine=avatar_engine,
857
+ ))
858
+ return self.request("POST", "/api/v1/jobs/estimate", json_body=body)
859
+
860
+ def list_vector_characters(self) -> Any:
861
+ """Vector Explainer characters: the built-in cast and your uploads (ids for vector_character_id)."""
862
+ return self.request("GET", "/api/v1/vector-characters")
863
+
864
+ def upload_vector_character(
865
+ self,
866
+ *,
867
+ image_path: str | Path | None = None,
868
+ image_url: str | None = None,
869
+ name: str = "",
870
+ _retried: bool = False,
871
+ ) -> Any:
872
+ """Add a Vector Explainer character from a local image or a public image URL; returns its id."""
873
+ if bool(image_path) == bool((image_url or "").strip()):
874
+ raise CliptudeApiError("Give image_path or image_url (one of them).")
875
+ if image_url:
876
+ return self.request(
877
+ "POST", "/api/v1/vector-characters", json_body={"image_url": image_url.strip(), "name": name}
878
+ )
879
+ path = Path(image_path)
880
+ if not path.is_file():
881
+ raise CliptudeApiError(f"Character image not found: {path}")
882
+ mime = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
883
+ try:
884
+ with path.open("rb") as fh:
885
+ resp = httpx.post(
886
+ f"{self.base_url}/api/v1/vector-characters",
887
+ headers=self._headers(json_content=False),
888
+ data={"name": name},
889
+ files={"image": (path.name, fh, mime)},
890
+ timeout=max(self.timeout, 120.0),
891
+ )
892
+ except httpx.HTTPError as exc:
893
+ raise CliptudeApiError(str(exc)) from exc
894
+ if resp.status_code == 401 and not _retried and self._maybe_refresh():
895
+ return self.upload_vector_character(image_path=image_path, name=name, _retried=True)
896
+ try:
897
+ payload = resp.json()
898
+ except ValueError:
899
+ payload = {"error": resp.text}
900
+ if resp.status_code >= 400:
901
+ self._raise_http(resp, payload=payload)
902
+ return payload
903
+
904
+ def delete_vector_character(self, character_id: str) -> Any:
905
+ """Delete one of your uploaded characters (refused while a template uses it)."""
906
+ return self.request("DELETE", f"/api/v1/vector-characters/{character_id}")
907
+
908
+ def list_avatars(
909
+ self,
910
+ *,
911
+ section: str | None = None,
912
+ search: str | None = None,
913
+ gender: str | None = None,
914
+ limit: int = 50,
915
+ offset: int = 0,
916
+ ) -> Any:
917
+ """Avatars for Avatar Video (ids for avatar_profile_id)."""
918
+ params: dict[str, Any] = {"limit": limit, "offset": offset}
919
+ for key, value in (("section", section), ("search", search), ("gender", gender)):
920
+ if value:
921
+ params[key] = value
922
+ return self.request("GET", "/api/v1/avatars", params=params)
@@ -26,7 +26,17 @@ def _client() -> CliptudeClient:
26
26
  set_request_token(token)
27
27
  except Exception:
28
28
  pass
29
- return CliptudeClient(api_key=token)
29
+ return CliptudeClient(api_key=token, client_kind="mcp")
30
+
31
+
32
+ def _thumbnail_arg(prompt: str | None, reference_url: str | None) -> dict[str, str] | None:
33
+ """create_job's thumbnail object from the flat tool arguments (None keeps the template's)."""
34
+ thumbnail = {
35
+ key: value.strip()
36
+ for key, value in (("custom_prompt", prompt), ("reference_url", reference_url))
37
+ if value and value.strip()
38
+ }
39
+ return thumbnail or None
30
40
 
31
41
 
32
42
  def _err(exc: Exception) -> dict[str, Any]:
@@ -96,6 +106,8 @@ def build_server(*, with_http_auth: bool = False):
96
106
  "prompt, script, voiceover_path (uploaded audio, transcribed; skips TTS), "
97
107
  "or talking_head_path (presenter video on a Talking Head template). "
98
108
  "create_job returns immediately; poll get_job until completed or failed. "
109
+ "To quote a price or check the balance first, call estimate_credits with the same "
110
+ "template and prompt/script (an upload as voiceover_seconds); it creates nothing. "
99
111
  "For a script only (no MP4), use create_script. For narration audio only, "
100
112
  "use create_voiceover. To turn a completed script or voiceover job into an MP4 "
101
113
  "on the same job id, use continue_job (do not create a second job). "
@@ -105,6 +117,8 @@ def build_server(*, with_http_auth: bool = False):
105
117
  "If they provide a voiceover file, pass voiceover_path and omit prompt/script. "
106
118
  "If they provide a talking-head recording, pass talking_head_path and omit "
107
119
  "prompt/script/voiceover_path (template format must be talking_head). "
120
+ "Avatar Video: list_avatars gives avatar ids; put one in create_template settings as "
121
+ "avatar_profile_id (with the voice), or pass avatar_profile_id on create_job to override. "
108
122
  "Avatar Video templates may include avatar_intro_only "
109
123
  "(Avatar Intro Only) and avatar_ai_footage (AI Image + AI Video); pass those "
110
124
  "on create_job to override the template, or omit them to keep the template. "
@@ -187,7 +201,12 @@ def build_server(*, with_http_auth: bool = False):
187
201
  description=(
188
202
  "Wizard settings: voice_id, voice_name, voice_provider plus any field from "
189
203
  "get_template_options (unset fields take the wizard defaults). "
190
- "Optional thumbnail: {custom_prompt}."
204
+ "Avatar Video: avatar_profile_id from list_avatars (gender must match the voice). "
205
+ "Vector Explainer: vector_character_id from get_template_options (vector_character.choices: "
206
+ "a built-in id such as nova, or one of the user's uploaded figures); omit it for no character. "
207
+ "Optional thumbnail: {reference_url} (a YouTube video link or https image whose style every "
208
+ "thumbnail copies) or {custom_prompt} (a standing brief: people, style, branding; each video "
209
+ "still sets its own subject and text). Omit it and each job picks a reference for its title."
191
210
  )
192
211
  ),
193
212
  ],
@@ -198,6 +217,131 @@ def build_server(*, with_http_auth: bool = False):
198
217
  except Exception as exc:
199
218
  return _err(exc)
200
219
 
220
+ @mcp.tool(
221
+ title="Estimate credits",
222
+ annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
223
+ )
224
+ def estimate_credits(
225
+ template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
226
+ prompt: Annotated[str | None, Field(description="Topic/brief, as you would send to create_job.")] = None,
227
+ script: Annotated[str | None, Field(description="Spoken narration, as you would send to create_job. Its length sets the estimate.")] = None,
228
+ duration: Annotated[
229
+ str | None,
230
+ Field(description="Duration bucket such as 6-8. Omit to use the template (or estimate from script)."),
231
+ ] = None,
232
+ voiceover_seconds: Annotated[
233
+ float | None,
234
+ Field(gt=0, description="Length of the voiceover you would upload. Uploaded voiceovers bill at the lowest voice rate. Do not also send prompt or script."),
235
+ ] = None,
236
+ talking_head_seconds: Annotated[
237
+ float | None,
238
+ Field(gt=0, description="Length of the talking-head video you would upload (Talking Head templates only)."),
239
+ ] = None,
240
+ output: Annotated[
241
+ str | None,
242
+ Field(description='"video" (default), "plan", "script" or "voiceover" — the output you would request.'),
243
+ ] = None,
244
+ avatar_intro_only: Annotated[bool | None, Field(description="Avatar Video only, as in create_job.")] = None,
245
+ avatar_ai_footage: Annotated[bool | None, Field(description="Avatar Video only, as in create_job.")] = None,
246
+ avatar_profile_id: Annotated[
247
+ int | None,
248
+ Field(description="Avatar Video only: avatar id from list_avatars. Omit to use the template's avatar."),
249
+ ] = None,
250
+ avatar_engine: Annotated[
251
+ str | None,
252
+ Field(description='Avatar Video only: "iii", "iv" or "v" (list_avatars shows which each avatar supports). Omit to keep the template.'),
253
+ ] = None,
254
+ render_only: Annotated[
255
+ 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."),
257
+ ] = None,
258
+ vector_reveal_mode: Annotated[
259
+ str | None,
260
+ Field(description='Vector Explainer only: "none" (stills with camera moves) or "video" (AI clips), to price a job that overrides the template.'),
261
+ ] = None,
262
+ ) -> dict[str, Any]:
263
+ """Credits a job would need before you create it, with the same pricing as create_job. Creates and charges nothing.
264
+
265
+ Returns credits_required (what is held to start; the final charge after render is usually lower),
266
+ credits_estimate (before the safety buffer), credits_per_minute, estimated_seconds, voice_source for
267
+ voice-priced formats, narration_credits for plan jobs, credits_available and enough_credits.
268
+ Use it to quote the user a price or check the balance before create_job."""
269
+ try:
270
+ return _client().estimate_credits(
271
+ template_id=template_id,
272
+ prompt=prompt,
273
+ script=script,
274
+ duration=duration,
275
+ voiceover_seconds=voiceover_seconds,
276
+ talking_head_seconds=talking_head_seconds,
277
+ output=output,
278
+ avatar_intro_only=avatar_intro_only,
279
+ avatar_ai_footage=avatar_ai_footage,
280
+ avatar_profile_id=avatar_profile_id,
281
+ avatar_engine=avatar_engine,
282
+ render_only=render_only,
283
+ vector_reveal_mode=vector_reveal_mode,
284
+ )
285
+ except Exception as exc:
286
+ return _err(exc)
287
+
288
+ @mcp.tool(
289
+ title="List avatars",
290
+ annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
291
+ )
292
+ def list_avatars(
293
+ section: Annotated[
294
+ str | None,
295
+ Field(description='"mine" (photo avatars the user created), "builtin", "public" or "favorites". Omit for all.'),
296
+ ] = None,
297
+ search: Annotated[str | None, Field(description="Part of the avatar's name.")] = None,
298
+ gender: Annotated[str | None, Field(description='"male" or "female" to match the voice. Omit for all.')] = None,
299
+ limit: Annotated[int, Field(ge=1, le=100)] = 50,
300
+ offset: Annotated[int, Field(ge=0)] = 0,
301
+ ) -> dict[str, Any]:
302
+ """Avatars the user can put in an Avatar Video: id, name, section, gender, engines, thumbnail_url. Pass an id as avatar_profile_id to create_template (in settings), create_job, create_plan_job or estimate_credits. The avatar's gender must match the voice."""
303
+ try:
304
+ return _client().list_avatars(section=section, search=search, gender=gender, limit=limit, offset=offset)
305
+ except Exception as exc:
306
+ return _err(exc)
307
+
308
+ @mcp.tool(
309
+ title="List vector characters",
310
+ annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
311
+ )
312
+ def list_vector_characters() -> dict[str, Any]:
313
+ """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."""
314
+ try:
315
+ return _client().list_vector_characters()
316
+ except Exception as exc:
317
+ return _err(exc)
318
+
319
+ @mcp.tool(title="Upload vector character")
320
+ def upload_vector_character(
321
+ name: Annotated[str, Field(min_length=1, max_length=120, description="A short name for the character, e.g. 'Dr. Maya'")],
322
+ image_path: Annotated[str | None, Field(description="Local PNG, JPG or WEBP file. Stdio / local MCP only.")] = None,
323
+ image_url: Annotated[str | None, Field(description="Public https link to the image (use on remote hosts).")] = None,
324
+ ) -> dict[str, Any]:
325
+ """Add the user's own Vector Explainer character and return its id (use it as vector_character_id). Use a picture the user supplied, or one you made for them: in that case show it to the user and upload only after they approve it. Best results: one full-body, front-facing character in flat vector style on a plain or transparent background, at least 1024 px, no text. It appears in the Cliptude wizard too."""
326
+ try:
327
+ path = (image_path or "").strip() or None
328
+ url = (image_url or "").strip() or None
329
+ if bool(path) == bool(url):
330
+ return {"error": "Give image_path or image_url (one of them)."}
331
+ return _client().upload_vector_character(image_path=path, image_url=url, name=name)
332
+ except Exception as exc:
333
+ return _err(exc)
334
+
335
+ @mcp.tool(title="Delete vector character")
336
+ def delete_vector_character(
337
+ character_id: Annotated[str, Field(min_length=8, description="Uploaded character id from list_vector_characters")],
338
+ ) -> dict[str, Any]:
339
+ """Delete one of the user's uploaded characters (built-in ones cannot be deleted). Refused while a saved template uses it. Only when the user asks."""
340
+ try:
341
+ return _client().delete_vector_character(character_id)
342
+ except Exception as exc:
343
+ return _err(exc)
344
+
201
345
  @mcp.tool(title="Create video job")
202
346
  def create_job(
203
347
  template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
@@ -242,11 +386,19 @@ def build_server(*, with_http_auth: bool = False):
242
386
  bool | None,
243
387
  Field(
244
388
  description=(
245
- "Avatar Video only: AI Image + AI Video instead of stock/YouTube. "
389
+ "Avatar Video only: AI Image + AI Video instead of stock and web footage. "
246
390
  "Omit to use the saved template. Other formats reject this field."
247
391
  ),
248
392
  ),
249
393
  ] = None,
394
+ avatar_profile_id: Annotated[
395
+ int | None,
396
+ Field(description="Avatar Video only: avatar id from list_avatars. Omit to use the template's avatar."),
397
+ ] = None,
398
+ avatar_engine: Annotated[
399
+ str | None,
400
+ Field(description='Avatar Video only: "iii", "iv" or "v" (list_avatars shows which each avatar supports). Omit to keep the template.'),
401
+ ] = None,
250
402
  disable_animations: Annotated[
251
403
  bool | None,
252
404
  Field(description="True = no animated text reveals or motion graphics. Omit to use the saved template."),
@@ -271,14 +423,37 @@ def build_server(*, with_http_auth: bool = False):
271
423
  list[str] | None,
272
424
  Field(description="Transition slugs to exclude from auto-selection, e.g. 'flip-horizontal', 'film-burn'. Omit to use the saved template."),
273
425
  ] = None,
426
+ voiceover_url: Annotated[
427
+ 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."),
429
+ ] = None,
430
+ thumbnail_prompt: Annotated[
431
+ str | None,
432
+ Field(description="This video's thumbnail brief (subject, people, text, style), up to 2000 characters. Replaces the template's thumbnail for this job. Omit to use the template; omit thumbnail_reference_url too."),
433
+ ] = None,
434
+ thumbnail_reference_url: Annotated[
435
+ str | None,
436
+ Field(description="A YouTube video link or https image whose thumbnail style to copy for this job (the content still comes from this video). Omit to use the template's; without one, Cliptude picks a reference for the title. Not with thumbnail_prompt."),
437
+ ] = None,
438
+ vector_character_id: Annotated[
439
+ str | None,
440
+ Field(description='Vector Explainer only: a character id from list_vector_characters (built-in or uploaded), or "none", for this video. Omit to use the template\'s.'),
441
+ ] = None,
442
+ vector_reveal_mode: Annotated[
443
+ str | None,
444
+ Field(description='Vector Explainer only: "none" = drawn stills with camera moves (Ken Burns), "video" = every picture beat animated as an AI clip (costs more; check estimate_credits). Omit to use the template\'s.'),
445
+ ] = None,
274
446
  ) -> dict[str, Any]:
275
447
  """Start generation and return a job id immediately. Do not wait for the MP4. Poll get_job. Provide prompt, script, voiceover_path, or talking_head_path. Never copy the title into prompt; for a topic-only request write a spoken script after web search and pass script. Uploaded audio or talking-head video is transcribed. Avatar Video: optional avatar_intro_only and avatar_ai_footage override the template. Any format: optional disable_animations/disable_overlays/disable_effects/disable_transitions and excluded_animation_types/excluded_transition_kinds override the template's motion & effects settings."""
276
448
  try:
277
449
  vo = (voiceover_path or "").strip() or None
450
+ vo_url = (voiceover_url or "").strip() or None
278
451
  th = (talking_head_path or "").strip() or None
279
- if vo and th:
452
+ if vo and vo_url:
453
+ return {"error": "Give voiceover_path or voiceover_url, not both."}
454
+ if (vo or vo_url) and th:
280
455
  return {"error": "Upload either a talking head video or a voiceover — not both."}
281
- if (vo or th) and ((prompt or "").strip() or (script or "").strip()):
456
+ if (vo or vo_url or th) and ((prompt or "").strip() or (script or "").strip()):
282
457
  kind = "talking head video" if th else "voiceover"
283
458
  return {
284
459
  "error": (
@@ -293,15 +468,21 @@ def build_server(*, with_http_auth: bool = False):
293
468
  script=script,
294
469
  duration=duration,
295
470
  voiceover_path=vo,
471
+ voiceover_url=vo_url,
296
472
  talking_head_path=th,
297
473
  avatar_intro_only=avatar_intro_only,
298
474
  avatar_ai_footage=avatar_ai_footage,
475
+ avatar_profile_id=avatar_profile_id,
476
+ avatar_engine=avatar_engine,
299
477
  disable_animations=disable_animations,
300
478
  disable_overlays=disable_overlays,
301
479
  disable_effects=disable_effects,
302
480
  disable_transitions=disable_transitions,
303
481
  excluded_animation_types=excluded_animation_types,
304
482
  excluded_transition_kinds=excluded_transition_kinds,
483
+ thumbnail=_thumbnail_arg(thumbnail_prompt, thumbnail_reference_url),
484
+ vector_character_id=vector_character_id,
485
+ vector_reveal_mode=vector_reveal_mode,
305
486
  )
306
487
  except Exception as exc:
307
488
  return _err(exc)
@@ -366,25 +547,64 @@ def build_server(*, with_http_auth: bool = False):
366
547
 
367
548
  @mcp.tool(title="Create agent-planned job")
368
549
  def create_plan_job(
369
- template_id: Annotated[str, Field(min_length=8, description="Saved Faceless Documentary, Faceless Top 10 or Avatar Video template UUID")],
550
+ template_id: Annotated[str, Field(min_length=8, description="Saved Faceless Documentary, Faceless Top 10, Avatar Video or Vector Explainer template UUID")],
370
551
  title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
371
552
  prompt: Annotated[str | None, Field(description="Topic/brief; Cliptude writes the narration. Never the video title.")] = None,
372
553
  script: Annotated[str | None, Field(description="Spoken narration to voice as-is. Omit prompt when you pass this.")] = None,
373
- voiceover_path: Annotated[str | None, Field(description="Local audio file to use as the narration (aligned, not re-voiced). Omit prompt/script.")] = None,
554
+ voiceover_path: Annotated[str | None, Field(description="Local audio file to use as the narration (aligned, not re-voiced). Omit prompt/script. Stdio / local MCP only.")] = None,
555
+ voiceover_url: Annotated[
556
+ str | None,
557
+ Field(description="Public https link to the narration audio (MP3, M4A, WAV, OGG, FLAC, WEBM; up to 200 MB). Cliptude downloads it and uses it like an uploaded voiceover. Use this on remote hosts, which cannot send a local file. Omit prompt/script and voiceover_path."),
558
+ ] = None,
374
559
  duration: Annotated[str | None, Field(description="Duration bucket such as 6-8. Omit to use the template.")] = None,
560
+ avatar_profile_id: Annotated[
561
+ int | None,
562
+ Field(description="Avatar Video only: avatar id from list_avatars. Omit to use the template's avatar."),
563
+ ] = None,
564
+ avatar_engine: Annotated[
565
+ str | None,
566
+ Field(description='Avatar Video only: "iii", "iv" or "v" (list_avatars shows which each avatar supports). Omit to keep the template.'),
567
+ ] = None,
568
+ render_only: Annotated[
569
+ bool | None,
570
+ Field(description="Render-only plan job: you bring the voiceover (voiceover_path, or voiceover_url on a remote host), every picture and clip (url, or keep from upload_plan_media) and the graphics; Cliptude searches, writes, voices and generates nothing and charges only the render-only rate per minute."),
571
+ ] = None,
572
+ thumbnail_prompt: Annotated[
573
+ str | None,
574
+ Field(description="This video's thumbnail brief (subject, people, text, style), up to 2000 characters. Replaces the template's thumbnail for this job. Omit to use the template; omit thumbnail_reference_url too."),
575
+ ] = None,
576
+ thumbnail_reference_url: Annotated[
577
+ str | None,
578
+ Field(description="A YouTube video link or https image whose thumbnail style to copy for this job (the content still comes from this video). Omit to use the template's; without one, Cliptude picks a reference for the title. Not with thumbnail_prompt."),
579
+ ] = None,
580
+ vector_character_id: Annotated[
581
+ str | None,
582
+ Field(description='Vector Explainer only: a character id from list_vector_characters (built-in or uploaded), or "none", for this video. Omit to use the template\'s.'),
583
+ ] = None,
584
+ vector_reveal_mode: Annotated[
585
+ str | None,
586
+ Field(description='Vector Explainer only: "none" = drawn stills with camera moves (Ken Burns), "video" = every picture beat animated as an AI clip (costs more; check estimate_credits). Omit to use the template\'s.'),
587
+ ] = None,
375
588
  ) -> dict[str, Any]:
376
589
  """Start a job whose visuals YOU plan. Cliptude writes (if needed) and voices the narration, then stops at status plan_ready. It needs the full website price in credits but charges only the narration now; the rest is charged when the video completes, and the total equals the website price. Poll get_job until plan_ready, then get_narration."""
377
590
  try:
378
- if not (prompt or "").strip() and not (script or "").strip() and not voiceover_path:
379
- return {"error": "Provide prompt, script or voiceover_path."}
591
+ if not (prompt or "").strip() and not (script or "").strip() and not voiceover_path and not voiceover_url:
592
+ return {"error": "Provide prompt, script, voiceover_path or voiceover_url."}
380
593
  return _client().create_job(
381
594
  template_id=template_id,
382
595
  title=title,
383
596
  prompt=prompt,
384
597
  script=script,
385
598
  voiceover_path=voiceover_path,
599
+ voiceover_url=(voiceover_url or "").strip() or None,
386
600
  duration=duration,
387
601
  output="plan",
602
+ avatar_profile_id=avatar_profile_id,
603
+ avatar_engine=avatar_engine,
604
+ render_only=render_only,
605
+ thumbnail=_thumbnail_arg(thumbnail_prompt, thumbnail_reference_url),
606
+ vector_character_id=vector_character_id,
607
+ vector_reveal_mode=vector_reveal_mode,
388
608
  )
389
609
  except Exception as exc:
390
610
  return _err(exc)
@@ -407,7 +627,7 @@ def build_server(*, with_http_auth: bool = False):
407
627
  annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
408
628
  )
409
629
  def get_kind_catalog(
410
- format: Annotated[str | None, Field(description="faceless_documentary, faceless_top_10 or avatar_video")] = None,
630
+ format: Annotated[str | None, Field(description="faceless_documentary, faceless_top_10, avatar_video or vector_explainer")] = None,
411
631
  theme: Annotated[str | None, Field(description="Visual theme, to mark graphics the theme does not use")] = None,
412
632
  compact: Annotated[bool, Field(description="One summary line per graphic (start here; the full catalog is large)")] = True,
413
633
  types: Annotated[list[str] | None, Field(description="Full entries (description, prop_schema, media_slots, durations, preview) for just these animation types / overlay styles")] = None,
@@ -470,6 +690,23 @@ def build_server(*, with_http_auth: bool = False):
470
690
  except Exception as exc:
471
691
  return _err(exc)
472
692
 
693
+ @mcp.tool(
694
+ title="Upload plan media",
695
+ annotations=ToolAnnotations(read_only_hint=False, open_world_hint=False),
696
+ )
697
+ def upload_plan_media(
698
+ job_id: Annotated[str, Field(min_length=8, description="Plan job UUID")],
699
+ path: Annotated[
700
+ str,
701
+ Field(description="Local picture (JPG/PNG/WEBP/GIF, up to 15 MB) or clip (MP4/MOV/WEBM/M4V, up to 300 MB). Stdio / local MCP only — remote hosts should use the CLI (cliptude upload-media) or give a public file link as media.url."),
702
+ ],
703
+ ) -> dict[str, Any]:
704
+ """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."""
705
+ try:
706
+ return _client().upload_plan_media(job_id, path)
707
+ except Exception as exc:
708
+ return _err(exc)
709
+
473
710
  @mcp.tool(
474
711
  title="Get plan sourcing report",
475
712
  annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cliptude/cli",
3
- "version": "0.1.7",
3
+ "version": "0.1.9",
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.7"
7
+ version = "0.1.9"
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"