@cliptude/cli 0.1.51 → 0.1.53

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,77 @@ 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
+
340
+ MAX_AROLLS = 4
341
+
342
+
343
+ def merge_aroll(prompt: str | None, aroll: Any) -> str | None:
344
+ """The prompt with one "A-roll: @clip after "<a line of the script>"." sentence per ``aroll`` item: the user's own
345
+ clip of someone speaking, spliced in between two sentences with its own sound (the narration pauses for it).
346
+ Items: "@clip" or {"media": "@clip", "placement": 'after "a line"'} (or "after": "a line"). The server reads the
347
+ sentence (videos/sponsor_segments.py) and refuses a line the script does not say."""
348
+ import re as _re
349
+
350
+ text = (prompt or "").strip()
351
+ items = aroll if isinstance(aroll, (list, tuple)) else ([aroll] if aroll else [])
352
+ if len(items) > MAX_AROLLS:
353
+ raise CliptudeApiError(f"A video can have at most {MAX_AROLLS} A-roll clips; you sent {len(items)}.")
354
+ sentences = []
355
+ for item in items:
356
+ if isinstance(item, dict):
357
+ raw = str(item.get("media") or item.get("file") or item.get("token") or "")
358
+ where = str(item.get("placement") or "")
359
+ if not where and item.get("after"):
360
+ where = f'after "{item["after"]}"'
361
+ if not where and item.get("before"):
362
+ where = f'before "{item["before"]}"'
363
+ says = str(item.get("says") or item.get("transcript") or "").strip()
364
+ if says:
365
+ where = f'{where} says "{says}"'.strip()
366
+ else:
367
+ raw, where = str(item or ""), ""
368
+ raw = raw.strip().lstrip("@")
369
+ token = _re.sub(r"[^0-9a-z]+", "_", _re.sub(r"\.[A-Za-z0-9]{2,4}$", "", raw).lower()).strip("_")
370
+ if not token:
371
+ raise CliptudeApiError("Each aroll item names a media-library video, like @kress_interview.")
372
+ if f"@{token}" in text.lower() and _re.search(r"\ba[- ]?roll", text, _re.I):
373
+ continue
374
+ # . ! ? inside a quoted line would end the tag's sentence early on the server; the line matches without them.
375
+ where = _re.sub(r'(["“])([^"“”]*)(["”])',
376
+ lambda q: q.group(1) + " ".join(_re.sub(r"[.!?…\n]+", " ", q.group(2)).split()) + q.group(3),
377
+ where)
378
+ where = " ".join(where.split()).strip().rstrip(".")
379
+ if _re.fullmatch(r"(?i)auto(matic)?|anywhere|", where):
380
+ where = ""
381
+ sentences.append(f"A-roll: @{token}" + (f" {where}" if where else "") + ".")
382
+ if not sentences:
383
+ return text or None
384
+ joined = "\n".join(sentences)
385
+ return f"{text}\n\n{joined}".strip() if text else joined
386
+
387
+
317
388
  def _review_job_fields(review_token: str | None, acknowledge: list[str] | None, review_only: bool | None,
318
389
  *, as_strings: bool = False) -> dict[str, Any]:
319
390
  """The job review: Cliptude answers a job without a review_token with the review (HTTP 428)."""
@@ -491,11 +562,24 @@ class CliptudeClient:
491
562
  def get_template(self, template_id: str) -> Any:
492
563
  return self.request("GET", f"/api/v1/templates/{_uuid_seg(template_id, 'template_id')}")
493
564
 
