@cliptude/cli 0.1.30 → 0.1.33

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.
@@ -1,4 +1,4 @@
1
- """MCP Apps (interactive widgets) for hosts that render them: Claude Desktop, claude.ai.
1
+ """MCP Apps (interactive widgets) for hosts that render them: Claude Desktop, claude.ai, ChatGPT.
2
2
 
3
3
  Spec: https://modelcontextprotocol.io/specification/draft/extensions/apps (SEP-1865, `io.modelcontextprotocol/ui`).
4
4
 
@@ -8,23 +8,30 @@ sandboxed iframe next to a tool's result:
8
8
  - list_avatars -> ui://cliptude/avatars.html avatar thumbnails, pick one
9
9
  - list_voices -> ui://cliptude/voices.html play voice previews, pick one
10
10
  - list_vector_characters -> ui://cliptude/characters.html Vector Explainer cast and uploads, pick one
11
- - get_render, get_product_video_status, show_video
12
- -> ui://cliptude/player.html watch the MP4, or "not rendered yet"
11
+ - get_render, show_video -> ui://cliptude/player.html watch the MP4, or "not rendered yet"
13
12
  - show_choices -> ui://cliptude/choices.html music (play), backgrounds, style packs, themes, captions
14
13
  - show_publish_kit -> ui://cliptude/publish-kit.html thumbnails, title ideas, description, chapters, tags
14
+ - list_templates -> ui://cliptude/templates.html template gallery, "Use this template"
15
+ - create_template, get_template
16
+ -> ui://cliptude/template.html one template's card: voice, presenter, music, look, switches
17
+ - create_job, create_plan_job, create_script, create_voiceover, continue_job, render_product_video,
18
+ draft_product_script, run_agent, render_project, create_avatar
19
+ -> ui://cliptude/review.html the 428 review to confirm (or the result card)
20
+ - get_job, get_product_video_status, get_narration
21
+ -> ui://cliptude/job.html progress card, the script to approve, or the publish kit
15
22
 
