@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.
- package/cliptude_mcp/cli.py +48 -4
- package/cliptude_mcp/client.py +26 -0
- package/cliptude_mcp/server.py +150 -16
- package/package.json +1 -1
- package/pyproject.toml +1 -1
package/cliptude_mcp/cli.py
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
730
|
+
_print(_create_reviewed(client, args,
|
|
687
731
|
template_id=template_id,
|
|
688
732
|
title=args.title,
|
|
689
733
|
prompt=args.prompt or None,
|
package/cliptude_mcp/client.py
CHANGED
|
@@ -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:
|
package/cliptude_mcp/server.py
CHANGED
|
@@ -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.
|
|
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
|
|
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
|
-
"
|
|
626
|
-
"
|
|
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
package/pyproject.toml
CHANGED