@cliptude/cli 0.1.16 → 0.1.18

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.
@@ -15,6 +15,48 @@ def _print(payload) -> None:
15
15
  sys.stdout.write("\n")
16
16
 
17
17
 
18
+ def _add_review_args(parser) -> None:
19
+ parser.add_argument("--review-token", default="", help="Token from the job review (shown when you run without it)")
20
+ parser.add_argument(
21
+ "--acknowledge", action="append", default=[],
22
+ help="An item from acknowledgements_required the user approved, e.g. no_general_web_content (repeatable)",
23
+ )
24
+
25
+
26
+ def _create_reviewed(client: CliptudeClient, args, **kwargs):
27
+ """create_job behind the job review: in a terminal, show it and ask; otherwise print it and stop.
28
+
29
+ Cliptude answers a job without a review_token with the review (HTTP 428) and creates nothing.
30
+ """
31
+ token = (getattr(args, "review_token", "") or "").strip() or None
32
+ acks = [a.strip() for raw in (getattr(args, "acknowledge", None) or []) for a in raw.split(",") if a.strip()]
33
+ try:
34
+ return client.create_job(review_token=token, acknowledge=acks or None, **kwargs)
35
+ except CliptudeApiError as exc:
36
+ detail = exc.payload if isinstance(exc.payload, dict) else {}
37
+ if exc.status != 428 or "review" not in detail or not sys.stdin.isatty():
38
+ raise
39
+ review = detail["review"]
40
+ out = sys.stderr
41
+ out.write("\nReview this video before it is created:\n")
42
+ for item in review.get("settings") or []:
43
+ out.write(f" {item.get('label')}: {item.get('value')}\n")
44
+ credits = review.get("credits") or {}
45
+ if credits.get("credits_required") is not None:
46
+ out.write(f" Credits: about {credits['credits_required']} (you have {credits.get('credits_available')})\n")
47
+ for warning in review.get("warnings") or []:
48
+ out.write(f" ! {warning}\n")
49
+ approved = []
50
+ for ack in review.get("acknowledgements_required") or []:
51
+ out.write(f"\n {ack['message']}\n")
52
+ if input(f" Approve ({ack['id']})? [y/N] ").strip().lower() != "y":
53
+ raise CliptudeApiError("Not created: change the template and run again.")
54
+ approved.append(ack["id"])
55
+ if input("\nCreate this video? [y/N] ").strip().lower() != "y":
56
+ raise CliptudeApiError("Not created.")
57
+ return client.create_job(review_token=detail["review_token"], acknowledge=approved or None, **kwargs)
58
+
59
+
18
60
  def _die(exc: Exception, code: int = 1) -> None:
19
61
  if isinstance(exc, CliptudeApiError):
20
62
  _print({"error": str(exc), "status": exc.status, "detail": exc.payload})
@@ -543,6 +585,8 @@ def main(argv: list[str] | None = None) -> None:
543
585
  c = sub.add_parser("cancel", help="Cancel a job")
544
586
  c.add_argument("job_id")
545
587
 
588
+ for job_parser in (g, sc, vo, pj):
589
+ _add_review_args(job_parser)
546
590
  args = parser.parse_args(argv)
547
591
  if args.cmd == "auth":
548
592
  _run_auth(args.auth_cmd)
@@ -624,7 +668,7 @@ def main(argv: list[str] | None = None) -> None:
624
668
  "Provide --prompt, --script / --script-file, --voiceover, or --talking-head."
625
669
  )
626
670
  template_id = _resolve_template_id(client, args.template)