16
23
  The existing tools keep their names, parameters and JSON (the text content stays the same for clients without
17
- Apps); only `_meta.ui.resourceUri` is added to them (`bind_existing_tools`). show_choices, show_video and
18
- show_publish_kit are new, thin tools: binding a widget to get_template_options, get_job or the editor-project
19
- tools would draw a widget on every one of their (frequent, polling) calls.
24
+ Apps); `bind_existing_tools` adds `_meta.ui.resourceUri` (plus ChatGPT's `openai/outputTemplate` alias) and tags a
25
+ 428 review with the tool that returned it (`tool`), so the review widget knows what to call again.
20
26
 
21
27
  A widget picks by posting a `ui/message` into the chat ("Use the voice ... (voice_id ...)"), so the model gets the
22
- id without the user typing it. The avatar and voice pickers can also make new ones in the chat (create_avatar,
23
- design_voice_previews / save_designed_voice, clone_voice in creation.py), calling those tools with `tools/call`.
28
+ id without the user typing it. Calls a widget makes itself (`tools/call`) happen only on the user's click: the
29
+ review widget's Confirm resends the reviewed call with its review_token, never on its own.
24
30
  """
25
31
 
26
32
  from __future__ import annotations
27
33
 
34
+ import functools
28
35
  from collections.abc import Callable
29
36
  from importlib import resources
30
37
  from typing import Annotated, Any
@@ -44,6 +51,10 @@ CHARACTERS_URI = "ui://cliptude/characters.html"
44
51
  PLAYER_URI = "ui://cliptude/player.html"
45
52
  CHOICES_URI = "ui://cliptude/choices.html"
46
53
  PUBLISH_KIT_URI = "ui://cliptude/publish-kit.html"
54
+ TEMPLATES_URI = "ui://cliptude/templates.html"
55
+ TEMPLATE_URI = "ui://cliptude/template.html"
56
+ REVIEW_URI = "ui://cliptude/review.html"
57
+ JOB_URI = "ui://cliptude/job.html"
47
58
 
48
59
  # uri -> (file, name, description)
49
60
  WIDGETS: dict[str, tuple[str, str, str]] = {
@@ -53,15 +64,58 @@ WIDGETS: dict[str, tuple[str, str, str]] = {
53
64
  PLAYER_URI: ("player.html", "Video player", "Plays a finished Cliptude MP4, or shows that it is not rendered yet."),
54
65
  CHOICES_URI: ("choices.html", "Setting picker", "Previews of music, backgrounds and styles to pick a template setting."),
55
66
  PUBLISH_KIT_URI: ("publish-kit.html", "Publish kit", "Thumbnails, title ideas, description, chapters and tags."),
67
+ TEMPLATES_URI: ("templates.html", "Templates", "The user's saved templates, to pick one for a video."),
68
+ TEMPLATE_URI: ("template.html", "Template", "One template: voice, presenter, music, background, style and switches."),
69
+ REVIEW_URI: ("review.html", "Review and confirm", "What a job or spend does and costs, for the user to confirm."),
70
+ JOB_URI: ("job.html", "Job", "A job's progress, its script to approve, or its publish kit when ready."),
56
71
  }
57
72
 
73
+ # Tools whose first call answers with a 428 review (detail.review + review_token) before they spend credits.
74
+ REVIEW_TOOLS: tuple[str, ...] = (
75
+ "create_job", "create_plan_job", "create_script", "create_voiceover", "continue_job", "render_product_video",
76
+ "draft_product_script", "run_agent", "render_project", "create_avatar",
77
+ )
78
+ # Of those, the ones that take acknowledge ids (the job review's acknowledgements_required).
79
+ ACKNOWLEDGE_TOOLS: frozenset[str] = frozenset({
80
+ "create_job", "create_plan_job", "create_script", "create_voiceover", "draft_product_script",
81
+ })
82
+
58
83
  # Existing tools that get a widget, by name.
59
84
  BOUND_TOOLS: dict[str, str] = {
60
85
  "list_avatars": AVATARS_URI,
61
86
  "list_voices": VOICES_URI,
62
87
  "list_vector_characters": CHARACTERS_URI,
63
88
  "get_render": PLAYER_URI,
64
- "get_product_video_status": PLAYER_URI,
89
+ "list_templates": TEMPLATES_URI,
90
+ "create_template": TEMPLATE_URI,
91
+ "get_template": TEMPLATE_URI,
92
+ "get_job": JOB_URI,
93
+ "get_product_video_status": JOB_URI,
94
+ "get_narration": JOB_URI,
95
+ **{name: REVIEW_URI for name in REVIEW_TOOLS},
96
+ }
97
+
98
+ # Tools a widget calls itself (tools/call). ChatGPT wants openai/widgetAccessible on them.
99
+ WIDGET_CALLED_TOOLS: frozenset[str] = frozenset({
100
+ *REVIEW_TOOLS, "list_avatars", "design_voice_previews", "save_designed_voice", "clone_voice", "show_publish_kit",
101
+ })
102
+
103
+ # ChatGPT's short status lines while a widget tool runs and after (openai/toolInvocation/*, at most 64 chars).
104
+ INVOCATION_TEXT: dict[str, tuple[str, str]] = {
105
+ "list_avatars": ("Loading avatars…", "Avatars ready"),
106
+ "list_voices": ("Loading voices…", "Voices ready"),
107
+ "list_vector_characters": ("Loading characters…", "Characters ready"),
108
+ "get_render": ("Checking the export…", "Export checked"),
109
+ "show_video": ("Loading the video…", "Video ready"),
110
+ "show_choices": ("Loading choices…", "Choices ready"),
111
+ "show_publish_kit": ("Opening the publish kit…", "Publish kit ready"),
112
+ "list_templates": ("Loading templates…", "Templates ready"),
113
+ "create_template": ("Saving the template…", "Template saved"),
114
+ "get_template": ("Loading the template…", "Template ready"),
115
+ "get_job": ("Checking the job…", "Job checked"),
116
+ "get_product_video_status": ("Checking the product video…", "Product video checked"),
117
+ "get_narration": ("Loading the narration…", "Narration ready"),
118
+ **{name: ("Preparing the review…", "Review ready") for name in REVIEW_TOOLS},
65
119
  }
66
120
 
67
121
  # Where the widgets' pictures, audio and video come from (CSP img-src/media-src via resourceDomains).
@@ -124,17 +178,48 @@ def widget_html(file_name: str) -> str:
124
178
  html = (pkg / file_name).read_text(encoding="utf-8")
125
179
  bridge = (pkg / "bridge.js").read_text(encoding="utf-8")
126
180
  css = (pkg / "base.css").read_text(encoding="utf-8")
127
- return html.replace("/*@BASE_CSS@*/", css).replace("/*@BRIDGE_JS@*/", bridge)
181
+ views = (pkg / "views.js").read_text(encoding="utf-8")
182
+ html = html.replace("/*@BASE_CSS@*/", css).replace("/*@BRIDGE_JS@*/", bridge)
183
+ return html.replace("/*@VIEWS_JS@*/", views)
128
184
 
129
185
 
130
186
  def media_domains(*, local: bool) -> list[str]:
131
187
  return list(MEDIA_DOMAINS) + (list(LOCAL_MEDIA_DOMAINS) if local else [])
132
188
 
133
189
 
134
- def _ui_meta(uri: str) -> dict[str, Any]:
190
+ def _openai_meta(name: str, uri: str) -> dict[str, Any]:
191
+ """ChatGPT's aliases (Apps SDK reference): it reads `_meta.ui.resourceUri` too, and documents these."""
192
+ meta: dict[str, Any] = {"openai/outputTemplate": uri}
193
+ invoking, invoked = INVOCATION_TEXT.get(name, ("", ""))
194
+ if invoking:
195
+ meta["openai/toolInvocation/invoking"] = invoking[:64]
196
+ meta["openai/toolInvocation/invoked"] = invoked[:64]
197
+ if name in WIDGET_CALLED_TOOLS:
198
+ meta["openai/widgetAccessible"] = True
199
+ return meta
200
+
201
+
202
+ def _ui_meta(uri: str, name: str = "") -> dict[str, Any]:
135
203
  # `ui.resourceUri` is the spec's key; the flat `ui/resourceUri` is its deprecated form, kept for hosts that
136
204
  # shipped before the rename.
137
- return {"ui": {"resourceUri": uri}, "ui/resourceUri": uri}
205
+ return {"ui": {"resourceUri": uri}, "ui/resourceUri": uri, **_openai_meta(name, uri)}
206
+
207
+
208
+ def _resource_meta(uri: str, description: str, *, local: bool) -> dict[str, Any]:
209
+ """`_meta` of a widget resource: the spec's `ui` block plus ChatGPT's openai/widget* aliases."""
210
+ domains = media_domains(local=local)
211
+ ui: dict[str, Any] = {"csp": ResourceCsp(resource_domains=domains).model_dump(by_alias=True, exclude_none=True)}
212
+ permissions = _PERMISSIONS.get(uri)
213
+ if permissions is not None:
214
+ ui["permissions"] = permissions.model_dump(by_alias=True, exclude_none=True)
215
+ ui["prefersBorder"] = True
216
+ return {
217
+ "ui": ui,
218
+ # The widgets fetch nothing themselves (no connect_domains); pictures, audio and video come from these.
219
+ "openai/widgetCSP": {"connect_domains": [], "resource_domains": domains},
220
+ "openai/widgetDescription": description,
221
+ "openai/widgetPrefersBorder": True,
222
+ }
138
223
 
139
224
 
140
225
  def build_apps(
@@ -148,23 +233,25 @@ def build_apps(
148
233
  return None
149
234
  from mcp.types import ToolAnnotations
150
235
 
236
+ from mcp.server.mcpserver.resources import TextResource
237
+
151
238
  apps = Apps()
152
- csp = ResourceCsp(resource_domains=media_domains(local=local))
153
239
  for uri, (file_name, name, description) in WIDGETS.items():
154
- apps.add_html_resource(
155
- uri,
156
- widget_html(file_name),
157
- name=name,
158
- title=name,
159
- description=description,
160
- csp=csp,
161
- permissions=_PERMISSIONS.get(uri),
162
- prefers_border=True,
240
+ apps.add_resource(
241
+ TextResource(
242
+ uri=uri,
243
+ name=name,
244
+ title=name,
245
+ description=description,
246
+ mime_type=APP_MIME_TYPE,
247
+ meta=_resource_meta(uri, description, local=local),
248
+ text=widget_html(file_name),
249
+ )
163
250
  )
164
251
 
165
252
  @apps.tool(
166
253
  resource_uri=CHOICES_URI,
167
- meta={"ui/resourceUri": CHOICES_URI},
254
+ meta={"ui/resourceUri": CHOICES_URI, **_openai_meta("show_choices", CHOICES_URI)},
168
255
  name="show_choices",
169
256
  title="Show setting choices",
170
257
  annotations=ToolAnnotations(title="Show setting choices", read_only_hint=True, open_world_hint=False),
@@ -188,7 +275,7 @@ def build_apps(
188
275
 
189
276
  @apps.tool(
190
277
  resource_uri=PLAYER_URI,
191
- meta={"ui/resourceUri": PLAYER_URI},
278
+ meta={"ui/resourceUri": PLAYER_URI, **_openai_meta("show_video", PLAYER_URI)},
192
279
  name="show_video",
193
280
  title="Show video",
194
281
  annotations=ToolAnnotations(title="Show video", read_only_hint=True, open_world_hint=False),
@@ -205,7 +292,7 @@ def build_apps(
205
292
 
206
293
  @apps.tool(
207
294
  resource_uri=PUBLISH_KIT_URI,
208
- meta={"ui/resourceUri": PUBLISH_KIT_URI},
295
+ meta={"ui/resourceUri": PUBLISH_KIT_URI, **_openai_meta("show_publish_kit", PUBLISH_KIT_URI)},
209
296
  name="show_publish_kit",
210
297
  title="Show publish kit",
211
298
  annotations=ToolAnnotations(title="Show publish kit", read_only_hint=False, destructive_hint=False, open_world_hint=False),
@@ -213,20 +300,47 @@ def build_apps(
213
300
  def show_publish_kit(
214
301
  job_id: Annotated[str, Field(min_length=8, description="Completed video job id")],
215
302
  ) -> dict[str, Any]:
216
- """The generated thumbnails, title ideas, YouTube description, chapters and tags of a finished video, shown as a publish kit with copy buttons (hosts that show apps). Opens the video's editor project like open_editor_project. Returns {job_id, project_id, title, thumbnails, publish_metadata}."""
303
+ """The finished video in a player, then its generated thumbnails, title ideas, YouTube description, chapters and tags with copy buttons (hosts that show apps). Call it as soon as a video is ready (rendered, or built and waiting for review): it is the one place the user watches the video and gets everything to publish it. Opens the video's editor project like open_editor_project. Returns {job_id, project_id, title, video, thumbnails, publish_metadata}; video.url is the latest export, else the job's own MP4, empty until one exists."""
217
304
  try:
218
305
  data = client().open_editor_project(job_id)
219
306
  except Exception as exc:
220
307
  return err(exc)
221
- return publish_kit_payload(data, job_id)
308
+ payload = publish_kit_payload(data, job_id)
309
+ if not payload.get("error") and not (payload.get("video") or {}).get("url"):
310
+ try:
311
+ job = client().get_job(job_id)
312
+ except Exception:
313
+ job = None
314
+ output = job.get("output") if isinstance(job, dict) and isinstance(job.get("output"), dict) else {}
315
+ if output.get("url"):
316
+ payload["video"] = {"url": output["url"], "source": "original", "note": ""}
317
+ return payload
222
318
 
223
319
  return apps
224
320
 
225
321
 
322
+ def _tag_reviews(tool: Any, name: str) -> None:
323
+ """A 428 review result also names the tool that returned it, so the review widget can call it again."""
324
+ original = tool.fn
325
+ if getattr(original, "_cliptude_tagged", False) or getattr(tool, "is_async", False):
326
+ return
327
+
328
+ @functools.wraps(original)
329
+ def tagged(*args: Any, **kwargs: Any) -> Any:
330
+ result = original(*args, **kwargs)
331
+ if isinstance(result, dict) and result.get("status") == 428 and "tool" not in result:
332
+ return {**result, "tool": name}
333
+ return result
334
+
335
+ tagged._cliptude_tagged = True # type: ignore[attr-defined]
336
+ tool.fn = tagged
337
+
338
+
226
339
  def bind_existing_tools(mcp: Any) -> list[str]:
227
340
  """Stamp `_meta.ui.resourceUri` on the existing tools that have a widget; returns the names bound.
228
341
 
229
- The tools are registered by server.py as before, so their names, parameters and results do not change.
342
+ The tools are registered by server.py (and creation.py) as before, so their names and parameters do not
343
+ change; a 428 review also says which tool returned it (`tool`).
230
344
  """
231
345
  manager = getattr(mcp, "_tool_manager", None)
232
346
  bound = []
@@ -234,8 +348,14 @@ def bind_existing_tools(mcp: Any) -> list[str]:
234
348
  tool = manager.get_tool(name) if manager is not None else None
235
349
  if tool is None:
236
350
  continue
237
- tool.meta = {**(tool.meta or {}), **_ui_meta(uri)}
351
+ tool.meta = {**(tool.meta or {}), **_ui_meta(uri, name)}
352
+ if name in REVIEW_TOOLS:
353
+ _tag_reviews(tool, name)
238
354
  bound.append(name)
355
+ for name in sorted(WIDGET_CALLED_TOOLS - set(BOUND_TOOLS)):
356
+ tool = manager.get_tool(name) if manager is not None else None
357
+ if tool is not None:
358
+ tool.meta = {**(tool.meta or {}), "openai/widgetAccessible": True}
239
359
  return bound
240
360
 
241
361
 
@@ -289,6 +409,18 @@ def video_payload(job: Any, job_id: str) -> dict[str, Any]:
289
409
  }
290
410
 
291
411
 
412
+ def _project_video(project: dict[str, Any]) -> dict[str, Any]:
413
+ """The newest finished export of the editor project, for the publish kit's player."""
414
+ render = project.get("latest_render") if isinstance(project.get("latest_render"), dict) else {}
415
+ url = ""
416
+ if str(render.get("status") or "completed").lower() == "completed":
417
+ url = str(render.get("output_url") or project.get("latest_render_url") or "")
418
+ if url:
419
+ return {"url": url, "source": "export", "note": ""}
420
+ note = "Not rendered yet: render_project makes the MP4." if render.get("status") not in (None, "", "completed") else ""
421
+ return {"url": "", "source": "", "note": note}
422
+
423
+
292
424
  def publish_kit_payload(data: Any, job_id: str) -> dict[str, Any]:
293
425
  if not isinstance(data, dict):
294
426
  return {"error": "Cliptude returned no editor project."}
@@ -300,6 +432,7 @@ def publish_kit_payload(data: Any, job_id: str) -> dict[str, Any]:
300
432
  "job_id": job_id,
301
433
  "project_id": project.get("id"),
302
434
  "title": project.get("title") or "",
435
+ "video": _project_video(project),
303
436
  "thumbnails": project.get("thumbnails") or {"status": "", "items": []},
304
437
  "publish_metadata": {
305
438
  "title_variants": meta.get("title_variants") or [],
@@ -1,4 +1,4 @@
1
- """Tiny CLI wrapping /api/v1: auth | templates | template-create | template-options | voices | avatars | estimate | generate | editor | agent | render | script | voiceover | continue | status | jobs | account | cancel."""
1
+ """Tiny CLI wrapping /api/v1: auth | pick | templates | template-create | template-options | voices | avatars | estimate | generate | editor | agent | render | script | voiceover | continue | status | jobs | account | cancel."""
2
2
 
3
3
  from __future__ import annotations
4
4
 
@@ -175,6 +175,43 @@ def _wait(fetch, status_of, *, interval: float = 10.0, timeout: float = 3600.0):
175
175
  time.sleep(interval)
176
176
 
177
177
 
178
+ def _run_pick(client: CliptudeClient, args) -> dict:
179
+ """Open a browser picker (made here with --kind, or one an agent got as browser_picker_url) and wait for it.
180
+
181
+ The page is the same widget Claude Desktop shows (avatars, voices, music, a review to confirm, ...), on
182
+ cliptude.com for the signed-in owner, for 15 minutes. Returns the pick once the user is done.
183
+ """
184
+ import time
185
+ import webbrowser
186
+
187
+ pick_id, url = (args.pick_id or "").strip(), (args.url or "").strip()
188
+ if args.kind:
189
+ try:
190
+ source = json.loads(args.source or "{}")
191
+ except ValueError as exc:
192
+ raise CliptudeApiError("--source must be a JSON object.") from exc
193
+ if not isinstance(source, dict):
194
+ raise CliptudeApiError("--source must be a JSON object.")
195
+ created = client.create_pick(args.kind, source)
196
+ pick_id, url = str(created.get("pick_id") or ""), str(created.get("url") or "")
197
+ if not pick_id:
198
+ raise CliptudeApiError("Give a pick_id (with --url to open it), or --kind to make a new picker.")
199
+ if url:
200
+ if not url.startswith(("https://", "http://127.0.0.1", "http://localhost")):
201
+ raise CliptudeApiError("--url must be the https link Cliptude gave (browser_picker_url).")
202
+ print(f"Pick in your browser: {url}", file=sys.stderr)
203
+ if not args.no_open:
204
+ webbrowser.open(url)
205
+ deadline = time.monotonic() + max(5.0, float(args.timeout))
206
+ while True:
207
+ payload = client.get_pick(pick_id)
208
+ status = str(payload.get("status") or "")
209
+ if status != "open" or time.monotonic() > deadline:
210
+ return payload
211
+ print("Waiting for your pick in the browser...", file=sys.stderr)
212
+ time.sleep(max(1.0, float(args.interval)))
213
+
214
+
178
215
  def _run_auth(auth_cmd: str) -> None:
179
216
  from cliptude_mcp.auth_login import AuthLoginError, login
180
217
  from cliptude_mcp.credentials import clear_credentials, stored_access_token
@@ -261,6 +298,25 @@ def main(argv: list[str] | None = None) -> None:
261
298
  use.add_argument("target", nargs="?", choices=["desktop", "cloud", "auto"],
262
299
  help="auto = the desktop app while it is running, else cliptude.com")
263
300
 
301
+ pk = sub.add_parser(
302
+ "pick",
303
+ help="Open a browser picker (avatars, voices, music, a review to confirm, ...) and wait for the pick",
304
+ description=(
305
+ "Clients without MCP Apps widgets get browser_picker_url and pick_id from the MCP tools. This opens the "
306
+ "link in your browser and waits until you pick (or confirm) there, then prints the result. With --kind "
307
+ "it makes a new picker first."
308
+ ),
309
+ )
310
+ pk.add_argument("pick_id", nargs="?", default="", help="pick_id from the tool result")
311
+ pk.add_argument("--url", default="", help="browser_picker_url from the tool result")
312
+ pk.add_argument("--kind", default="", choices=["", "avatars", "voices", "characters", "choices", "templates",
313
+ "template", "job", "script", "publish_kit", "video"],
314
+ help="Make a new picker of this kind instead")
315
+ pk.add_argument("--source", default="{}", help='Where Cliptude reads it from, JSON, e.g. {"provider": "elevenlabs"}')
316
+ pk.add_argument("--no-open", action="store_true", help="Print the link instead of opening a browser")
317
+ pk.add_argument("--timeout", type=float, default=900.0, help="Seconds to wait (the link lasts 15 minutes)")
318
+ pk.add_argument("--interval", type=float, default=3.0, help="Seconds between checks")
319
+
264
320
  t = sub.add_parser("templates", help="List saved templates")
265
321
  t.add_argument("--limit", type=int, default=20)
266
322
  t.add_argument("--offset", type=int, default=0)
@@ -662,7 +718,12 @@ def main(argv: list[str] | None = None) -> None:
662
718
  return
663
719
  client = CliptudeClient(client_kind="cli")
664
720
  try:
665
- if args.cmd == "templates":
721
+ if args.cmd == "pick":
722
+ payload = _run_pick(client, args)
723
+ _print(payload)
724
+ if payload.get("status") != "done":
725
+ raise SystemExit(1)
726
+ elif args.cmd == "templates":
666
727
  _print(client.list_templates(limit=args.limit, offset=args.offset))
667
728
  elif args.cmd == "template-create":
668
729
  settings = {}
@@ -1163,6 +1163,15 @@ class CliptudeClient:
1163
1163
  def get_account(self) -> Any:
1164
1164
  return self.request("GET", "/api/v1/account")
1165
1165
 
1166
+ # Browser pickers (clients without MCP Apps widgets) ---------------------------------------------
1167
+
1168
+ def create_pick(self, kind: str, payload_source: dict[str, Any]) -> Any:
1169
+ """A cliptude.com/pick link showing a widget in the browser; Cliptude builds what it shows."""
1170
+ return self.request("POST", "/api/v1/picks", json_body={"kind": kind, "payload_source": payload_source})
1171
+
1172
+ def get_pick(self, pick_id: str) -> Any:
1173
+ return self.request("GET", f"/api/v1/picks/{_uuid_seg(pick_id, 'pick_id')}")
1174
+
1166
1175
  def estimate_credits(
1167
1176
  self,
1168
1177
  *,
@@ -1210,12 +1219,16 @@ class CliptudeClient:
1210
1219
  *,
1211
1220
  image_path: str | Path | None = None,
1212
1221
  image_url: str | None = None,
1222
+ image_file: tuple[str, bytes, str] | None = None,
1213
1223
  name: str = "",
1214
1224
  _retried: bool = False,
1215
1225
  ) -> Any:
1216
- """Add a Vector Explainer character from a local image or a public image URL; returns its id."""
1217
- if bool(image_path) == bool((image_url or "").strip()):
1218
- raise CliptudeApiError("Give image_path or image_url (one of them).")
1226
+ """Add a Vector Explainer character from a local image, a public image URL, or (file name, bytes, mime)
1227
+ sent by a widget; returns its id."""
1228
+ if sum(bool(x) for x in (image_path, (image_url or "").strip(), image_file)) != 1:
1229
+ raise CliptudeApiError("Give image_path, image_url or the image itself (one of them).")
1230
+ if image_file:
1231
+ return self._post_vector_character_file(image_file, name, _retried)
1219
1232
  if image_url:
1220
1233
  return self.request(
1221
1234
  "POST", "/api/v1/vector-characters", json_body={"image_url": image_url.strip(), "name": name}
@@ -1245,6 +1258,28 @@ class CliptudeClient:
1245
1258
  self._raise_http(resp, payload=payload)
1246
1259
  return payload
1247
1260
 
1261
+ def _post_vector_character_file(self, image_file: tuple[str, bytes, str], name: str, _retried: bool) -> Any:
1262
+ file_name, raw, mime = image_file
1263
+ try:
1264
+ resp = httpx.post(
1265
+ f"{self.base_url}/api/v1/vector-characters",
1266
+ headers=self._headers(json_content=False),
1267
+ data={"name": name},
1268
+ files={"image": (file_name, raw, mime)},
1269
+ timeout=max(self.timeout, 120.0),
1270
+ )
1271
+ except httpx.HTTPError as exc:
1272
+ raise CliptudeApiError(str(exc)) from exc
1273
+ if resp.status_code == 401 and not _retried and self._maybe_refresh():
1274
+ return self._post_vector_character_file(image_file, name, True)
1275
+ try:
1276
+ payload = resp.json()
1277
+ except ValueError:
1278
+ payload = {"error": resp.text}
1279
+ if resp.status_code >= 400:
1280
+ self._raise_http(resp, payload=payload)
1281
+ return payload
1282
+
1248
1283
  def delete_vector_character(self, character_id: str) -> Any:
1249
1284
  """Delete one of your uploaded characters (refused while a template uses it)."""
1250
1285
  return self.request("DELETE", f"/api/v1/vector-characters/{_uuid_seg(character_id, 'character_id')}")