565
+ def _inline_brand_kit(self, brand_kit: dict[str, Any] | None, brand_kit_id: int | None) -> dict[str, Any] | None:
566
+ """A new kit sent with a template; a local ``logo_path`` in it is uploaded first."""
567
+ if brand_kit is None:
568
+ return None
569
+ if brand_kit_id is not None:
570
+ raise CliptudeApiError("Give brand_kit_id (an existing kit) or brand_kit (a new one), not both.")
571
+ kit = dict(brand_kit)
572
+ logo_path = kit.pop("logo_path", None)
573
+ return self._brand_kit_body(kit, logo_path)
574
+
494
575
  def create_template(self, *, name: str, format: str, settings: dict[str, Any],
495
576
  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)."""
577
+ look: str | None = None, captions: bool | None = None,
578
+ brand_kit: dict[str, Any] | None = None) -> Any:
579
+ """Create a ready-to-use template from settings (no create wizard); optional brand kit (an existing one by
580
+ id, or ``brand_kit``: a new kit made and attached in the same call), logo, Look and whole-video captions
581
+ (off by default)."""
582
+ new_kit = self._inline_brand_kit(brand_kit, brand_kit_id)
499
583
  settings = dict(settings or {})
500
584
  if captions is not None:
501
585
  settings["captions_enabled"] = bool(captions)
@@ -504,15 +588,20 @@ class CliptudeClient:
504
588
  body["look"] = look
505
589
  if brand_kit_id is not None:
506
590
  body["brand_kit_id"] = brand_kit_id or None
591
+ if new_kit is not None:
592
+ body["brand_kit"] = new_kit
507
593
  if show_logo is not None:
508
594
  body["show_logo"] = bool(show_logo)
509
- return self.request("POST", "/api/v1/templates", json_body=body)
595
+ # A new kit's logo_url is downloaded during the call.
596
+ return self.request("POST", "/api/v1/templates", json_body=body,
597
+ **({"timeout": max(self.timeout, 60.0)} if new_kit is not None else {}))
510
598
 
511
599
  def update_template(self, template_id: str, *, name: str | None = None, brand_kit_id: int | None = None,
512
600
  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."""
601
+ captions: bool | None = None, brand_kit: dict[str, Any] | None = None) -> Any:
602
+ """Rename a template, set its brand kit (0 = the user's default kit, or ``brand_kit``: a new kit made and
603
+ attached in the same call), its logo switch, its Look ('' removes the Look) or its whole-video captions."""
604
+ new_kit = self._inline_brand_kit(brand_kit, brand_kit_id)
516
605
  body: dict[str, Any] = {}
517
606
  if captions is not None:
518
607
  body["captions"] = bool(captions)
@@ -522,6 +611,8 @@ class CliptudeClient:
522
611
  body["name"] = name
523
612
  if brand_kit_id is not None:
524
613
  body["brand_kit_id"] = brand_kit_id or None
614
+ if new_kit is not None:
615
+ body["brand_kit"] = new_kit
525
616
  if show_logo is not None:
526
617
  body["show_logo"] = bool(show_logo)
527
618
  return self.request("PATCH", f"/api/v1/templates/{_uuid_seg(template_id, 'template_id')}", json_body=body)
@@ -551,6 +642,184 @@ class CliptudeClient:
551
642
  """The user's brand kits (one per channel): logo, colours, fonts; one is the default."""
552
643
  return self.request("GET", "/api/v1/brand-kits")
553
644
 