627
- _print(client.create_job(
671
+ _print(_create_reviewed(client, args,
628
672
  template_id=template_id,
629
673
  title=args.title,
630
674
  prompt=args.prompt or None,
@@ -652,7 +696,7 @@ def main(argv: list[str] | None = None) -> None:
652
696
  if not (args.prompt or "").strip():
653
697
  raise CliptudeApiError("Provide --prompt.")
654
698
  template_id = _resolve_template_id(client, args.template)
655
- _print(client.create_job(
699
+ _print(_create_reviewed(client, args,
656
700
  template_id=template_id,
657
701
  title=args.title,
658
702
  prompt=args.prompt,
@@ -666,7 +710,7 @@ def main(argv: list[str] | None = None) -> None:
666
710
  if not (args.prompt or "").strip() and not (script or "").strip():
667
711
  raise CliptudeApiError("Provide --prompt or --script / --script-file.")
668
712
  template_id = _resolve_template_id(client, args.template)
669
- _print(client.create_job(
713
+ _print(_create_reviewed(client, args,
670
714
  template_id=template_id,
671
715
  title=args.title,
672
716
  prompt=args.prompt or None,
@@ -683,7 +727,7 @@ def main(argv: list[str] | None = None) -> None:
683
727
  if not (args.prompt or "").strip() and not (script or "").strip() and not voiceover and not voiceover_url:
684
728
  raise CliptudeApiError("Provide --prompt, --script / --script-file, --voiceover or --voiceover-url.")
685
729
  template_id = _resolve_template_id(client, args.template)
686
- _print(client.create_job(
730
+ _print(_create_reviewed(client, args,
687
731
  template_id=template_id,
688
732
  title=args.title,
689
733
  prompt=args.prompt or None,
@@ -149,6 +149,19 @@ def _avatar_job_fields(
149
149
  return fields
150
150
 
151
151
 
152
+ def _review_job_fields(review_token: str | None, acknowledge: list[str] | None, review_only: bool | None,
153
+ *, as_strings: bool = False) -> dict[str, Any]:
154
+ """The job review: Cliptude answers a job without a review_token with the review (HTTP 428)."""
155
+ out: dict[str, Any] = {}
156
+ if review_token:
157
+ out["review_token"] = str(review_token)
158
+ if acknowledge:
159
+ out["acknowledge"] = ",".join(acknowledge) if as_strings else list(acknowledge)
160
+ if review_only:
161
+ out["review_only"] = "true" if as_strings else True
162
+ return out
163
+
164
+
152
165
  def _thumbnail_job_field(thumbnail: dict[str, str] | None, *, as_string: bool = False) -> dict[str, Any]:
153
166
  """create_job's per-job thumbnail ({custom_prompt} or {reference_url}); multipart sends it as JSON text."""
154
167
  cleaned = {k: str(v).strip() for k, v in (thumbnail or {}).items() if v is not None and str(v).strip()}
@@ -309,6 +322,9 @@ class CliptudeClient:
309
322
  vector_character_id: str | None = None,
310
323
  vector_reveal_mode: str | None = None,
311
324
  pronunciations: list[dict[str, str]] | None = None,
325
+ review_token: str | None = None,
326
+ acknowledge: list[str] | None = None,
327
+ review_only: bool | None = None,
312
328
  ) -> Any:
313
329
  if voiceover_path and voiceover_url:
314
330
  raise CliptudeApiError("Give voiceover_path or voiceover_url, not both.")
@@ -369,6 +385,7 @@ class CliptudeClient:
369
385
  excluded_animation_types=excluded_animation_types,
370
386
  excluded_transition_kinds=excluded_transition_kinds,
371
387
  thumbnail=thumbnail,
388
+ review=_review_job_fields(review_token, acknowledge, review_only),
372
389
  )
373
390
  if vo_path:
374
391
  extra_data = {
@@ -383,6 +400,7 @@ class CliptudeClient:
383
400
  **({"vector_character_id": str(vector_character_id)} if vector_character_id else {}),
384
401
  **({"vector_reveal_mode": str(vector_reveal_mode)} if vector_reveal_mode else {}),
385
402
  **({"pronunciations": json.dumps(pronunciations)} if pronunciations is not None else {}),
403
+ **_review_job_fields(review_token, acknowledge, review_only, as_strings=True),
386
404
  }
387
405
  return self._create_job_multipart(
388
406
  template_id=template_id,
@@ -419,6 +437,7 @@ class CliptudeClient:
419
437
  body["vector_reveal_mode"] = str(vector_reveal_mode)
420
438
  if pronunciations is not None:
421
439
  body["pronunciations"] = pronunciations
440
+ body.update(_review_job_fields(review_token, acknowledge, review_only))
422
441
  return self.request("POST", "/api/v1/jobs", json_body=body)
423
442
 
424
443
  def _raise_http(self, resp, *, payload=None) -> None:
@@ -515,7 +534,11 @@ class CliptudeClient:
515
534
  excluded_animation_types: list[str] | None = None,
516
535
  excluded_transition_kinds: list[str] | None = None,
517
536
  thumbnail: dict[str, str] | None = None,
537
+ review: dict[str, Any] | None = None,
518
538
  ) -> Any:
539
+ review = review or {}
540
+ review_strings = {k: (",".join(v) if isinstance(v, list) else ("true" if v is True else v))
541
+ for k, v in review.items()}
519
542
  motion_extra = _motion_control_job_fields(
520
543
  disable_animations=disable_animations,
521
544
  disable_overlays=disable_overlays,
@@ -549,6 +572,7 @@ class CliptudeClient:
549
572
  **_avatar_job_fields(avatar_intro_only, avatar_ai_footage, as_strings=True),
550
573
  **motion_extra,
551
574
  **_thumbnail_job_field(thumbnail, as_string=True),
575
+ **review_strings,
552
576
  }
553
577
  return self._create_job_multipart(
554
578
  template_id=template_id,
@@ -567,6 +591,7 @@ class CliptudeClient:
567
591
  **_avatar_job_fields(avatar_intro_only, avatar_ai_footage, as_strings=True),
568
592
  **motion_extra,
569
593
  **_thumbnail_job_field(thumbnail, as_string=True),
594
+ **review_strings,
570
595
  }
571
596
  return self._create_job_multipart(
572
597
  template_id=template_id,
@@ -605,6 +630,7 @@ class CliptudeClient:
605
630
  excluded_transition_kinds=excluded_transition_kinds,
606
631
  )
607
632
  )
633
+ body.update(review)
608
634
  return self.request("POST", "/api/v1/jobs", json_body=body)
609
635
 
610
636
  def _upload_talking_head_parts(self, path: Path, init: dict[str, Any]) -> None:
@@ -48,6 +48,74 @@ def _err(exc: Exception) -> dict[str, Any]:
48
48
  return {"error": str(exc)}
49
49
 
50
50
 
51
+ # Fields that make an MCP result too big to read (a 90 minute-class timeline index, per-word timings,
52
+ # whole-voiceover segment arrays) without helping an agent decide anything.
53
+ _BULKY_OPERATION_KEYS = frozenset({
54
+ "voice_segments", "chunk_alignments", "chunk_durations", "voiceover_chunks", "timing_metadata",
55
+ })
56
+
57
+
58
+ def _compact_operation(operation: Any) -> Any:
59
+ if not isinstance(operation, dict):
60
+ return operation
61
+ out: dict[str, Any] = {}
62
+ for key, value in operation.items():
63
+ if key in _BULKY_OPERATION_KEYS and isinstance(value, (list, dict)):
64
+ out[key] = f"<{len(value)} entries omitted>"
65
+ else:
66
+ out[key] = value
67
+ return out
68
+
69
+
70
+ def _compact_agent_run(data: Any) -> Any:
71
+ """Agent run with the voice-segment arrays of its operations summarised (they repeat in messages)."""
72
+ if not isinstance(data, dict):
73
+ return data
74
+ out = dict(data)
75
+ run = out.get("run")
76
+ if isinstance(run, dict) and isinstance(run.get("applied_operations"), list):
77
+ out["run"] = {**run, "applied_operations": [_compact_operation(op) for op in run["applied_operations"]]}
78
+ messages = out.get("messages")
79
+ if isinstance(messages, list):
80
+ compact_messages = []
81
+ for message in messages:
82
+ if isinstance(message, dict) and isinstance(message.get("metadata"), dict):
83
+ meta = dict(message["metadata"])
84
+ if isinstance(meta.get("operations"), list):
85
+ meta["operations"] = [_compact_operation(op) for op in meta["operations"]]
86
+ message = {**message, "metadata": meta}
87
+ compact_messages.append(message)
88
+ out["messages"] = compact_messages
89
+ return out
90
+
91
+
92
+ def _compact_editor_project(data: Any) -> Any:
93
+ """Editor project without voice_timing.spokenEventIndex (every word of the narration, 100 KB+)."""
94
+ if not isinstance(data, dict):
95
+ return data
96
+ project = data.get("project")
97
+ if not isinstance(project, dict) or not isinstance(project.get("voice_timing"), dict):
98
+ return data
99
+ timing = project["voice_timing"]
100
+ kept = {k: v for k, v in timing.items() if k != "spokenEventIndex"}
101
+ index = timing.get("spokenEventIndex")
102
+ if isinstance(index, dict) and isinstance(index.get("words"), list):
103
+ kept["spoken_words"] = len(index["words"])
104
+ return {**data, "project": {**project, "voice_timing": kept}}
105
+
106
+
107
+ def _compact_narration(data: Any, *, include_words: bool) -> Any:
108
+ """Narration sentences without per-word timings unless asked (they are most of the payload)."""
109
+ if include_words or not isinstance(data, dict) or not isinstance(data.get("sentences"), list):
110
+ return data
111
+ sentences = []
112
+ for sentence in data["sentences"]:
113
+ if isinstance(sentence, dict) and "words" in sentence:
114
+ sentence = {k: v for k, v in sentence.items() if k != "words"}
115
+ sentences.append(sentence)
116
+ return {**data, "sentences": sentences, "words_omitted": True}
117
+
118
+
51
119
  def mcp_allowed_hosts(resource_url: str | None = None) -> list[str]:
52
120
  """Host header values the Streamable HTTP transport should accept.
53
121
 
@@ -127,15 +195,33 @@ def build_server(*, with_http_auth: bool = False):
127
195
  "Avatar Video templates may include avatar_intro_only "
128
196
  "(Avatar Intro Only) and avatar_ai_footage (AI Image + AI Video); pass those "
129
197
  "on create_job to override the template, or omit them to keep the template. "
198
+ "REVIEW BEFORE EVERY JOB: create_job, create_plan_job, create_script and create_voiceover first return "
199
+ "a review (status 428, detail.review) and create nothing. Show the user every setting in it in plain "
200
+ "words (voice, model tier, media sources incl. general web crawling, animations/motion graphics, charts, "
201
+ "overlays, transitions, sound effects, music, A-roll) plus every warning and the credits, and ask them to "
202
+ "confirm. Then call the same tool again with the same arguments and review_token. For each item in "
203
+ "detail.review.acknowledgements_required (no_general_web_content: no YouTube or general web content, which "
204
+ "can lower video quality a lot; no_video_footage; no_motion_graphics) tell the user what it costs and pass "
205
+ "its id in acknowledge only after they explicitly approve; otherwise fix the template. "
130
206
  "AGENT-PLANNED VIDEOS (Faceless Documentary, Top 10, Avatar Video): you plan every visual "
131
207
  "and Cliptude only voices, sources and renders. create_plan_job, poll get_job until "
132
208
  "plan_ready, get_narration (numbered sentences), get_kind_catalog (compact first), write the "
133
- "plan, check_plan until valid, lock_plan, continue_job, then get_plan_report. See the "
209
+ "plan, check_plan until valid, lock_plan, continue_job, then get_plan_report. Before giving the user "
210
+ "the editor link, open_editor_project and look at EVERY frame with view_scenes (0 to the end): replace "
211
+ "any dead body or gore, other brands, logos, game or album art, title cards, pictures whose place or era "
212
+ "contradicts the story (a search naming a place can return a namesake elsewhere), near-black frames, clips floating in black bars, broken AI pictures and any picture held over ~8 s, in a free revision, then review again. Generic "
213
+ "shots of places name the story's setting (\"empty bed mud house\", not \"empty bed dark room\"). True "
214
+ "stories (real events and people) set sense.true_story and sense.people and never search for people: a "
215
+ "stranger on screen is taken for the real person (check_plan refuses it, stand_in_person; a dated topic "
216
+ "naming people counts as true unless true_story is false, and its year is the default era). See the "
134
217
  "cliptude-plan skill. Avatar Video and Talking Head plans never show the presenter only in "
135
218
  "full screen: make about one in four presenter_windows split_left/split_right with collage_media and "
136
219
  "put a speaker board (talking_head_*, dual_metric_talking_head) in most full-screen windows; check_plan "
137
220
  "refuses all-full-screen windows (presenter_only_full_screen). Treat presenter_no_speaker_boards, "
138
221
  "presenter_no_splits, kind_overused, over_cap and few_board_pictures warnings as must-fix. "
222
+ "On footage videos also fix query_too_long, query_style_words and same_subject_searches (write each "
223
+ "query as 2-5 words naming the subject, as clips are titled, and put the shot in intent), and on "
224
+ "video_needs_web_crawling ask the user to turn on General Web Crawling before building. "
139
225
  "PRODUCT VIDEOS (the user's connected store, or a product page from a store they sell for): "
140
226
  "fetch_product_context, show the user the 3 angles, draft_product_script with their pick and a "
141
227
  "duration (6-8 to 50-60 minutes), poll get_product_video_status until script_ready, let the user "
@@ -221,7 +307,10 @@ def build_server(*, with_http_auth: bool = False):
221
307
  Field(
222
308
  description=(
223
309
  "Wizard settings: voice_id, voice_name, voice_provider plus any field from "
224
- "get_template_options (unset fields take the wizard defaults). "
310
+ "get_template_options (unset fields take the wizard defaults). Set only what the user asked for: "
311
+ "each field's description says what turning it on or off does, and the source and graphics "
312
+ "switches (source_general_web_crawling, enable_broll_stock_footage, enable_animations, ...) "
313
+ "decide whether the video can have real footage and boards at all. "
225
314
  "Avatar Video: avatar_profile_id from list_avatars (gender must match the voice). "
226
315
  "Vector Explainer: vector_character_id from get_template_options (vector_character.choices: "
227
316
  "a built-in id such as nova, or one of the user's uploaded figures); omit it for no character. "
@@ -232,7 +321,7 @@ def build_server(*, with_http_auth: bool = False):
232
321
  ),
233
322
  ],
234
323
  ) -> dict[str, Any]:
235
- """Create a ready-to-use template without the create wizard. Values are validated like the wizard; returns the template (use its id in create_job)."""
324
+ """Create a ready-to-use template without the create wizard. Values are validated like the wizard; returns the template (use its id in create_job) and `warnings`: choices that will change what the video can show (no footage, AI stills, no graphics). Tell the user every warning in plain words and fix the ones they did not ask for before making a video."""
236
325
  try:
237
326
  return _client().create_template(name=name, format=format, settings=settings)
238
327
  except Exception as exc:
@@ -477,6 +566,14 @@ def build_server(*, with_http_auth: bool = False):
477
566
  list[dict[str, str]] | None,
478
567
  Field(description='How the voice says hard words (ElevenLabs voices): [{"word": "Gmay", "alias": "guh-MAY"}] or [{"word": "Ordnung", "phoneme": "ˈɔɹt.nʊŋ", "alphabet": "ipa"}]. Script, captions and searches keep the real spelling. Replaces the template\'s list for this video; omit to keep it.'),
479
568
  ] = None,
569
+ review_token: Annotated[
570
+ str | None,
571
+ Field(description="From the review this tool returned when called without it (status 428, detail.review_token). Only send it after showing the user every setting and warning in detail.review and getting their confirmation."),
572
+ ] = None,
573
+ acknowledge: Annotated[
574
+ list[str] | None,
575
+ Field(description="Ids from detail.review.acknowledgements_required (e.g. no_general_web_content) that the user explicitly approved after you explained each one. Never fill these in yourself."),
576
+ ] = None,
480
577
  ) -> dict[str, Any]:
481
578
  """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."""
482
579
  try:
@@ -496,6 +593,8 @@ def build_server(*, with_http_auth: bool = False):
496
593
  )
497
594
  }
498
595
  return _client().create_job(
596
+ review_token=review_token,
597
+ acknowledge=acknowledge,
499
598
  template_id=template_id,
500
599
  title=title,
501
600
  prompt=prompt,
@@ -534,10 +633,20 @@ def build_server(*, with_http_auth: bool = False):
534
633
  str | None,
535
634
  Field(description="Wizard duration bucket such as 3-4 or 6-8. Omit to use the template."),
536
635
  ] = None,
636
+ review_token: Annotated[
637
+ str | None,
638
+ Field(description="From the review this tool returned when called without it (status 428, detail.review_token). Only send it after showing the user every setting and warning in detail.review and getting their confirmation."),
639
+ ] = None,
640
+ acknowledge: Annotated[
641
+ list[str] | None,
642
+ Field(description="Ids from detail.review.acknowledgements_required (e.g. no_general_web_content) that the user explicitly approved after you explained each one. Never fill these in yourself."),
643
+ ] = None,
537
644
  ) -> dict[str, Any]:
538
645
  """Start a script-only job (no MP4). Returns a job id immediately. Poll get_job until completed; read script. Do not use create_job."""
539
646
  try:
540
647
  return _client().create_job(
648
+ review_token=review_token,
649
+ acknowledge=acknowledge,
541
650
  template_id=template_id,
542
651
  title=title,
543
652
  prompt=prompt,
@@ -560,12 +669,22 @@ def build_server(*, with_http_auth: bool = False):
560
669
  str | None,
561
670
  Field(description="Wizard duration bucket such as 3-4 or 6-8. Omit to use the template (or estimate from script)."),
562
671
  ] = None,
672
+ review_token: Annotated[
673
+ str | None,
674
+ Field(description="From the review this tool returned when called without it (status 428, detail.review_token). Only send it after showing the user every setting and warning in detail.review and getting their confirmation."),
675
+ ] = None,
676
+ acknowledge: Annotated[
677
+ list[str] | None,
678
+ Field(description="Ids from detail.review.acknowledgements_required (e.g. no_general_web_content) that the user explicitly approved after you explained each one. Never fill these in yourself."),
679
+ ] = None,
563
680
  ) -> dict[str, Any]:
564
681
  """Start a TTS-only job (no MP4). Returns a job id immediately. Poll get_job until completed; read voiceover.url. Provide prompt or script."""
565
682
  try:
566
683
  if not (prompt or "").strip() and not (script or "").strip():
567
684
  return {"error": "Provide prompt or script."}
568
685
  return _client().create_job(
686
+ review_token=review_token,
687
+ acknowledge=acknowledge,
569
688
  template_id=template_id,
570
689
  title=title,
571
690
  prompt=prompt,
@@ -597,13 +716,14 @@ def build_server(*, with_http_auth: bool = False):
597
716
  def fetch_product_context(
598
717
  product_url_or_query: Annotated[str, Field(min_length=1, description=(
599
718
  "A product page URL from the user's own store (Shopify, e.g. https://store.com/products/handle; "
600
- "WooCommerce or Etsy work through the page's structured data), a connected store's "
719
+ "WooCommerce, e.g. https://store.com/product/name/, is read through its Store API; Etsy and others "
720
+ "work through the page's structured data), a connected store's "
601
721
  "product id/handle, or a search term together with store_domain."))],
602
722
  store_domain: Annotated[str | None, Field(description=(
603
723
  "Store to search or read from, e.g. acme.com or acme.myshopify.com. Uses the user's connected "
604
724
  "store when it matches."))] = None,
605
725
  ) -> dict[str, Any]:
606
- """Read a store product: title, price, variants, description and its real image URLs, saved as product_id, plus 3 educational YouTube video angles (80% teaching, 20% product). A search that matches several products returns candidates; fetch again with the chosen URL. Show the user the angles before drafting."""
726
+ """Read a store product: title, price, variants, description and its real image URLs, saved as product_id, plus 3 educational YouTube video angles (80% teaching, 20% product). When no angles could be suggested the list is empty with an angles_note: pass your own angle (a title, or {title, problem, hook}) to draft_product_script. A search that matches several products returns candidates; fetch again with the chosen URL. Show the user the angles before drafting."""
607
727
  try:
608
728
  return _client().fetch_product_context(product_url_or_query, store_domain=store_domain)
609
729
  except Exception as exc:
@@ -622,8 +742,9 @@ def build_server(*, with_http_auth: bool = False):
622
742
  "Length: 6-8, 10-12, 18-20, 30-40 or 50-60 (minutes), or a number of minutes from 6 to 60. "
623
743
  "Default 6-8."))] = None,
624
744
  template_id: Annotated[str | None, Field(description=(
625
- "Faceless Documentary template to use (voice, look, music). Omit to use the latest one, or a "
626
- "default Product Explainer template."))] = None,
745
+ "Template to use (voice, look, music): a Faceless Documentary, Top 10 or Avatar Video template "
746
+ "(an Avatar Video one puts the avatar on screen). Omit to use the latest Faceless Documentary one, "
747
+ "or a default Product Explainer template."))] = None,
627
748
  title: Annotated[str | None, Field(description="Video title. Defaults to the angle title.")] = None,
628
749
  discount_code: Annotated[str | None, Field(description="Discount code the merchant gave. Never invent one.")] = None,
629
750
  cta_url: Annotated[str | None, Field(description="Where viewers should go. Defaults to the product page.")] = None,
@@ -717,12 +838,22 @@ def build_server(*, with_http_auth: bool = False):
717
838
  list[dict[str, str]] | None,
718
839
  Field(description='How the voice says hard words (ElevenLabs voices): [{"word": "Gmay", "alias": "guh-MAY"}] or [{"word": "Ordnung", "phoneme": "ˈɔɹt.nʊŋ", "alphabet": "ipa"}]. Script, captions and searches keep the real spelling. Replaces the template\'s list for this video; omit to keep it.'),
719
840
  ] = None,
841
+ review_token: Annotated[
842
+ str | None,
843
+ Field(description="From the review this tool returned when called without it (status 428, detail.review_token). Only send it after showing the user every setting and warning in detail.review and getting their confirmation."),
844
+ ] = None,
845
+ acknowledge: Annotated[
846
+ list[str] | None,
847
+ Field(description="Ids from detail.review.acknowledgements_required (e.g. no_general_web_content) that the user explicitly approved after you explained each one. Never fill these in yourself."),
848
+ ] = None,
720
849
  ) -> dict[str, Any]:
721
850
  """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."""
722
851
  try:
723
852
  if not (prompt or "").strip() and not (script or "").strip() and not voiceover_path and not voiceover_url:
724
853
  return {"error": "Provide prompt, script, voiceover_path or voiceover_url."}
725
854
  return _client().create_job(
855
+ review_token=review_token,
856
+ acknowledge=acknowledge,
726
857
  template_id=template_id,
727
858
  title=title,
728
859
  prompt=prompt,
@@ -748,10 +879,13 @@ def build_server(*, with_http_auth: bool = False):
748
879
  )
749
880
  def get_narration(
750
881
  job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
882
+ include_words: Annotated[
883
+ bool, Field(description="Add every word's start/end to each sentence (large: about 10 KB a minute). Phrases in a plan are matched server-side, so leave it off unless you need word times.")
884
+ ] = False,
751
885
  ) -> dict[str, Any]:
752
- """The narration you plan against: numbered sentences with start/end seconds and every word's timing, narration_digest (copy it into the plan), suggested chapters, the template's theme and switched-off graphics, pricing (website price, already charged, due at continue), and narration_audio: a url to listen to (check names and borrowed words before you lock) and the API path that downloads the MP3. The sentence text is what the voice said, so a misspoken word shows up there too."""
886
+ """The narration you plan against: numbered sentences with start/end seconds (and every word's timing with include_words), narration_digest (copy it into the plan), suggested chapters, the template's theme and switched-off graphics, pricing (website price, already charged, due at continue), and narration_audio: a url to listen to (check names and borrowed words before you lock) and the API path that downloads the MP3. The sentence text is what the voice said, so a misspoken word shows up there too."""
753
887
  try:
754
- return _client().get_narration(job_id)
888
+ return _compact_narration(_client().get_narration(job_id), include_words=include_words)
755
889
  except Exception as exc:
756
890
  return _err(exc)
757
891
 
@@ -985,7 +1119,7 @@ def build_server(*, with_http_auth: bool = False):
985
1119
  ) -> dict[str, Any]:
986
1120
  """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."""
987
1121
  try:
988
- return _client().open_editor_project(job_id)
1122
+ return _compact_editor_project(_client().open_editor_project(job_id))
989
1123
  except Exception as exc:
990
1124
  return _err(exc)
991
1125
 
@@ -998,7 +1132,7 @@ def build_server(*, with_http_auth: bool = False):
998
1132
  ) -> dict[str, Any]:
999
1133
  """Current revision, compact timeline, latest render and export_credits_due (what render_project would charge now) of an editor project."""
1000
1134
  try:
1001
- return _client().get_editor_project(project_id)
1135
+ return _compact_editor_project(_client().get_editor_project(project_id))
1002
1136
  except Exception as exc:
1003
1137
  return _err(exc)
1004
1138
 
@@ -1011,7 +1145,7 @@ def build_server(*, with_http_auth: bool = False):
1011
1145
  start_s: Annotated[float, Field(ge=0, description="First second to show")] = 0.0,
1012
1146
  end_s: Annotated[float | None, Field(description="Stop before this second (default: the end)")] = None,
1013
1147
  ) -> list[str | Image]:
1014
- """See what the timeline shows, without opening any link: numbered contact sheets of every picture, a frame of every clip and each graphic's picture with its words, with the narration under each, plus a legend (tile, item_id, start_s, end_s, words, said, flags). Up to 24 tiles per call; call again from next_start_s. Use it to review a built video yourself (other brands, wrong pictures, repeats, leftover text) before giving the user the editor link, and again after run_agent to check the change."""
1148
+ """See what the timeline shows, without opening any link: numbered contact sheets of every picture, a frame of every clip and each graphic's picture with its words, with the narration under each, plus a legend (tile, item_id, start_s, end_s, words, said, flags: REPEATED PICTURE, HELD, AI STILL, DARK, BARS). Up to 24 tiles per call; call again from next_start_s. Use it to review a built video yourself (other brands, wrong pictures, repeats, leftover text) before giving the user the editor link, and again after run_agent to check the change."""
1015
1149
  try:
1016
1150
  data = _client().view_scenes(project_id, start_s=start_s, end_s=end_s)
1017
1151
  except Exception as exc:
@@ -1035,11 +1169,11 @@ def build_server(*, with_http_auth: bool = False):
1035
1169
  tier: Annotated[str, Field(description="fast or smart")] = "fast",
1036
1170
  chat_id: Annotated[str | None, Field(description="Continue an existing agent chat")] = None,
1037
1171
  ) -> dict[str, Any]:
1038
- """Ask Cliptude Agent to edit the timeline (swap footage, regenerate images or voiceover ranges, music, transitions, text). One kind of change per run: picture swaps and text edits go in separate runs. Several clips can get new pictures in one run: reference them all and describe each one's picture by its item id; a clip with nothing suitable is left unchanged and named in the reply. Swapping a graphic's picture keeps the graphic and its words. Returns a run; poll get_agent_run. Charges agent credits. Then render_project for a new MP4, after view_scenes on the changed range."""
1172
+ """Ask Cliptude Agent to edit the timeline (swap footage, regenerate images or voiceover ranges, music, transitions, text). One kind of change per run: picture swaps and text edits go in separate runs. Several clips can get new pictures in one run: reference them all and describe each one's picture by its item id; a clip with nothing suitable is left unchanged and named in the reply. Swapping a graphic's picture keeps the graphic and its words. To use one exact picture (a product cover, a screenshot), paste its https link in the prompt: it is downloaded and applied as is, not searched for. Returns a run; poll get_agent_run. Charges agent credits. Then render_project for a new MP4, after view_scenes on the changed range."""
1039
1173
  try:
1040
- return _client().run_agent(
1174
+ return _compact_agent_run(_client().run_agent(
1041
1175
  project_id, prompt=prompt, tier=tier, referenced_item_ids=referenced_item_ids, chat_id=chat_id
1042
- )
1176
+ ))
1043
1177
  except Exception as exc:
1044
1178
  return _err(exc)
1045
1179
 
@@ -1053,7 +1187,7 @@ def build_server(*, with_http_auth: bool = False):
1053
1187
  ) -> dict[str, Any]:
1054
1188
  """Status of a Cliptude Agent run plus the agent's messages."""
1055
1189
  try:
1056
- return _client().get_agent_run(project_id, run_id)
1190
+ return _compact_agent_run(_client().get_agent_run(project_id, run_id))
1057
1191
  except Exception as exc:
1058
1192
  return _err(exc)
1059
1193
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cliptude/cli",
3
- "version": "0.1.16",
3
+ "version": "0.1.18",
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.16"
7
+ version = "0.1.18"
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"