@cliptude/cli 0.1.50 → 0.1.51

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.
@@ -473,7 +473,9 @@ def main(argv: list[str] | None = None) -> None:
473
473
  _add_branding_args(tu)
474
474
  _add_captions_arg(tu, scope="every video from this template")
475
475
 
476
- sub.add_parser("looks", help="List the prebuilt Looks (formats, colours, painted +20 credits/min, motion graphics)")
476
+ lk = sub.add_parser("looks", help="List the prebuilt Looks (formats, colours, painted +20 credits/min, motion graphics)")
477
+ lk.add_argument("--topic", default="", help="The video's title or description: the Looks that fit it come first with suggested=true and a reason")
478
+ lk.add_argument("--format", default="", help="Only suggest Looks that work with this format")
477
479
  lt = sub.add_parser("look-template", help="Save a Look as one of your templates; prints the template")
478
480
  lt.add_argument("slug", help="Look slug from `cliptude looks`")
479
481
  lt.add_argument("--name", default="", help="Template name (default: the Look's name)")
@@ -975,7 +977,7 @@ def main(argv: list[str] | None = None) -> None:
975
977
  brand_kit_id=args.brand_kit, show_logo=args.show_logo, look=args.look,
976
978
  captions=args.captions))
977
979
  elif args.cmd == "looks":
978
- _print(client.list_looks())
980
+ _print(client.list_looks(topic=args.topic or None, format=args.format or None))
979
981
  elif args.cmd == "look-template":
980
982
  _print(client.save_look_as_template(args.slug, name=args.name or None, format=args.format or None))
981
983
  elif args.cmd == "brand-kits":
@@ -526,9 +526,15 @@ class CliptudeClient:
526
526
  body["show_logo"] = bool(show_logo)
527
527
  return self.request("PATCH", f"/api/v1/templates/{_uuid_seg(template_id, 'template_id')}", json_body=body)
528
528
 
529
- def list_looks(self) -> Any:
530
- """The prebuilt Looks (colours, captions, footage grade, the boards that carry each), with sample reels."""
531
- return self.request("GET", "/api/v1/looks")
529
+ def list_looks(self, topic: str | None = None, format: str | None = None) -> Any:
530
+ """The prebuilt Looks (colours, captions, footage grade, the boards that carry each), with sample reels.
531
+ With ``topic`` the best fits come first with ``suggested: true`` and a ``reason``; ``format`` limits them."""
532
+ params: dict[str, Any] = {}
533
+ if topic and topic.strip():
534
+ params["topic"] = topic.strip()[:2000]
535
+ if format:
536
+ params["format"] = format
537
+ return self.request("GET", "/api/v1/looks", params=params or None)
532
538
 
533
539
  def save_look_as_template(self, slug: str, *, name: str | None = None, format: str | None = None) -> Any:
534
540
  """Copy a Look into one of the user's templates (format: any of the Look's formats); returns the template."""
@@ -641,6 +647,7 @@ class CliptudeClient:
641
647
  pronunciations: list[dict[str, str]] | None = None,
642
648
  visual_direction: str | None = None,
643
649
  captions: bool | None = None,
650
+ look: str | None = None,
644
651
  review_token: str | None = None,
645
652
  acknowledge: list[str] | None = None,
646
653
  review_only: bool | None = None,
@@ -717,6 +724,7 @@ class CliptudeClient:
717
724
  excluded_transition_kinds=excluded_transition_kinds,
718
725
  thumbnail=thumbnail,
719
726
  captions=captions,
727
+ look=look,
720
728
  review=_review_job_fields(review_token, acknowledge, review_only),
721
729
  )
722
730
  if vo_path:
@@ -734,6 +742,7 @@ class CliptudeClient:
734
742
  **({"pronunciations": json.dumps(pronunciations)} if pronunciations is not None else {}),
735
743
  **({"visual_direction": visual_direction} if visual_direction else {}),
736
744
  **({"captions": "true" if captions else "false"} if captions is not None else {}),
745
+ **({"look": str(look).strip() or "none"} if look is not None else {}),
737
746
  **({"prompt": prompt} if prompt else {}),