645
+ def _public_get(self, path: str, params: dict[str, Any] | None = None) -> Any:
646
+ """GET a public endpoint (the docs): sends the session when there is one, works without signing in."""
647
+ if self.connection_error:
648
+ raise CliptudeApiError(self.connection_error)
649
+ if self.api_key:
650
+ return self.request("GET", path, params=params)
651
+ headers = {"Accept": "application/json", **django_proxy_headers(self.base_url)}
652
+ if self.client_kind:
653
+ headers["X-Cliptude-Client"] = self.client_kind
654
+ try:
655
+ resp = httpx.get(f"{self.base_url}{path}", headers=headers, params=params, timeout=self.timeout)
656
+ except httpx.HTTPError as exc:
657
+ raise CliptudeApiError(str(exc)) from exc
658
+ try:
659
+ payload = resp.json()
660
+ except ValueError:
661
+ payload = {"error": resp.text}
662
+ if resp.status_code >= 400:
663
+ message = payload.get("error") if isinstance(payload, dict) else str(payload)
664
+ raise CliptudeApiError(message or f"HTTP {resp.status_code}", status=resp.status_code, payload=payload)
665
+ return payload
666
+
667
+ def list_docs(self, *, category: str | None = None) -> Any:
668
+ """Every Cliptude docs page: slug, title, url, category, summary and its main section headings."""
669
+ return self._public_get("/api/v1/docs", {"category": category} if category else None)
670
+
671
+ def search_docs(self, query: str, *, limit: int = 8) -> Any:
672
+ """Docs sections ranked for a question: page title, section heading, url and a ~600-character excerpt."""
673
+ query = " ".join(str(query or "").split())
674
+ if not query:
675
+ raise CliptudeApiError("query is required.", status=400)
676
+ return self._public_get("/api/v1/docs/search", {"q": query[:300], "limit": max(1, min(int(limit), 20))})
677
+
678
+ def read_doc(self, slug: str, *, section: str | None = None, offset: int = 0, max_chars: int = 20000) -> Any:
679
+ """One docs page as Markdown (or one heading's section), up to max_chars from offset; next_offset pages on."""
680
+ text = str(slug or "").strip().strip("/")
681
+ text = re.sub(r"^(https?://[^/]+)?/?docs/", "", text).split("#", 1)[0].strip("/") or "overview"
682
+ if not re.fullmatch(r"[a-z0-9][a-z0-9_-]{0,80}", text.lower()):
683
+ raise CliptudeApiError("slug must be a docs page slug from list_docs or search_docs, e.g. credits.",
684
+ status=400)
685
+ params: dict[str, Any] = {"offset": max(0, int(offset)), "max_chars": max(500, min(int(max_chars), 20000))}
686
+ if section and section.strip():
687
+ params["section"] = section.strip()[:200]
688
+ return self._public_get(f"/api/v1/docs/{quote(text.lower(), safe='')}", params)
689
+
690
+ def brand_kit_options(self) -> Any:
691
+ """Fonts, weights, logo positions, colour format and limits a brand kit may use."""
692
+ return self.request("GET", "/api/v1/brand-kits/options")
693
+
694
+ def get_brand_kit(self, kit_id: int | str) -> Any:
695
+ return self.request("GET", f"/api/v1/brand-kits/{_int_seg(kit_id, 'kit_id')}")
696
+
697
+ def _brand_kit_body(self, fields: dict[str, Any], logo_path: str | Path | None) -> dict[str, Any]:
698
+ body = {k: v for k, v in fields.items() if v is not None}
699
+ if logo_path:
700
+ if body.get("logo_url") or body.get("logo_media_id"):
701
+ raise CliptudeApiError("Give one logo: logo_path, logo_url or logo_media_id.")
702
+ body["logo_media_id"] = self.upload_brand_logo(logo_path)["media_id"]
703
+ return body
704
+
705
+ def create_brand_kit(self, *, name: str, logo_path: str | Path | None = None, **fields: Any) -> Any:
706
+ """A new brand kit: name plus any of channel_name, channel_handle, colors, fonts, logo_position,
707
+ logo_media_id, logo_url, is_default. ``logo_path`` (a local file) is uploaded first."""
708
+ body = self._brand_kit_body({"name": name, **fields}, logo_path)
709
+ return self.request("POST", "/api/v1/brand-kits", json_body=body, timeout=max(self.timeout, 60.0))
710
+
711
+ def update_brand_kit(self, kit_id: int | str, *, logo_path: str | Path | None = None, **fields: Any) -> Any:
712
+ """Change only the fields given (None = unchanged); ``logo_path`` is uploaded and becomes the logo."""
713
+ body = self._brand_kit_body(fields, logo_path)
714
+ if not body:
715
+ raise CliptudeApiError("Nothing to change: give a field to update.")
716
+ return self.request("PATCH", f"/api/v1/brand-kits/{_int_seg(kit_id, 'kit_id')}", json_body=body,
717
+ timeout=max(self.timeout, 60.0))
718
+
719
+ def set_default_brand_kit(self, kit_id: int | str) -> Any:
720
+ return self.request("POST", f"/api/v1/brand-kits/{_int_seg(kit_id, 'kit_id')}/default")
721
+
722
+ def delete_brand_kit(self, kit_id: int | str) -> Any:
723
+ return self.request("DELETE", f"/api/v1/brand-kits/{_int_seg(kit_id, 'kit_id')}")
724
+
725
+ def start_brand_upload(self, *, filename: str, size: int, content_type: str | None = None) -> dict[str, Any]:
726
+ """Signed PUT URLs for a logo (PNG, JPG or WebP, up to 5 MB), for a host that sends the bytes itself."""
727
+ return self._start_signed_upload("/api/v1/uploads/brand", filename=filename, size=size, content_type=content_type)
728
+
729
+ def finish_brand_upload(self, *, key: str, upload_id: str, kit_id: int | str | None = None) -> Any:
730
+ """Returns {media_id, url, ...}; with kit_id the logo goes on that kit at once (brand_kit in the result)."""
731
+ body: dict[str, Any] = {"key": key, "upload_id": upload_id}
732
+ if kit_id not in (None, ""):
733
+ body["kit_id"] = int(_int_seg(kit_id, "kit_id"))
734
+ return self.request("POST", "/api/v1/uploads/brand/complete", json_body=body, timeout=max(self.timeout, 60.0))
735
+
736
+ def abort_brand_upload(self, *, key: str, upload_id: str) -> Any:
737
+ return self.request("POST", "/api/v1/uploads/brand/abort", json_body={"key": key, "upload_id": upload_id})
738
+
739
+ def upload_brand_logo(self, path: str | Path, *, kit_id: int | str | None = None) -> Any:
740
+ """Upload a local logo file through the signed-URL flow; returns {media_id, url, ...}."""
741
+ path = self._local_file(path, "logo_path")
742
+ if not path.is_file():
743
+ raise CliptudeApiError(f"Logo file not found: {path}")
744
+ init = self.request("POST", "/api/v1/uploads/brand/init", json_body={
745
+ "filename": path.name,
746
+ "size": path.stat().st_size,
747
+ "content_type": mimetypes.guess_type(path.name)[0] or "application/octet-stream",
748
+ })
749
+ body = {"key": (init or {}).get("key"), "upload_id": (init or {}).get("upload_id")}
750
+ try:
751
+ self._upload_parts(path, init, "/api/v1/uploads/brand/sign-parts", "logo")
752
+ return self.finish_brand_upload(key=body["key"], upload_id=body["upload_id"], kit_id=kit_id)
753
+ except Exception:
754
+ try:
755
+ self.request("POST", "/api/v1/uploads/brand/abort", json_body=body)
756
+ except Exception:
757
+ pass
758
+ raise
759
+
760
+ # --- media library uploads (pictures, clips, audio; videos/library_upload.py) -------------------------------
761
+
762
+ def start_library_upload(self, *, filename: str, size: int, content_type: str | None = None) -> dict[str, Any]:
763
+ """Signed PUT URLs for one media-library file (picture up to 15 MB, clip up to 300 MB, audio up to 95 MB),
764
+ for a host that sends the bytes itself."""
765
+ return self._start_signed_upload("/api/v1/uploads/library", filename=filename, size=size,
766
+ content_type=content_type)
767
+
768
+ def finish_library_upload(self, *, key: str, upload_id: str, folder: str | None = None,
769
+ name: str | None = None) -> Any:
770
+ """Returns the file as list_media shows it, with its media_id and @tag."""
771
+ body: dict[str, Any] = {"key": key, "upload_id": upload_id}
772
+ if folder:
773
+ body["folder"] = folder
774
+ if name:
775
+ body["name"] = name
776
+ return self.request("POST", "/api/v1/uploads/library/complete", json_body=body,
777
+ timeout=max(self.timeout, 180.0))
778
+
779
+ def abort_library_upload(self, *, key: str, upload_id: str) -> Any:
780
+ return self.request("POST", "/api/v1/uploads/library/abort", json_body={"key": key, "upload_id": upload_id})
781
+
782
+ def upload_to_library(self, path: str | Path, *, folder: str | None = None, name: str | None = None) -> Any:
783
+ """Upload one local file to the media library through the signed-URL flow; returns {media_id, tag, url, ...}."""
784
+ path = self._local_file(path, "path")
785
+ if not path.is_file():
786
+ raise CliptudeApiError(f"File not found: {path}")
787
+ init = self.request("POST", "/api/v1/uploads/library/init", json_body={
788
+ "filename": path.name,
789
+ "size": path.stat().st_size,
790
+ "content_type": mimetypes.guess_type(path.name)[0] or "application/octet-stream",
791
+ })
792
+ body = {"key": (init or {}).get("key"), "upload_id": (init or {}).get("upload_id")}
793
+ try:
794
+ self._upload_parts(path, init, "/api/v1/uploads/library/sign-parts", path.name)
795
+ return self.finish_library_upload(key=body["key"], upload_id=body["upload_id"], folder=folder, name=name)
796
+ except Exception:
797
+ try:
798
+ self.request("POST", "/api/v1/uploads/library/abort", json_body=body)
799
+ except Exception:
800
+ pass
801
+ raise
802
+
803
+ def upload_many_to_library(self, paths: list[str | Path], *, folder: str | None = None) -> dict[str, Any]:
804
+ """Upload several local files (one at a time; a failure does not stop the rest). Returns
805
+ {uploaded: [...], failed: [{path, error}]}."""
806
+ uploaded, failed = [], []
807
+ for p in paths:
808
+ try:
809
+ uploaded.append(self.upload_to_library(p, folder=folder))
810
+ except Exception as exc: # one bad file must not lose the others
811
+ failed.append({"path": str(p), "error": str(exc)})
812
+ return {"uploaded": uploaded, "failed": failed}
813
+
814
+ def import_media(self, *, url: str, folder: str | None = None, name: str | None = None) -> Any:
815
+ """Download a public https link (picture, clip or audio) into the media library."""
816
+ body: dict[str, Any] = {"url": url}
817
+ if folder:
818
+ body["folder"] = folder
819
+ if name:
820
+ body["name"] = name
821
+ return self.request("POST", "/api/v1/media/import", json_body=body, timeout=max(self.timeout, 180.0))
822
+
554
823
  def list_media(self, *, folder: str | None = None, kind: str | None = None, limit: int = 50,
555
824
  offset: int = 0) -> Any:
