@cliptude/cli 0.1.50 → 0.1.52

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.
@@ -314,6 +314,29 @@ def merge_visual_direction(prompt: str | None, visual_direction: str | None) ->
314
314
  return text or None
315
315
 
316
316
 
317
+ def merge_sponsor(prompt: str | None, sponsor: str | None, placement: str | None = None,
318
+ bumpers: bool | None = None) -> str | None:
319
+ """The prompt with a sponsor sentence ("Sponsor: @nordvpn_ad after the intro.") for ``sponsor``: a media-library
320
+ video spliced in as a sponsored segment with its own sound (the server reads the sentence,
321
+ videos/sponsor_segments.py, and refuses a placement it cannot read when sent as the API's own params)."""
322
+ import re as _re
323
+
324
+ raw = str(sponsor or "").strip().lstrip("@")
325
+ text = (prompt or "").strip()
326
+ if not raw:
327
+ return text or None
328
+ token = _re.sub(r"[^0-9a-z]+", "_", _re.sub(r"\.[A-Za-z0-9]{2,4}$", "", raw).lower()).strip("_")
329
+ if not token:
330
+ raise CliptudeApiError("sponsor must name a media-library video, like @nordvpn_ad.")
331
+ if f"@{token}" in text.lower() and _re.search(r"\bsponsor", text, _re.I):
332
+ return text
333
+ where = " ".join(str(placement or "").split()).strip().rstrip(".")
334
+ if _re.fullmatch(r"(?i)auto(matic)?|anywhere|", where):
335
+ where = ""
336
+ sentence = f"Sponsor: @{token}" + (f" {where}" if where else "") + (", no bumpers" if bumpers is False else "") + "."
337
+ return f"{text}\n\n{sentence}".strip() if text else sentence
338
+
339
+
317
340
  def _review_job_fields(review_token: str | None, acknowledge: list[str] | None, review_only: bool | None,
318
341
  *, as_strings: bool = False) -> dict[str, Any]:
319
342
  """The job review: Cliptude answers a job without a review_token with the review (HTTP 428)."""
@@ -491,11 +514,24 @@ class CliptudeClient:
491
514
  def get_template(self, template_id: str) -> Any:
492
515
  return self.request("GET", f"/api/v1/templates/{_uuid_seg(template_id, 'template_id')}")
493
516
 
517
+ def _inline_brand_kit(self, brand_kit: dict[str, Any] | None, brand_kit_id: int | None) -> dict[str, Any] | None:
518
+ """A new kit sent with a template; a local ``logo_path`` in it is uploaded first."""
519
+ if brand_kit is None:
520
+ return None
521
+ if brand_kit_id is not None:
522
+ raise CliptudeApiError("Give brand_kit_id (an existing kit) or brand_kit (a new one), not both.")
523
+ kit = dict(brand_kit)
524
+ logo_path = kit.pop("logo_path", None)
525
+ return self._brand_kit_body(kit, logo_path)
526
+
494
527
  def create_template(self, *, name: str, format: str, settings: dict[str, Any],
495
528
  brand_kit_id: int | None = None, show_logo: bool | None = None,
496
- look: str | None = None, captions: bool | None = None) -> Any:
497
- """Create a ready-to-use template from settings (no create wizard); optional brand kit, logo, Look and
498
- whole-video captions (off by default)."""
529
+ look: str | None = None, captions: bool | None = None,
530
+ brand_kit: dict[str, Any] | None = None) -> Any:
531
+ """Create a ready-to-use template from settings (no create wizard); optional brand kit (an existing one by
532
+ id, or ``brand_kit``: a new kit made and attached in the same call), logo, Look and whole-video captions
533
+ (off by default)."""
534
+ new_kit = self._inline_brand_kit(brand_kit, brand_kit_id)
499
535
  settings = dict(settings or {})
500
536
  if captions is not None:
501
537
  settings["captions_enabled"] = bool(captions)
@@ -504,15 +540,20 @@ class CliptudeClient:
504
540
  body["look"] = look
505
541
  if brand_kit_id is not None:
506
542
  body["brand_kit_id"] = brand_kit_id or None
543
+ if new_kit is not None:
544
+ body["brand_kit"] = new_kit
507
545
  if show_logo is not None:
508
546
  body["show_logo"] = bool(show_logo)
509
- return self.request("POST", "/api/v1/templates", json_body=body)
547
+ # A new kit's logo_url is downloaded during the call.
548
+ return self.request("POST", "/api/v1/templates", json_body=body,
549
+ **({"timeout": max(self.timeout, 60.0)} if new_kit is not None else {}))
510
550
 