738
747
  **_review_job_fields(review_token, acknowledge, review_only, as_strings=True),
739
748
  }
@@ -776,6 +785,8 @@ class CliptudeClient:
776
785
  body["visual_direction"] = visual_direction
777
786
  if captions is not None:
778
787
  body["captions"] = bool(captions)
788
+ if look is not None:
789
+ body["look"] = str(look).strip()
779
790
  body.update(_review_job_fields(review_token, acknowledge, review_only))
780
791
  return self.request("POST", "/api/v1/jobs", json_body=body)
781
792
 
@@ -876,11 +887,16 @@ class CliptudeClient:
876
887
  excluded_transition_kinds: list[str] | None = None,
877
888
  thumbnail: dict[str, str] | None = None,
878
889
  captions: bool | None = None,
890
+ look: str | None = None,
879
891
  review: dict[str, Any] | None = None,
880
892
  ) -> Any:
881
893
  review = review or {}
882
894
  captions_field = {"captions": bool(captions)} if captions is not None else {}
883
895
  captions_str = {"captions": "true" if captions else "false"} if captions is not None else {}
896
+ # The job's Look rides with captions on every talking-head path ("none" = no Look; multipart drops "").
897
+ if look is not None:
898
+ captions_field["look"] = str(look).strip()
899
+ captions_str["look"] = str(look).strip() or "none"
884
900
  review_strings = {k: (",".join(v) if isinstance(v, list) else ("true" if v is True else v))
885
901
  for k, v in review.items()}
886
902
  motion_extra = _motion_control_job_fields(
@@ -1432,11 +1448,14 @@ class CliptudeClient:
1432
1448
  render_only: bool | None = None,
1433
1449
  vector_reveal_mode: str | None = None,
1434
1450
  captions: bool | None = None,
1451
+ look: str | None = None,
1435
1452
  ) -> Any:
1436
1453
  """Credits a job would need; creates nothing."""
1437
1454
  body: dict[str, Any] = {"template_id": template_id}
1438
1455
  if captions is not None:
1439
1456
  body["captions"] = bool(captions)
1457
+ if look is not None:
1458
+ body["look"] = str(look).strip()
1440
1459
  if render_only:
1441
1460
  body["render_only"] = True