556
825
  """The user's media library (images, clips, audio; shared with the editor's uploads)."""
@@ -644,16 +913,26 @@ class CliptudeClient:
644
913
  thumbnail: dict[str, str] | None = None,
645
914
  vector_character_id: str | None = None,
646
915
  vector_reveal_mode: str | None = None,
916
+ vector_art_style: str | None = None,
917
+ vector_image_model: str | None = None,
647
918
  pronunciations: list[dict[str, str]] | None = None,
648
919
  visual_direction: str | None = None,
649
920
  captions: bool | None = None,
650
921
  look: str | None = None,
922
+ brand_kit_id: int | None = None,
651
923
  review_token: str | None = None,
652
924
  acknowledge: list[str] | None = None,
653
925
  review_only: bool | None = None,
926
+ sponsor: str | None = None,
927
+ sponsor_placement: str | None = None,
928
+ sponsor_bumpers: bool | None = None,
929
+ aroll: Any = None,
930
+ include_aroll: bool | None = None,
654
931
  ) -> Any:
655
932
  if voiceover_path and voiceover_url:
656
933
  raise CliptudeApiError("Give voiceover_path or voiceover_url, not both.")
934
+ # A sponsored segment and A-roll clips are sentences in the description, the same on every path.
935
+ prompt = merge_aroll(merge_sponsor(prompt, sponsor, sponsor_placement, sponsor_bumpers), aroll)
657
936
  # visual_direction is deprecated: the description (prompt) carries the visual direction. Older callers still