511
551
  def update_template(self, template_id: str, *, name: str | None = None, brand_kit_id: int | None = None,
512
552
  show_logo: bool | None = None, look: str | None = None,
513
- captions: bool | None = None) -> Any:
514
- """Rename a template, set its brand kit (0 = the user's default kit), its logo switch, its Look
515
- ('' removes the Look) or its whole-video captions."""
553
+ captions: bool | None = None, brand_kit: dict[str, Any] | None = None) -> Any:
554
+ """Rename a template, set its brand kit (0 = the user's default kit, or ``brand_kit``: a new kit made and
555
+ attached in the same call), its logo switch, its Look ('' removes the Look) or its whole-video captions."""
556
+ new_kit = self._inline_brand_kit(brand_kit, brand_kit_id)
516
557
  body: dict[str, Any] = {}
517
558
  if captions is not None:
518
559
  body["captions"] = bool(captions)
@@ -522,13 +563,21 @@ class CliptudeClient:
522
563
  body["name"] = name
523
564
  if brand_kit_id is not None:
524
565
  body["brand_kit_id"] = brand_kit_id or None
566
+ if new_kit is not None:
567
+ body["brand_kit"] = new_kit
525
568
  if show_logo is not None:
526
569
  body["show_logo"] = bool(show_logo)
527
570
  return self.request("PATCH", f"/api/v1/templates/{_uuid_seg(template_id, 'template_id')}", json_body=body)
528
571
 
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")
572
+ def list_looks(self, topic: str | None = None, format: str | None = None) -> Any:
573
+ """The prebuilt Looks (colours, captions, footage grade, the boards that carry each), with sample reels.
574
+ With ``topic`` the best fits come first with ``suggested: true`` and a ``reason``; ``format`` limits them."""
575
+ params: dict[str, Any] = {}
576
+ if topic and topic.strip():
577
+ params["topic"] = topic.strip()[:2000]
578
+ if format:
579
+ params["format"] = format
580
+ return self.request("GET", "/api/v1/looks", params=params or None)
532
581
 
533
582
  def save_look_as_template(self, slug: str, *, name: str | None = None, format: str | None = None) -> Any:
534
583
  """Copy a Look into one of the user's templates (format: any of the Look's formats); returns the template."""
@@ -545,6 +594,121 @@ class CliptudeClient:
545
594
  """The user's brand kits (one per channel): logo, colours, fonts; one is the default."""
546
595
  return self.request("GET", "/api/v1/brand-kits")
547
596
 