1442
1461
  for key, value in (
@@ -237,6 +237,9 @@ def build_server(*, with_http_auth: bool = False):
237
237
  "instructions": (
238
238
  "Generate Cliptude videos from a saved template. "
239
239
  "Call list_templates, then create_job with template_id + title plus "
240
+ "(a Look: when the template has none, call list_looks with the video's topic and format, offer the "
241
+ "suggested Looks to the user and pass the one they pick as create_job look=<slug>; the review also lists "
242
+ "look_suggestions) "
240
243
  "(no suitable template? get_template_options + list_voices, then create_template) "
241
244
  "To revise a finished video: open_editor_project, then edit_timeline for exact changes on its item ids "
242
245
  "(delete, retime, trim, swap a graphic's design or picture, fix its words, add a graphic, clip or catalog sound, "
@@ -300,7 +303,8 @@ def build_server(*, with_http_auth: bool = False):
300
303
  "and Cliptude only voices, sources and renders. This is the default for these four formats: use "
301
304
  "create_plan_job, not create_job, unless the user asks Cliptude to plan the visuals (\"just make it\"), "
302
305
  "Cliptude runs in the Desktop app (no plan jobs there), or the template's Look is a motion-graphics Look "
303
- "(neon-noir, paper-atlas, editorial-explainer, business-ledger, route-atlas: Cliptude draws every shot from its "
306
+ "(neon-noir, paper-atlas, editorial-explainer, business-ledger, route-atlas, tech-glow, chalkboard-lesson, kinetic-type, "
307
+ "manim-math, data-desk, isometric-pastel: Cliptude draws every shot from its "
304
308
  "component library, so create_plan_job refuses them with code motion_graphics_look_plan; use create_job). A voiceover the user brings works the same way: "
305
309
  "pass it as voiceover_path/voiceover_url and Cliptude aligns it before plan_ready. Unless the user gave a script or a voiceover, research the "
306
310
  "topic with web search, write the narration yourself and show it to the user to review first; then "
@@ -356,7 +360,8 @@ def build_server(*, with_http_auth: bool = False):
356
360
  "with its picker, one at a time, and wait for each pick before the next, in this order as the format uses it "
357
361
  "(the five live formats: faceless_documentary, faceless_top_10, avatar_video, talking_head, vector_explainer; "
358
362
  "every other format is retired and refused for new templates and jobs; videos are 16:9 only; the five "
359
- "motion-graphics Looks neon-noir, paper-atlas, editorial-explainer, business-ledger and route-atlas work on "
363
+ "motion-graphics Looks neon-noir, paper-atlas, editorial-explainer, business-ledger, route-atlas, tech-glow, chalkboard-lesson, "
364
+ "kinetic-type, manim-math, data-desk and isometric-pastel work on "
360
365
  "Faceless Documentary, Top 10, Avatar Video and Talking Head): "
361
366
  "voice (list_voices); the presenter (list_avatars, Avatar Video) or character (list_vector_characters, "
362
367
  "Vector Explainer; the user can upload their own there); background music (show_choices field background_music_library_file); background picture "
@@ -544,10 +549,13 @@ def build_server(*, with_http_auth: bool = False):
544
549
  title="List looks",
545
550
  annotations=ToolAnnotations(title="List looks", read_only_hint=True, open_world_hint=False),
546
551
  )
547
- def list_looks() -> dict[str, Any]:
548
- """Prebuilt Looks: ready-made styles (Cold Case Board, Money Breakdown, Archive Press, Tactical Brief ...), each with the formats it works with (footage Looks: Faceless Documentary, Faceless Top 10, Avatar Video, Talking Head and Vector Explainer; the five motion-graphics Looks neon-noir, paper-atlas, editorial-explainer, business-ledger and route-atlas draw every shot from a component library and work with Faceless Documentary, Faceless Top 10, Avatar Video and Talking Head, made with create_job, never create_plan_job), five colours, caption style, footage grade, the premium boards it favours and a sample reel URL. painted=true marks the painted Looks (imagery "ai_cast": empire-story, shield-wall, cartoon-briefing ...): on Faceless Documentary (painted_formats) every scene is AI-painted and the video costs credits_per_minute_extra (+20) credits/min on top of the voice rate (60/min with ElevenLabs instead of 40); estimate_job_credits includes it (painted_look_credits_per_minute). Tell the user before choosing one. A Look is used through a template: create_template(look=...) or update_template(look=...) for a template with the user's own voice and settings, or save_look_as_template for a template from the Look alone; then create_job with that template_id. Offer them when the user wants a style but has no template."""
552
+ def list_looks(
553
+ topic: Annotated[str | None, Field(description="Optional: the video's title, description or script start. The Looks that fit it come first with suggested=true and a short reason (\"history and maps\"); a generic topic suggests none. Free, no model call.")] = None,
554
+ format: Annotated[str | None, Field(description="Optional: only suggest Looks that work with this format (faceless_documentary, faceless_top_10, avatar_video, talking_head, vector_explainer)")] = None,
555
+ ) -> dict[str, Any]:
556
+ """Prebuilt Looks: ready-made styles (Cold Case Board, Money Breakdown, Archive Press, Tactical Brief ...), each with the formats it works with (footage Looks: Faceless Documentary, Faceless Top 10, Avatar Video, Talking Head and Vector Explainer; the motion-graphics Looks neon-noir, paper-atlas, editorial-explainer, business-ledger, route-atlas, tech-glow, chalkboard-lesson, kinetic-type, manim-math, data-desk and isometric-pastel draw every shot from a component library and work with Faceless Documentary, Faceless Top 10, Avatar Video and Talking Head, made with create_job, never create_plan_job), five colours, caption style, footage grade, the premium boards it favours and a sample reel URL. painted=true marks the painted Looks (imagery "ai_cast": empire-story, shield-wall, cartoon-briefing ...): on Faceless Documentary (painted_formats) every scene is AI-painted and the video costs credits_per_minute_extra (+20) credits/min on top of the voice rate (60/min with ElevenLabs instead of 40); estimate_job_credits includes it (painted_look_credits_per_minute). Tell the user before choosing one. For one video, pass the slug as create_job look=<slug> (it overrides the template's Look; the user's voice and settings stay). To keep a Look for future videos, put it on a template: create_template(look=...) or update_template(look=...), or save_look_as_template for a template from the Look alone. Offer them when the user wants a style but has no template. Pass topic (the video's title or description) and format to rank them by fit: the top matches have suggested=true and a reason; offer those first, with the painted +20/min cost on any painted one."""
549
557
  try:
550
- return _client().list_looks()
558
+ return _client().list_looks(topic=topic, format=format)
551
559
  except Exception as exc:
552
560
  return _err(exc)
553
561
 
@@ -639,6 +647,10 @@ def build_server(*, with_http_auth: bool = False):
639
647
  bool | None,
640
648
  Field(description="Whole-video captions in the template's caption style. Off by default on every video: true only when the user asks; false hides them; omit to keep the template's."),
641
649
  ] = None,