658
937
  # send it, so it is appended to the prompt here, the same on every path (JSON, voiceover upload, talking head).
659
938
  prompt = merge_visual_direction(prompt, visual_direction)
@@ -725,6 +1004,7 @@ class CliptudeClient:
725
1004
  thumbnail=thumbnail,
726
1005
  captions=captions,
727
1006
  look=look,
1007
+ brand_kit_id=brand_kit_id,
728
1008
  review=_review_job_fields(review_token, acknowledge, review_only),
729
1009
  )
730
1010
  if vo_path:
@@ -739,10 +1019,14 @@ class CliptudeClient:
739
1019
  **_thumbnail_job_field(thumbnail, as_string=True),
740
1020
  **({"vector_character_id": str(vector_character_id)} if vector_character_id else {}),
741
1021
  **({"vector_reveal_mode": str(vector_reveal_mode)} if vector_reveal_mode else {}),
1022
+ **({"vector_art_style": str(vector_art_style)} if vector_art_style else {}),
1023
+ **({"vector_image_model": str(vector_image_model)} if vector_image_model else {}),
742
1024
  **({"pronunciations": json.dumps(pronunciations)} if pronunciations is not None else {}),
743
1025
  **({"visual_direction": visual_direction} if visual_direction else {}),
744
1026
  **({"captions": "true" if captions else "false"} if captions is not None else {}),
745
1027
  **({"look": str(look).strip() or "none"} if look is not None else {}),
1028
+ **({"brand_kit_id": str(int(brand_kit_id))} if brand_kit_id is not None else {}),
1029
+ **({"include_aroll": "true" if include_aroll else "false"} if include_aroll is not None else {}),
746
1030
  **({"prompt": prompt} if prompt else {}),
747
1031
  **_review_job_fields(review_token, acknowledge, review_only, as_strings=True),
748
1032
  }
@@ -769,6 +1053,8 @@ class CliptudeClient:
769
1053
  body["voiceover_url"] = str(voiceover_url).strip()
770
1054
  if render_only:
771
1055
  body["render_only"] = True