597
+ def _public_get(self, path: str, params: dict[str, Any] | None = None) -> Any:
598
+ """GET a public endpoint (the docs): sends the session when there is one, works without signing in."""
599
+ if self.connection_error:
600
+ raise CliptudeApiError(self.connection_error)
601
+ if self.api_key:
602
+ return self.request("GET", path, params=params)
603
+ headers = {"Accept": "application/json", **django_proxy_headers(self.base_url)}
604
+ if self.client_kind:
605
+ headers["X-Cliptude-Client"] = self.client_kind
606
+ try:
607
+ resp = httpx.get(f"{self.base_url}{path}", headers=headers, params=params, timeout=self.timeout)
608
+ except httpx.HTTPError as exc:
609
+ raise CliptudeApiError(str(exc)) from exc
610
+ try:
611
+ payload = resp.json()
612
+ except ValueError:
613
+ payload = {"error": resp.text}
614
+ if resp.status_code >= 400:
615
+ message = payload.get("error") if isinstance(payload, dict) else str(payload)
616
+ raise CliptudeApiError(message or f"HTTP {resp.status_code}", status=resp.status_code, payload=payload)
617
+ return payload
618
+
619
+ def list_docs(self, *, category: str | None = None) -> Any:
620
+ """Every Cliptude docs page: slug, title, url, category, summary and its main section headings."""
621
+ return self._public_get("/api/v1/docs", {"category": category} if category else None)
622
+
623
+ def search_docs(self, query: str, *, limit: int = 8) -> Any:
624
+ """Docs sections ranked for a question: page title, section heading, url and a ~600-character excerpt."""
625
+ query = " ".join(str(query or "").split())
626
+ if not query:
627
+ raise CliptudeApiError("query is required.", status=400)
628
+ return self._public_get("/api/v1/docs/search", {"q": query[:300], "limit": max(1, min(int(limit), 20))})
629
+
630
+ def read_doc(self, slug: str, *, section: str | None = None, offset: int = 0, max_chars: int = 20000) -> Any:
631
+ """One docs page as Markdown (or one heading's section), up to max_chars from offset; next_offset pages on."""
632
+ text = str(slug or "").strip().strip("/")
633
+ text = re.sub(r"^(https?://[^/]+)?/?docs/", "", text).split("#", 1)[0].strip("/") or "overview"
634
+ if not re.fullmatch(r"[a-z0-9][a-z0-9_-]{0,80}", text.lower()):
635
+ raise CliptudeApiError("slug must be a docs page slug from list_docs or search_docs, e.g. credits.",
636
+ status=400)
637
+ params: dict[str, Any] = {"offset": max(0, int(offset)), "max_chars": max(500, min(int(max_chars), 20000))}
638
+ if section and section.strip():
639
+ params["section"] = section.strip()[:200]
640
+ return self._public_get(f"/api/v1/docs/{quote(text.lower(), safe='')}", params)
641
+
642
+ def brand_kit_options(self) -> Any:
643
+ """Fonts, weights, logo positions, colour format and limits a brand kit may use."""
644
+ return self.request("GET", "/api/v1/brand-kits/options")
645
+
646
+ def get_brand_kit(self, kit_id: int | str) -> Any:
647
+ return self.request("GET", f"/api/v1/brand-kits/{_int_seg(kit_id, 'kit_id')}")
648
+
649
+ def _brand_kit_body(self, fields: dict[str, Any], logo_path: str | Path | None) -> dict[str, Any]:
650
+ body = {k: v for k, v in fields.items() if v is not None}
651
+ if logo_path:
652
+ if body.get("logo_url") or body.get("logo_media_id"):
653
+ raise CliptudeApiError("Give one logo: logo_path, logo_url or logo_media_id.")
654
+ body["logo_media_id"] = self.upload_brand_logo(logo_path)["media_id"]
655
+ return body
656
+
657
+ def create_brand_kit(self, *, name: str, logo_path: str | Path | None = None, **fields: Any) -> Any:
658
+ """A new brand kit: name plus any of channel_name, channel_handle, colors, fonts, logo_position,
659
+ logo_media_id, logo_url, is_default. ``logo_path`` (a local file) is uploaded first."""
660
+ body = self._brand_kit_body({"name": name, **fields}, logo_path)
661
+ return self.request("POST", "/api/v1/brand-kits", json_body=body, timeout=max(self.timeout, 60.0))
662
+
663
+ def update_brand_kit(self, kit_id: int | str, *, logo_path: str | Path | None = None, **fields: Any) -> Any:
664
+ """Change only the fields given (None = unchanged); ``logo_path`` is uploaded and becomes the logo."""
665
+ body = self._brand_kit_body(fields, logo_path)
666
+ if not body:
667
+ raise CliptudeApiError("Nothing to change: give a field to update.")
668
+ return self.request("PATCH", f"/api/v1/brand-kits/{_int_seg(kit_id, 'kit_id')}", json_body=body,
669
+ timeout=max(self.timeout, 60.0))
670
+
671
+ def set_default_brand_kit(self, kit_id: int | str) -> Any:
672
+ return self.request("POST", f"/api/v1/brand-kits/{_int_seg(kit_id, 'kit_id')}/default")
673
+
674
+ def delete_brand_kit(self, kit_id: int | str) -> Any:
675
+ return self.request("DELETE", f"/api/v1/brand-kits/{_int_seg(kit_id, 'kit_id')}")
676
+
677
+ def start_brand_upload(self, *, filename: str, size: int, content_type: str | None = None) -> dict[str, Any]:
678
+ """Signed PUT URLs for a logo (PNG, JPG or WebP, up to 5 MB), for a host that sends the bytes itself."""
679
+ return self._start_signed_upload("/api/v1/uploads/brand", filename=filename, size=size, content_type=content_type)
680
+
681
+ def finish_brand_upload(self, *, key: str, upload_id: str, kit_id: int | str | None = None) -> Any:
682
+ """Returns {media_id, url, ...}; with kit_id the logo goes on that kit at once (brand_kit in the result)."""
683
+ body: dict[str, Any] = {"key": key, "upload_id": upload_id}
684
+ if kit_id not in (None, ""):
685
+ body["kit_id"] = int(_int_seg(kit_id, "kit_id"))
686
+ return self.request("POST", "/api/v1/uploads/brand/complete", json_body=body, timeout=max(self.timeout, 60.0))
687
+
688
+ def abort_brand_upload(self, *, key: str, upload_id: str) -> Any:
689
+ return self.request("POST", "/api/v1/uploads/brand/abort", json_body={"key": key, "upload_id": upload_id})
690
+
691
+ def upload_brand_logo(self, path: str | Path, *, kit_id: int | str | None = None) -> Any:
692
+ """Upload a local logo file through the signed-URL flow; returns {media_id, url, ...}."""
693
+ path = self._local_file(path, "logo_path")
694
+ if not path.is_file():
695
+ raise CliptudeApiError(f"Logo file not found: {path}")
696
+ init = self.request("POST", "/api/v1/uploads/brand/init", json_body={
697
+ "filename": path.name,
698
+ "size": path.stat().st_size,
699
+ "content_type": mimetypes.guess_type(path.name)[0] or "application/octet-stream",
700
+ })
701
+ body = {"key": (init or {}).get("key"), "upload_id": (init or {}).get("upload_id")}
702
+ try:
703
+ self._upload_parts(path, init, "/api/v1/uploads/brand/sign-parts", "logo")
704
+ return self.finish_brand_upload(key=body["key"], upload_id=body["upload_id"], kit_id=kit_id)
705
+ except Exception:
706
+ try:
707
+ self.request("POST", "/api/v1/uploads/brand/abort", json_body=body)
708
+ except Exception:
709
+ pass
710
+ raise
711
+
548
712
  def list_media(self, *, folder: str | None = None, kind: str | None = None, limit: int = 50,
549
713
  offset: int = 0) -> Any:
