@cliptude/cli 0.1.51 → 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,6 +563,8 @@ 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)
@@ -551,6 +594,121 @@ class CliptudeClient:
551
594
  """The user's brand kits (one per channel): logo, colours, fonts; one is the default."""
552
595
  return self.request("GET", "/api/v1/brand-kits")
553
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
+
554
712
  def list_media(self, *, folder: str | None = None, kind: str | None = None, limit: int = 50,
555
713
  offset: int = 0) -> Any:
556
714
  """The user's media library (images, clips, audio; shared with the editor's uploads)."""
@@ -644,16 +802,24 @@ class CliptudeClient:
644
802
  thumbnail: dict[str, str] | None = None,
645
803
  vector_character_id: str | None = None,
646
804
  vector_reveal_mode: str | None = None,
805
+ vector_art_style: str | None = None,
806
+ vector_image_model: str | None = None,
647
807
  pronunciations: list[dict[str, str]] | None = None,
648
808
  visual_direction: str | None = None,
649
809
  captions: bool | None = None,
650
810
  look: str | None = None,
811
+ brand_kit_id: int | None = None,
651
812
  review_token: str | None = None,
652
813
  acknowledge: list[str] | None = None,
653
814
  review_only: bool | None = None,
815
+ sponsor: str | None = None,
816
+ sponsor_placement: str | None = None,
817
+ sponsor_bumpers: bool | None = None,
654
818
  ) -> Any:
655
819
  if voiceover_path and voiceover_url:
656
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)
657
823
  # visual_direction is deprecated: the description (prompt) carries the visual direction. Older callers still
658
824
  # send it, so it is appended to the prompt here, the same on every path (JSON, voiceover upload, talking head).
659
825
  prompt = merge_visual_direction(prompt, visual_direction)
@@ -725,6 +891,7 @@ class CliptudeClient:
725
891
  thumbnail=thumbnail,
726
892
  captions=captions,
727
893
  look=look,
894
+ brand_kit_id=brand_kit_id,
728
895
  review=_review_job_fields(review_token, acknowledge, review_only),
729
896
  )
730
897
  if vo_path:
@@ -739,10 +906,13 @@ class CliptudeClient:
739
906
  **_thumbnail_job_field(thumbnail, as_string=True),
740
907
  **({"vector_character_id": str(vector_character_id)} if vector_character_id else {}),
741
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 {}),
742
911
  **({"pronunciations": json.dumps(pronunciations)} if pronunciations is not None else {}),
743
912
  **({"visual_direction": visual_direction} if visual_direction else {}),
744
913
  **({"captions": "true" if captions else "false"} if captions is not None else {}),
745
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 {}),
746
916
  **({"prompt": prompt} if prompt else {}),
747
917
  **_review_job_fields(review_token, acknowledge, review_only, as_strings=True),
748
918
  }
@@ -779,6 +949,10 @@ class CliptudeClient:
779
949
  body["vector_character_id"] = str(vector_character_id)
780
950
  if vector_reveal_mode:
781
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)
782
956
  if pronunciations is not None:
783
957
  body["pronunciations"] = pronunciations
784
958
  if visual_direction:
@@ -787,6 +961,9 @@ class CliptudeClient:
787
961
  body["captions"] = bool(captions)
788
962
  if look is not None:
789
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)
790
967
  body.update(_review_job_fields(review_token, acknowledge, review_only))
791
968
  return self.request("POST", "/api/v1/jobs", json_body=body)
792
969
 
@@ -888,6 +1065,7 @@ class CliptudeClient:
888
1065
  thumbnail: dict[str, str] | None = None,
889
1066
  captions: bool | None = None,
890
1067
  look: str | None = None,
1068
+ brand_kit_id: int | None = None,
891
1069
  review: dict[str, Any] | None = None,
892
1070
  ) -> Any:
893
1071
  review = review or {}
@@ -897,6 +1075,9 @@ class CliptudeClient:
897
1075
  if look is not None:
898
1076
  captions_field["look"] = str(look).strip()
899
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))
900
1081
  review_strings = {k: (",".join(v) if isinstance(v, list) else ("true" if v is True else v))
901
1082
  for k, v in review.items()}
902
1083
  motion_extra = _motion_control_job_fields(
@@ -1209,10 +1390,12 @@ class CliptudeClient:
1209
1390
  compact: bool = False,
1210
1391
  types: list[str] | None = None,
1211
1392
  premium: bool = False,
1393
+ look: str | None = None,
1212
1394
  ) -> Any:
1213
1395
  """Every graphic an agent can place. compact: one summary line each; types: full entries for those;
1214
- premium: only the premium boards."""
1215
- 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}
1216
1399
  if compact:
1217
1400
  params["compact"] = "1"
1218
1401
  if premium:
@@ -1449,13 +1632,20 @@ class CliptudeClient:
1449
1632
  vector_reveal_mode: str | None = None,
1450
1633
  captions: bool | None = None,
1451
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,
1452
1639
  ) -> Any:
1453
1640
  """Credits a job would need; creates nothing."""
1641
+ prompt = merge_sponsor(prompt, sponsor, sponsor_placement, sponsor_bumpers)
1454
1642
  body: dict[str, Any] = {"template_id": template_id}
1455
1643
  if captions is not None:
1456
1644
  body["captions"] = bool(captions)
1457
1645
  if look is not None:
1458
1646
  body["look"] = str(look).strip()
1647
+ if brand_kit_id is not None:
1648
+ body["brand_kit_id"] = int(brand_kit_id)
1459
1649
  if render_only:
1460
1650
  body["render_only"] = True
1461
1651
  for key, value in (