1056
+ if include_aroll is not None:
1057
+ body["include_aroll"] = bool(include_aroll)
772
1058
  body.update(_avatar_job_fields(
773
1059
  avatar_intro_only, avatar_ai_footage,
774
1060
  avatar_profile_id=avatar_profile_id, avatar_engine=avatar_engine,
@@ -779,6 +1065,10 @@ class CliptudeClient:
779
1065
  body["vector_character_id"] = str(vector_character_id)
780
1066
  if vector_reveal_mode:
781
1067
  body["vector_reveal_mode"] = str(vector_reveal_mode)
1068
+ if vector_art_style is not None:
1069
+ body["vector_art_style"] = str(vector_art_style)
1070
+ if vector_image_model:
1071
+ body["vector_image_model"] = str(vector_image_model)
782
1072
  if pronunciations is not None:
783
1073
  body["pronunciations"] = pronunciations
784
1074
  if visual_direction:
@@ -787,6 +1077,9 @@ class CliptudeClient:
787
1077
  body["captions"] = bool(captions)
788
1078
  if look is not None:
789
1079
  body["look"] = str(look).strip()
1080
+ if brand_kit_id is not None:
1081
+ # The job's own brand kit (0 = the default kit); omitted = the template's.
1082
+ body["brand_kit_id"] = int(brand_kit_id)
790
1083
  body.update(_review_job_fields(review_token, acknowledge, review_only))
791
1084
  return self.request("POST", "/api/v1/jobs", json_body=body)
792
1085
 
@@ -888,6 +1181,7 @@ class CliptudeClient:
888
1181
  thumbnail: dict[str, str] | None = None,
889
1182
  captions: bool | None = None,
890
1183
  look: str | None = None,
1184
+ brand_kit_id: int | None = None,
891
1185
  review: dict[str, Any] | None = None,
892
1186
  ) -> Any:
893
1187
  review = review or {}
@@ -897,6 +1191,9 @@ class CliptudeClient:
897
1191
  if look is not None:
898
1192
  captions_field["look"] = str(look).strip()
899
1193
  captions_str["look"] = str(look).strip() or "none"
1194
+ if brand_kit_id is not None:
1195
+ captions_field["brand_kit_id"] = int(brand_kit_id)
1196
+ captions_str["brand_kit_id"] = str(int(brand_kit_id))
900
1197
  review_strings = {k: (",".join(v) if isinstance(v, list) else ("true" if v is True else v))
901
1198
  for k, v in review.items()}
902
1199
  motion_extra = _motion_control_job_fields(
@@ -1209,10 +1506,12 @@ class CliptudeClient:
1209
1506
  compact: bool = False,
1210
1507
  types: list[str] | None = None,
1211
1508
  premium: bool = False,
1509
+ look: str | None = None,
1212
1510
  ) -> Any:
1213
1511
  """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}
1512
+ premium: only the premium boards; look: the job's Look slug (a Look with a spec lists only its own boards,
1513
+ and check_plan refuses the others)."""
1514
+ params = {k: v for k, v in (("format", format), ("theme", theme), ("look", look)) if v}
1216
1515
  if compact:
1217
1516
  params["compact"] = "1"
1218
1517
  if premium:
@@ -1449,13 +1748,24 @@ class CliptudeClient:
1449
1748
  vector_reveal_mode: str | None = None,
1450
1749
  captions: bool | None = None,
1451
1750
  look: str | None = None,
1751
+ sponsor: str | None = None,
1752
+ sponsor_placement: str | None = None,
1753
+ sponsor_bumpers: bool | None = None,
1754
+ brand_kit_id: int | None = None,
1755
+ aroll: Any = None,
1756
+ include_aroll: bool | None = None,
1452
1757
  ) -> Any:
1453
1758
  """Credits a job would need; creates nothing."""
1759
+ prompt = merge_aroll(merge_sponsor(prompt, sponsor, sponsor_placement, sponsor_bumpers), aroll)
1454
1760
  body: dict[str, Any] = {"template_id": template_id}
1761
+ if include_aroll is not None:
1762
+ body["include_aroll"] = bool(include_aroll)
1455
1763
  if captions is not None:
1456
1764
  body["captions"] = bool(captions)
1457
1765
  if look is not None:
1458
1766
  body["look"] = str(look).strip()
1767
+ if brand_kit_id is not None:
1768
+ body["brand_kit_id"] = int(brand_kit_id)
1459
1769
  if render_only:
1460
1770
  body["render_only"] = True
1461
1771
  for key, value in (