550
714
  """The user's media library (images, clips, audio; shared with the editor's uploads)."""
@@ -638,15 +802,24 @@ class CliptudeClient:
638
802
  thumbnail: dict[str, str] | None = None,
639
803
  vector_character_id: str | None = None,
640
804
  vector_reveal_mode: str | None = None,
805
+ vector_art_style: str | None = None,
806
+ vector_image_model: str | None = None,
641
807
  pronunciations: list[dict[str, str]] | None = None,
642
808
  visual_direction: str | None = None,
643
809
  captions: bool | None = None,
810
+ look: str | None = None,
811
+ brand_kit_id: int | None = None,
644
812
  review_token: str | None = None,
645
813
  acknowledge: list[str] | None = None,
646
814
  review_only: bool | None = None,
815
+ sponsor: str | None = None,
816
+ sponsor_placement: str | None = None,
817
+ sponsor_bumpers: bool | None = None,
647
818
  ) -> Any:
648
819
  if voiceover_path and voiceover_url:
649
820
  raise CliptudeApiError("Give voiceover_path or voiceover_url, not both.")
821
+ # A sponsored segment is a sentence in the description, the same on every path.
822
+ prompt = merge_sponsor(prompt, sponsor, sponsor_placement, sponsor_bumpers)
650
823
  # visual_direction is deprecated: the description (prompt) carries the visual direction. Older callers still
651
824
  # send it, so it is appended to the prompt here, the same on every path (JSON, voiceover upload, talking head).
652
825
  prompt = merge_visual_direction(prompt, visual_direction)
@@ -717,6 +890,8 @@ class CliptudeClient:
717
890
  excluded_transition_kinds=excluded_transition_kinds,
718
891
  thumbnail=thumbnail,
719
892
  captions=captions,
893
+ look=look,
894
+ brand_kit_id=brand_kit_id,
720
895
  review=_review_job_fields(review_token, acknowledge, review_only),
721
896
  )
722
897
  if vo_path:
@@ -731,9 +906,13 @@ class CliptudeClient:
731
906
  **_thumbnail_job_field(thumbnail, as_string=True),
732
907
  **({"vector_character_id": str(vector_character_id)} if vector_character_id else {}),
733
908
  **({"vector_reveal_mode": str(vector_reveal_mode)} if vector_reveal_mode else {}),
909
+ **({"vector_art_style": str(vector_art_style)} if vector_art_style else {}),
910
+ **({"vector_image_model": str(vector_image_model)} if vector_image_model else {}),
734
911
  **({"pronunciations": json.dumps(pronunciations)} if pronunciations is not None else {}),
735
912
  **({"visual_direction": visual_direction} if visual_direction else {}),
736
913
  **({"captions": "true" if captions else "false"} if captions is not None else {}),
914
+ **({"look": str(look).strip() or "none"} if look is not None else {}),
915
+ **({"brand_kit_id": str(int(brand_kit_id))} if brand_kit_id is not None else {}),
737
916
  **({"prompt": prompt} if prompt else {}),