650
+ look: Annotated[
651
+ str | None,
652
+ Field(description="The Look the job would use (list_looks slug, \"none\" = no Look), to price a job that overrides the template's: a painted Look adds credits per minute on Faceless Documentary."),
653
+ ] = None,
642
654
  ) -> dict[str, Any]:
643
655
  """Credits a job would need before you create it, with the same pricing as create_job. Creates and charges nothing.
644
656
 
@@ -664,6 +676,7 @@ def build_server(*, with_http_auth: bool = False):
664
676
  render_only=render_only,
665
677
  vector_reveal_mode=vector_reveal_mode,
666
678
  captions=captions,
679
+ look=look,
667
680
  )
668
681
  except Exception as exc:
669
682
  return _err(exc)
@@ -868,6 +881,10 @@ def build_server(*, with_http_auth: bool = False):
868
881
  bool | None,
869
882
  Field(description="Whole-video captions in the template's caption style. Off by default on every video: true only when the user asks; false hides them; omit to keep the template's."),
870
883
  ] = None,
884
+ look: Annotated[
885
+ str | None,
886
+ Field(description="A Look for this video (slug from list_looks, e.g. archive-press), overriding the template's: its theme, tone, captions, colours, footage grade and favoured boards. Pass the video's topic to list_looks to get the ones that fit, offer them to the user, and send the one they choose. Painted Looks add credits per minute on Faceless Documentary (list_looks says how many); say so first. \"none\" = no Look. Omit to keep the template's. The review shows it, and suggests fitting Looks when the video would have none."),
887
+ ] = None,
871
888
  review_token: Annotated[
872
889
  str | None,
873
890
  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."),
@@ -925,6 +942,7 @@ def build_server(*, with_http_auth: bool = False):
925
942
  pronunciations=pronunciations,
926
943
  visual_direction=visual_direction,
927
944
  captions=captions,
945
+ look=look,
928
946
  )
929
947
  except Exception as exc:
930
948
  return _err(exc)
@@ -1213,7 +1231,7 @@ def build_server(*, with_http_auth: bool = False):
1213
1231
  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."),
1214
1232
  ] = None,
1215
1233
  ) -> dict[str, Any]:
1216
- """Start a job whose visuals YOU plan. Not for a template whose Look is a motion-graphics Look (neon-noir, paper-atlas, editorial-explainer, business-ledger, route-atlas): those are refused (code motion_graphics_look_plan); use create_job. 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."""
1234
+ """Start a job whose visuals YOU plan. Not for a template whose Look is a motion-graphics Look (neon-noir, paper-atlas, editorial-explainer, business-ledger, route-atlas, tech-glow, chalkboard-lesson, kinetic-type, manim-math, data-desk, isometric-pastel): those are refused (code motion_graphics_look_plan); use create_job. 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."""
1217
1235
  refused = _local_path_refused(remote, ("voiceover_path", voiceover_path))
1218
1236
  if refused:
1219
1237
  return refused
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cliptude/cli",
3
- "version": "0.1.50",
3
+ "version": "0.1.51",
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.50"
7
+ version = "0.1.51"
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"