738
917
  **_review_job_fields(review_token, acknowledge, review_only, as_strings=True),
739
918
  }
@@ -770,12 +949,21 @@ class CliptudeClient:
770
949
  body["vector_character_id"] = str(vector_character_id)
771
950
  if vector_reveal_mode:
772
951
  body["vector_reveal_mode"] = str(vector_reveal_mode)
952
+ if vector_art_style is not None:
953
+ body["vector_art_style"] = str(vector_art_style)
954
+ if vector_image_model:
955
+ body["vector_image_model"] = str(vector_image_model)
773
956
  if pronunciations is not None:
774
957
  body["pronunciations"] = pronunciations
775
958
  if visual_direction:
776
959
  body["visual_direction"] = visual_direction
777
960
  if captions is not None:
778
961
  body["captions"] = bool(captions)
962
+ if look is not None:
963
+ body["look"] = str(look).strip()
964
+ if brand_kit_id is not None:
965
+ # The job's own brand kit (0 = the default kit); omitted = the template's.
966
+ body["brand_kit_id"] = int(brand_kit_id)
779
967
  body.update(_review_job_fields(review_token, acknowledge, review_only))
780
968
  return self.request("POST", "/api/v1/jobs", json_body=body)
781
969
 
@@ -876,11 +1064,20 @@ class CliptudeClient:
876
1064
  excluded_transition_kinds: list[str] | None = None,
877
1065
  thumbnail: dict[str, str] | None = None,
878
1066
  captions: bool | None = None,
1067
+ look: str | None = None,
1068
+ brand_kit_id: int | None = None,
879
1069
  review: dict[str, Any] | None = None,
880
1070
  ) -> Any:
881
1071
  review = review or {}
882
1072
  captions_field = {"captions": bool(captions)} if captions is not None else {}
883
1073
  captions_str = {"captions": "true" if captions else "false"} if captions is not None else {}
1074
+ # The job's Look rides with captions on every talking-head path ("none" = no Look; multipart drops "").
1075
+ if look is not None:
1076
+ captions_field["look"] = str(look).strip()
1077
+ captions_str["look"] = str(look).strip() or "none"
1078
+ if brand_kit_id is not None:
1079
+ captions_field["brand_kit_id"] = int(brand_kit_id)
1080
+ captions_str["brand_kit_id"] = str(int(brand_kit_id))
884
1081
  review_strings = {k: (",".join(v) if isinstance(v, list) else ("true" if v is True else v))
885
1082
  for k, v in review.items()}
886
1083
  motion_extra = _motion_control_job_fields(
@@ -1193,10 +1390,12 @@ class CliptudeClient:
1193
1390
  compact: bool = False,
1194
1391
  types: list[str] | None = None,
1195
1392
  premium: bool = False,
1393
+ look: str | None = None,
1196
1394
  ) -> Any:
1197
1395
  """Every graphic an agent can place. compact: one summary line each; types: full entries for those;
1198
- premium: only the premium boards."""
1199
- params = {k: v for k, v in (("format", format), ("theme", theme)) if v}
1396
+ premium: only the premium boards; look: the job's Look slug (a Look with a spec lists only its own boards,
1397
+ and check_plan refuses the others)."""
1398
+ params = {k: v for k, v in (("format", format), ("theme", theme), ("look", look)) if v}
1200
1399
  if compact:
1201
1400
  params["compact"] = "1"
1202
1401
  if premium:
@@ -1432,11 +1631,21 @@ class CliptudeClient:
1432
1631
  render_only: bool | None = None,
1433
1632
  vector_reveal_mode: str | None = None,
1434
1633
  captions: bool | None = None,
1634
+ look: str | None = None,
1635
+ sponsor: str | None = None,
1636
+ sponsor_placement: str | None = None,
1637
+ sponsor_bumpers: bool | None = None,
1638
+ brand_kit_id: int | None = None,
1435
1639
  ) -> Any:
1436
1640
  """Credits a job would need; creates nothing."""
1641
+ prompt = merge_sponsor(prompt, sponsor, sponsor_placement, sponsor_bumpers)
1437
1642
  body: dict[str, Any] = {"template_id": template_id}
1438
1643
  if captions is not None:
1439
1644
  body["captions"] = bool(captions)
1645
+ if look is not None:
1646
+ body["look"] = str(look).strip()
1647
+ if brand_kit_id is not None:
1648
+ body["brand_kit_id"] = int(brand_kit_id)
1440
1649
  if render_only:
1441
1650
  body["render_only"] = True
1442
1651
  for key, value in (