@cliptude/cli 0.1.7 → 0.1.9
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.
- package/README.md +8 -3
- package/cliptude_mcp/__pycache__/__init__.cpython-313.pyc +0 -0
- package/cliptude_mcp/__pycache__/__init__.cpython-314.pyc +0 -0
- package/cliptude_mcp/__pycache__/__main__.cpython-313.pyc +0 -0
- package/cliptude_mcp/__pycache__/auth.cpython-313.pyc +0 -0
- package/cliptude_mcp/__pycache__/auth.cpython-314.pyc +0 -0
- package/cliptude_mcp/__pycache__/auth_login.cpython-313.pyc +0 -0
- package/cliptude_mcp/__pycache__/auth_login.cpython-314.pyc +0 -0
- package/cliptude_mcp/__pycache__/cli.cpython-313.pyc +0 -0
- package/cliptude_mcp/__pycache__/cli.cpython-314.pyc +0 -0
- package/cliptude_mcp/__pycache__/client.cpython-313.pyc +0 -0
- package/cliptude_mcp/__pycache__/client.cpython-314.pyc +0 -0
- package/cliptude_mcp/__pycache__/credentials.cpython-313.pyc +0 -0
- package/cliptude_mcp/__pycache__/credentials.cpython-314.pyc +0 -0
- package/cliptude_mcp/__pycache__/server.cpython-313.pyc +0 -0
- package/cliptude_mcp/__pycache__/server.cpython-314.pyc +0 -0
- package/cliptude_mcp/cli.py +149 -8
- package/cliptude_mcp/client.py +203 -7
- package/cliptude_mcp/server.py +247 -10
- package/package.json +1 -1
- package/pyproject.toml +1 -1
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@ Generate videos from a saved template. Same account and credits as cliptude.com.
|
|
|
6
6
|
|
|
7
7
|
1. Install the CLI: run `npm i -g @cliptude/cli`.
|
|
8
8
|
2. Authenticate: run `cliptude auth login` and complete the sign-in in the browser it opens.
|
|
9
|
-
3. Install the companion skills: run `npx skills add cliptude/cliptude
|
|
9
|
+
3. Install the companion skills: run `npx skills add cliptude/cliptude`.
|
|
10
10
|
|
|
11
11
|
From this repo without npm:
|
|
12
12
|
|
|
@@ -24,6 +24,9 @@ cliptude voices --provider elevenlabs
|
|
|
24
24
|
cliptude template-create --name "TSMC doc" --format faceless_documentary --set voice_id=<id> --set voice_name=George --set generation_model=pro --set faceless_documentary_style=investigative
|
|
25
25
|
cliptude template-create --name "TSMC doc" --format faceless_documentary --settings-file settings.json
|
|
26
26
|
cliptude generate --template "Finance vector weekly" --title "Why index funds win" --prompt "why most retail traders underperform the S&P over 10 years, keep it for beginners" --duration 3-4
|
|
27
|
+
cliptude estimate --template "Finance vector weekly" --script-file script.txt
|
|
28
|
+
cliptude avatars --section mine
|
|
29
|
+
cliptude generate --template "My avatar weekly" --title "Episode one" --script-file script.txt --avatar 42
|
|
27
30
|
cliptude generate --template "Finance vector weekly" --title "Why index funds win" --script-file script.txt
|
|
28
31
|
cliptude generate --template "Finance vector weekly" --title "Why index funds win" --voiceover narration.mp3
|
|
29
32
|
cliptude generate --template "My talking head" --title "Weekly recap" --talking-head clip.mp4
|
|
@@ -38,13 +41,15 @@ cliptude continue <job-id>
|
|
|
38
41
|
cliptude status <job-id>
|
|
39
42
|
```
|
|
40
43
|
|
|
41
|
-
No template yet? `template-create` makes one without the create wizard: pick a `voice_id` from `voices`, and see `template-options` for every other field, its choices and its default (unset fields take the wizard default). Values are validated like the wizard; uploads (custom music, avatars, characters) still need the wizard. MCP tools: `get_template_options`, `list_voices`, `create_template`.
|
|
44
|
+
No template yet? `template-create` makes one without the create wizard: pick a `voice_id` from `voices`, and see `template-options` for every other field, its choices and its default (unset fields take the wizard default). Values are validated like the wizard; uploads (custom music, avatars, characters) still need the wizard. MCP tools: `get_template_options`, `list_voices`, `create_template`. For Avatar Video, `avatars` (MCP `list_avatars`) lists your avatars; set one with `--set avatar_profile_id=<id>` on `template-create`, or override it per video with `--avatar <id>` (and `--avatar-engine iii|iv|v`) on `generate`, `plan-job` and `estimate`. The avatar's gender must match the voice. For Vector Explainer, `vector-characters` lists the built-in cast and your uploads, `vector-character-upload --name "Dr. Maya" --file maya.png` (or `--url`) adds your own, and `--set vector_character_id=<id>` on `template-create` (or `--vector-character <id>` on `generate` / `plan-job`) uses it. Motion: `--set vector_reveal_mode=none|video` on the template, or `--vector-motion none|video` on `generate`, `plan-job` and `estimate` (`none` = stills with camera moves, `video` = AI clips). Thumbnails: `--thumbnail-reference <YouTube link or image URL>` or `--thumbnail-prompt "<brief>"` on `template-create` sets the template's look; the same flags on `generate` and `plan-job` set one video's. With neither, each video picks a style reference for its own title.
|
|
45
|
+
|
|
46
|
+
To check the price first, `estimate` (MCP `estimate_credits`, REST `POST /api/v1/jobs/estimate`) takes the same template and prompt/script as `generate` (an upload as `--voiceover-seconds` / `--talking-head-seconds`) and returns the credits the job would need and whether the account has them. It creates and charges nothing.
|
|
42
47
|
|
|
43
48
|
To revise a finished video, `editor` opens its timeline (item ids, times, text), `agent` asks Cliptude Agent for an edit (it charges agent credits; reference item ids with `--items`), and `render` exports a new MP4. MCP tools: `open_editor_project`, `get_editor_project`, `run_agent`, `get_agent_run`, `cancel_agent_run`, `render_project`, `get_render`.
|
|
44
49
|
|
|
45
50
|
### Agent-planned videos
|
|
46
51
|
|
|
47
|
-
On Faceless Documentary, Faceless Top 10
|
|
52
|
+
On Faceless Documentary, Faceless Top 10, Avatar Video and Vector Explainer templates an agent can plan every visual and leave Cliptude
|
|
48
53
|
only the voicing, sourcing and rendering:
|
|
49
54
|
|
|
50
55
|
1. `cliptude plan-job` (stops at `plan_ready`), `cliptude narration <job>`.
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/cliptude_mcp/cli.py
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
"""Tiny CLI wrapping /api/v1: auth | templates | template-create | template-options | voices | generate | editor | agent | render | script | voiceover | continue | status | jobs | account | cancel."""
|
|
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."""
|
|
2
2
|
|
|
3
3
|
from __future__ import annotations
|
|
4
4
|
|
|
@@ -35,6 +35,34 @@ def _resolve_template_id(client: CliptudeClient, value: str) -> str:
|
|
|
35
35
|
raise CliptudeApiError(f"Template not found: {value}")
|
|
36
36
|
|
|
37
37
|
|
|
38
|
+
def _add_thumbnail_args(parser: argparse.ArgumentParser, *, scope: str) -> None:
|
|
39
|
+
parser.add_argument(
|
|
40
|
+
"--thumbnail-prompt",
|
|
41
|
+
default="",
|
|
42
|
+
help=f"Thumbnail brief for {scope} (people, style, text). Not with --thumbnail-reference.",
|
|
43
|
+
)
|
|
44
|
+
parser.add_argument(
|
|
45
|
+
"--thumbnail-reference",
|
|
46
|
+
default="",
|
|
47
|
+
help=(
|
|
48
|
+
f"YouTube video link or https image whose thumbnail style {scope} copies. Without a brief or "
|
|
49
|
+
"reference, each video picks a reference for its own title."
|
|
50
|
+
),
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def _thumbnail_from_args(args) -> dict | None:
|
|
55
|
+
thumbnail = {
|
|
56
|
+
key: value.strip()
|
|
57
|
+
for key, value in (
|
|
58
|
+
("custom_prompt", getattr(args, "thumbnail_prompt", "")),
|
|
59
|
+
("reference_url", getattr(args, "thumbnail_reference", "")),
|
|
60
|
+
)
|
|
61
|
+
if value and value.strip()
|
|
62
|
+
}
|
|
63
|
+
return thumbnail or None
|
|
64
|
+
|
|
65
|
+
|
|
38
66
|
def _parse_set_args(pairs: list[str]) -> dict:
|
|
39
67
|
out = {}
|
|
40
68
|
for pair in pairs:
|
|
@@ -85,7 +113,7 @@ def _run_auth(auth_cmd: str) -> None:
|
|
|
85
113
|
print("Not authenticated. Run: cliptude auth login", file=sys.stderr)
|
|
86
114
|
raise SystemExit(1)
|
|
87
115
|
try:
|
|
88
|
-
account = CliptudeClient().get_account()
|
|
116
|
+
account = CliptudeClient(client_kind="cli").get_account()
|
|
89
117
|
except Exception as exc:
|
|
90
118
|
_die(exc)
|
|
91
119
|
email = account.get("email") if isinstance(account, dict) else None
|
|
@@ -139,6 +167,7 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
139
167
|
metavar="KEY=VALUE",
|
|
140
168
|
help="One setting; VALUE is parsed as JSON when possible (true, 0.4, [\"a\"]), else a string. Repeatable.",
|
|
141
169
|
)
|
|
170
|
+
_add_thumbnail_args(tc, scope="every video from this template")
|
|
142
171
|
|
|
143
172
|
to = sub.add_parser("template-options", help="Fields, choices and defaults for template-create")
|
|
144
173
|
to.add_argument("--format", required=True)
|
|
@@ -147,6 +176,48 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
147
176
|
vc.add_argument("--provider", default="elevenlabs", help="elevenlabs, minimax, cartesia, inworld, voicetory")
|
|
148
177
|
vc.add_argument("--language", default="")
|
|
149
178
|
|
|
179
|
+
av = sub.add_parser("avatars", help="List avatars for Avatar Video (id for --avatar / avatar_profile_id)")
|
|
180
|
+
av.add_argument("--section", default="", choices=["", "mine", "builtin", "public", "favorites"])
|
|
181
|
+
av.add_argument("--search", default="", help="Part of the avatar's name")
|
|
182
|
+
av.add_argument("--gender", default="", choices=["", "male", "female"])
|
|
183
|
+
av.add_argument("--limit", type=int, default=50)
|
|
184
|
+
|
|
185
|
+
vcl = sub.add_parser("vector-characters", help="List Vector Explainer characters (built-in and your uploads)")
|
|
186
|
+
vcu = sub.add_parser(
|
|
187
|
+
"vector-character-upload",
|
|
188
|
+
help="Add your own Vector Explainer character from a local image or a public URL; prints its id",
|
|
189
|
+
)
|
|
190
|
+
vcu.add_argument("--name", required=True, help="Short name for the character")
|
|
191
|
+
vcu.add_argument("--file", default="", help="Local PNG, JPG or WEBP")
|
|
192
|
+
vcu.add_argument("--url", default="", help="Public https link to the image")
|
|
193
|
+
vcd = sub.add_parser("vector-character-delete", help="Delete one of your uploaded Vector Explainer characters")
|
|
194
|
+
vcd.add_argument("character_id")
|
|
195
|
+
|
|
196
|
+
est = sub.add_parser(
|
|
197
|
+
"estimate",
|
|
198
|
+
help="Credits a job would need (creates nothing)",
|
|
199
|
+
formatter_class=argparse.RawDescriptionHelpFormatter,
|
|
200
|
+
epilog=(
|
|
201
|
+
"example:\n"
|
|
202
|
+
' cliptude estimate --template "Finance vector weekly" --script-file script.txt\n'
|
|
203
|
+
' cliptude estimate --template "Finance vector weekly" --voiceover-seconds 3600'
|
|
204
|
+
),
|
|
205
|
+
)
|
|
206
|
+
est.add_argument("--template", required=True, help="Template name or UUID")
|
|
207
|
+
est.add_argument("--prompt", default="")
|
|
208
|
+
est.add_argument("--script", default="")
|
|
209
|
+
est.add_argument("--script-file", default="")
|
|
210
|
+
est.add_argument("--duration", default="", help="Duration bucket, e.g. 6-8. Default: template (or from --script)")
|
|
211
|
+
est.add_argument("--voiceover-seconds", type=float, default=None, help="Length of the voiceover you would upload")
|
|
212
|
+
est.add_argument("--talking-head-seconds", type=float, default=None, help="Length of the talking-head video you would upload")
|
|
213
|
+
est.add_argument("--output", default="", choices=["", "video", "plan", "script", "voiceover"])
|
|
214
|
+
est.add_argument("--avatar-intro-only", action=argparse.BooleanOptionalAction, default=None)
|
|
215
|
+
est.add_argument("--avatar-ai-footage", action=argparse.BooleanOptionalAction, default=None)
|
|
216
|
+
est.add_argument("--avatar", type=int, default=None, help="Avatar Video: avatar id from `cliptude avatars`. Default: the template's avatar")
|
|
217
|
+
est.add_argument("--avatar-engine", default="", choices=["", "iii", "iv", "v"], help="Avatar Video: HeyGen engine. Default: the template's")
|
|
218
|
+
est.add_argument("--vector-motion", default="", choices=["", "none", "video"], help="Vector Explainer: price stills (none) or AI clips (video)")
|
|
219
|
+
est.add_argument("--render-only", action="store_true", help="Plan job where you bring the voiceover, pictures, clips and graphics (with --output plan --voiceover-seconds)")
|
|
220
|
+
|
|
150
221
|
g = sub.add_parser(
|
|
151
222
|
"generate",
|
|
152
223
|
help="Start a job",
|
|
@@ -178,6 +249,7 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
178
249
|
default="",
|
|
179
250
|
help="Path to a narration audio file (MP3, M4A, WAV, …). Transcribed; skips TTS. Do not combine with --prompt or --script.",
|
|
180
251
|
)
|
|
252
|
+
g.add_argument("--voiceover-url", default="", help="Public https link to the narration audio; Cliptude downloads it.")
|
|
181
253
|
g.add_argument(
|
|
182
254
|
"--talking-head",
|
|
183
255
|
default="",
|
|
@@ -202,10 +274,12 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
202
274
|
action=argparse.BooleanOptionalAction,
|
|
203
275
|
default=None,
|
|
204
276
|
help=(
|
|
205
|
-
"Avatar Video: AI Image + AI Video instead of stock
|
|
277
|
+
"Avatar Video: AI Image + AI Video instead of stock and web footage. "
|
|
206
278
|
"Omit to use the template. Only valid for Avatar Video templates."
|
|
207
279
|
),
|
|
208
280
|
)
|
|
281
|
+
g.add_argument("--avatar", type=int, default=None, help="Avatar Video: avatar id from `cliptude avatars`. Default: the template's avatar")
|
|
282
|
+
g.add_argument("--avatar-engine", default="", choices=["", "iii", "iv", "v"], help="Avatar Video: HeyGen engine. Default: the template's")
|
|
209
283
|
g.add_argument(
|
|
210
284
|
"--disable-animations",
|
|
211
285
|
action=argparse.BooleanOptionalAction,
|
|
@@ -246,6 +320,9 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
246
320
|
metavar="SLUG",
|
|
247
321
|
help="Exclude a transition (e.g. flip-horizontal) from auto-selection. Repeatable. Omit to use the template.",
|
|
248
322
|
)
|
|
323
|
+
_add_thumbnail_args(g, scope="this video")
|
|
324
|
+
g.add_argument("--vector-motion", default="", choices=["", "none", "video"], help='Vector Explainer: "none" = stills with camera moves, "video" = AI clips. Default: the template\'s')
|
|
325
|
+
g.add_argument("--vector-character", default="", help='Vector Explainer: character id from `cliptude vector-characters`, or "none". Default: the template\'s')
|
|
249
326
|
|
|
250
327
|
sc = sub.add_parser(
|
|
251
328
|
"script",
|
|
@@ -314,13 +391,20 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
314
391
|
pj.add_argument("--script", default="")
|
|
315
392
|
pj.add_argument("--script-file", default="")
|
|
316
393
|
pj.add_argument("--voiceover", default="", help="Local audio to use as the narration (aligned, not re-voiced)")
|
|
394
|
+
pj.add_argument("--voiceover-url", default="", help="Public https link to the narration audio; Cliptude downloads it")
|
|
317
395
|
pj.add_argument("--duration", default="", help="Wizard duration bucket, e.g. 6-8")
|
|
396
|
+
pj.add_argument("--avatar", type=int, default=None, help="Avatar Video: avatar id from `cliptude avatars`. Default: the template's avatar")
|
|
397
|
+
pj.add_argument("--avatar-engine", default="", choices=["", "iii", "iv", "v"], help="Avatar Video: HeyGen engine. Default: the template's")
|
|
398
|
+
pj.add_argument("--render-only", action="store_true", help="You bring everything (needs --voiceover); Cliptude only builds and renders, at the render-only rate")
|
|
399
|
+
_add_thumbnail_args(pj, scope="this video")
|
|
400
|
+
pj.add_argument("--vector-motion", default="", choices=["", "none", "video"], help='Vector Explainer: "none" = stills with camera moves, "video" = AI clips. Default: the template\'s')
|
|
401
|
+
pj.add_argument("--vector-character", default="", help='Vector Explainer: character id from `cliptude vector-characters`, or "none". Default: the template\'s')
|
|
318
402
|
|
|
319
403
|
nr = sub.add_parser("narration", help="Numbered sentences and word timings of a plan_ready job")
|
|
320
404
|
nr.add_argument("job_id")
|
|
321
405
|
|
|
322
406
|
cat = sub.add_parser("catalog", help="Graphics an agent can place (kinds, types, overlay styles)")
|
|
323
|
-
cat.add_argument("--format", default="", help="faceless_documentary, faceless_top_10 or
|
|
407
|
+
cat.add_argument("--format", default="", help="faceless_documentary, faceless_top_10, avatar_video or vector_explainer")
|
|
324
408
|
cat.add_argument("--theme", default="")
|
|
325
409
|
cat.add_argument("--compact", action="store_true", help="One summary line per graphic")
|
|
326
410
|
cat.add_argument("--types", default="", help="Comma-separated types/styles for full entries")
|
|
@@ -337,6 +421,9 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
337
421
|
pv.add_argument("job_id")
|
|
338
422
|
pr = sub.add_parser("plan-report", help="What sourcing used for each media request of the locked plan")
|
|
339
423
|
pr.add_argument("job_id")
|
|
424
|
+
um = sub.add_parser("upload-media", help="Send a picture or clip you found to a plan job; prints its keep id for media.keep")
|
|
425
|
+
um.add_argument("job_id")
|
|
426
|
+
um.add_argument("path", help="Local JPG/PNG/WEBP/GIF (up to 15 MB) or MP4/MOV/WEBM/M4V (up to 300 MB)")
|
|
340
427
|
|
|
341
428
|
ed = sub.add_parser("editor", help="Open the timeline editor project for a completed job (prints the timeline)")
|
|
342
429
|
ed.add_argument("job_id")
|
|
@@ -392,7 +479,7 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
392
479
|
if args.cmd == "auth":
|
|
393
480
|
_run_auth(args.auth_cmd)
|
|
394
481
|
return
|
|
395
|
-
client = CliptudeClient()
|
|
482
|
+
client = CliptudeClient(client_kind="cli")
|
|
396
483
|
try:
|
|
397
484
|
if args.cmd == "templates":
|
|
398
485
|
_print(client.list_templates(limit=args.limit, offset=args.offset))
|
|
@@ -403,18 +490,56 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
403
490
|
if not isinstance(settings, dict):
|
|
404
491
|
raise CliptudeApiError("--settings-file must contain a JSON object.")
|
|
405
492
|
settings.update(_parse_set_args(args.set))
|
|
493
|
+
thumbnail = _thumbnail_from_args(args)
|
|
494
|
+
if thumbnail:
|
|
495
|
+
settings["thumbnail"] = thumbnail
|
|
406
496
|
_print(client.create_template(name=args.name, format=args.format, settings=settings))
|
|
407
497
|
elif args.cmd == "template-options":
|
|
408
498
|
_print(client.template_options(args.format))
|
|
409
499
|
elif args.cmd == "voices":
|
|
410
500
|
_print(client.list_voices(provider=args.provider, language=args.language or None))
|
|
501
|
+
elif args.cmd == "vector-characters":
|
|
502
|
+
_print(client.list_vector_characters())
|
|
503
|
+
elif args.cmd == "vector-character-upload":
|
|
504
|
+
if bool(args.file) == bool(args.url):
|
|
505
|
+
raise CliptudeApiError("Give --file or --url (one of them).")
|
|
506
|
+
_print(client.upload_vector_character(
|
|
507
|
+
image_path=args.file or None, image_url=args.url or None, name=args.name,
|
|
508
|
+
))
|
|
509
|
+
elif args.cmd == "vector-character-delete":
|
|
510
|
+
_print(client.delete_vector_character(args.character_id))
|
|
511
|
+
elif args.cmd == "avatars":
|
|
512
|
+
_print(client.list_avatars(
|
|
513
|
+
section=args.section or None, search=args.search or None,
|
|
514
|
+
gender=args.gender or None, limit=args.limit,
|
|
515
|
+
))
|
|
516
|
+
elif args.cmd == "estimate":
|
|
517
|
+
script = args.script
|
|
518
|
+
if args.script_file:
|
|
519
|
+
script = Path(args.script_file).read_text(encoding="utf-8")
|
|
520
|
+
_print(client.estimate_credits(
|
|
521
|
+
template_id=_resolve_template_id(client, args.template),
|
|
522
|
+
prompt=args.prompt or None,
|
|
523
|
+
script=script or None,
|
|
524
|
+
duration=args.duration or None,
|
|
525
|
+
voiceover_seconds=args.voiceover_seconds,
|
|
526
|
+
talking_head_seconds=args.talking_head_seconds,
|
|
527
|
+
output=args.output or None,
|
|
528
|
+
avatar_intro_only=args.avatar_intro_only,
|
|
529
|
+
avatar_ai_footage=args.avatar_ai_footage,
|
|
530
|
+
avatar_profile_id=args.avatar,
|
|
531
|
+
avatar_engine=args.avatar_engine or None,
|
|
532
|
+
render_only=args.render_only or None,
|
|
533
|
+
vector_reveal_mode=args.vector_motion or None,
|
|
534
|
+
))
|
|
411
535
|
elif args.cmd == "generate":
|
|
412
536
|
script = args.script
|
|
413
537
|
if args.script_file:
|
|
414
538
|
script = Path(args.script_file).read_text(encoding="utf-8")
|
|
415
539
|
voiceover = (args.voiceover or "").strip()
|
|
540
|
+
voiceover_url = (args.voiceover_url or "").strip()
|
|
416
541
|
talking_head = (args.talking_head or "").strip()
|
|
417
|
-
if talking_head and voiceover:
|
|
542
|
+
if talking_head and (voiceover or voiceover_url):
|
|
418
543
|
raise CliptudeApiError("Use --talking-head or --voiceover, not both.")
|
|
419
544
|
if talking_head and (args.prompt or script):
|
|
420
545
|
raise CliptudeApiError(
|
|
@@ -438,15 +563,21 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
438
563
|
script=script or None,
|
|
439
564
|
duration=(args.duration or None),
|
|
440
565
|
voiceover_path=voiceover or None,
|
|
566
|
+
voiceover_url=voiceover_url or None,
|
|
441
567
|
talking_head_path=talking_head or None,
|
|
442
568
|
avatar_intro_only=args.avatar_intro_only,
|
|
443
569
|
avatar_ai_footage=args.avatar_ai_footage,
|
|
570
|
+
avatar_profile_id=args.avatar,
|
|
571
|
+
avatar_engine=args.avatar_engine or None,
|
|
444
572
|
disable_animations=args.disable_animations,
|
|
445
573
|
disable_overlays=args.disable_overlays,
|
|
446
574
|
disable_effects=args.disable_effects,
|
|
447
575
|
disable_transitions=args.disable_transitions,
|
|
448
576
|
excluded_animation_types=args.excluded_animation_types,
|
|
449
577
|
excluded_transition_kinds=args.excluded_transition_kinds,
|
|
578
|
+
thumbnail=_thumbnail_from_args(args),
|
|
579
|
+
vector_character_id=args.vector_character or None,
|
|
580
|
+
vector_reveal_mode=args.vector_motion or None,
|
|
450
581
|
))
|
|
451
582
|
elif args.cmd == "script":
|
|
452
583
|
if not (args.prompt or "").strip():
|
|
@@ -479,8 +610,9 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
479
610
|
if args.script_file:
|
|
480
611
|
script = Path(args.script_file).read_text(encoding="utf-8")
|
|
481
612
|
voiceover = (args.voiceover or "").strip()
|
|
482
|
-
|
|
483
|
-
|
|
613
|
+
voiceover_url = (args.voiceover_url or "").strip()
|
|
614
|
+
if not (args.prompt or "").strip() and not (script or "").strip() and not voiceover and not voiceover_url:
|
|
615
|
+
raise CliptudeApiError("Provide --prompt, --script / --script-file, --voiceover or --voiceover-url.")
|
|
484
616
|
template_id = _resolve_template_id(client, args.template)
|
|
485
617
|
_print(client.create_job(
|
|
486
618
|
template_id=template_id,
|
|
@@ -488,8 +620,15 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
488
620
|
prompt=args.prompt or None,
|
|
489
621
|
script=script or None,
|
|
490
622
|
voiceover_path=voiceover or None,
|
|
623
|
+
voiceover_url=voiceover_url or None,
|
|
491
624
|
duration=(args.duration or None),
|
|
492
625
|
output="plan",
|
|
626
|
+
avatar_profile_id=args.avatar,
|
|
627
|
+
avatar_engine=args.avatar_engine or None,
|
|
628
|
+
render_only=args.render_only or None,
|
|
629
|
+
thumbnail=_thumbnail_from_args(args),
|
|
630
|
+
vector_character_id=args.vector_character or None,
|
|
631
|
+
vector_reveal_mode=args.vector_motion or None,
|
|
493
632
|
))
|
|
494
633
|
elif args.cmd == "narration":
|
|
495
634
|
_print(client.get_narration(args.job_id))
|
|
@@ -508,6 +647,8 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
508
647
|
_print(client.get_plan_review(args.job_id))
|
|
509
648
|
elif args.cmd == "plan-report":
|
|
510
649
|
_print(client.get_plan_report(args.job_id))
|
|
650
|
+
elif args.cmd == "upload-media":
|
|
651
|
+
_print(client.upload_plan_media(args.job_id, args.path))
|
|
511
652
|
elif args.cmd == "download-voiceover":
|
|
512
653
|
dest = Path(args.out)
|
|
513
654
|
client.download_voiceover_file(args.job_id, dest)
|
package/cliptude_mcp/client.py
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
from __future__ import annotations
|
|
4
4
|
|
|
5
5
|
import json
|
|
6
|
+
import mimetypes
|
|
6
7
|
import os
|
|
7
8
|
from contextvars import ContextVar
|
|
8
9
|
from pathlib import Path
|
|
@@ -129,8 +130,14 @@ def _avatar_job_fields(
|
|
|
129
130
|
avatar_ai_footage: bool | None,
|
|
130
131
|
*,
|
|
131
132
|
as_strings: bool = False,
|
|
133
|
+
avatar_profile_id: int | str | None = None,
|
|
134
|
+
avatar_engine: str | None = None,
|
|
132
135
|
) -> dict[str, Any]:
|
|
133
136
|
fields: dict[str, Any] = {}
|
|
137
|
+
if avatar_profile_id not in (None, ""):
|
|
138
|
+
fields["avatar_profile_id"] = str(avatar_profile_id) if as_strings else int(avatar_profile_id)
|
|
139
|
+
if avatar_engine:
|
|
140
|
+
fields["avatar_engine"] = str(avatar_engine).strip().lower()
|
|
134
141
|
if avatar_intro_only is not None:
|
|
135
142
|
fields["avatar_intro_only"] = (
|
|
136
143
|
("true" if avatar_intro_only else "false") if as_strings else bool(avatar_intro_only)
|
|
@@ -142,6 +149,14 @@ def _avatar_job_fields(
|
|
|
142
149
|
return fields
|
|
143
150
|
|
|
144
151
|
|
|
152
|
+
def _thumbnail_job_field(thumbnail: dict[str, str] | None, *, as_string: bool = False) -> dict[str, Any]:
|
|
153
|
+
"""create_job's per-job thumbnail ({custom_prompt} or {reference_url}); multipart sends it as JSON text."""
|
|
154
|
+
cleaned = {k: str(v).strip() for k, v in (thumbnail or {}).items() if v is not None and str(v).strip()}
|
|
155
|
+
if not cleaned:
|
|
156
|
+
return {}
|
|
157
|
+
return {"thumbnail": json.dumps(cleaned) if as_string else cleaned}
|
|
158
|
+
|
|
159
|
+
|
|
145
160
|
def _motion_control_job_fields(
|
|
146
161
|
*,
|
|
147
162
|
disable_animations: bool | None = None,
|
|
@@ -173,8 +188,16 @@ def _motion_control_job_fields(
|
|
|
173
188
|
|
|
174
189
|
|
|
175
190
|
class CliptudeClient:
|
|
176
|
-
def __init__(
|
|
191
|
+
def __init__(
|
|
192
|
+
self,
|
|
193
|
+
base_url: str | None = None,
|
|
194
|
+
api_key: str | None = None,
|
|
195
|
+
timeout: float = 30.0,
|
|
196
|
+
client_kind: str | None = None,
|
|
197
|
+
):
|
|
177
198
|
self.base_url = (base_url or resolve_base_url()).rstrip("/")
|
|
199
|
+
# "cli" or "mcp": sent as X-Cliptude-Client so Cliptude records where a job was started.
|
|
200
|
+
self.client_kind = (client_kind or os.environ.get("CLIPTUDE_CLIENT_KIND") or "").strip().lower()
|
|
178
201
|
self.api_key = _resolve_token(api_key)
|
|
179
202
|
self.timeout = timeout
|
|
180
203
|
self._session_file = not bool(
|
|
@@ -191,6 +214,8 @@ class CliptudeClient:
|
|
|
191
214
|
"Accept": "application/json",
|
|
192
215
|
**django_proxy_headers(self.base_url),
|
|
193
216
|
}
|
|
217
|
+
if self.client_kind:
|
|
218
|
+
headers["X-Cliptude-Client"] = self.client_kind
|
|
194
219
|
if json_content:
|
|
195
220
|
headers["Content-Type"] = "application/json"
|
|
196
221
|
return headers
|
|
@@ -266,17 +291,31 @@ class CliptudeClient:
|
|
|
266
291
|
script: str | None = None,
|
|
267
292
|
duration: str | None = None,
|
|
268
293
|
voiceover_path: str | Path | None = None,
|
|
294
|
+
voiceover_url: str | None = None,
|
|
269
295
|
talking_head_path: str | Path | None = None,
|
|
270
296
|
output: str | None = None,
|
|
271
297
|
avatar_intro_only: bool | None = None,
|
|
272
298
|
avatar_ai_footage: bool | None = None,
|
|
299
|
+
avatar_profile_id: int | str | None = None,
|
|
300
|
+
avatar_engine: str | None = None,
|
|
273
301
|
disable_animations: bool | None = None,
|
|
274
302
|
disable_overlays: bool | None = None,
|
|
275
303
|
disable_effects: bool | None = None,
|
|
276
304
|
disable_transitions: bool | None = None,
|
|
277
305
|
excluded_animation_types: list[str] | None = None,
|
|
278
306
|
excluded_transition_kinds: list[str] | None = None,
|
|
307
|
+
render_only: bool | None = None,
|
|
308
|
+
thumbnail: dict[str, str] | None = None,
|
|
309
|
+
vector_character_id: str | None = None,
|
|
310
|
+
vector_reveal_mode: str | None = None,
|
|
279
311
|
) -> Any:
|
|
312
|
+
if voiceover_path and voiceover_url:
|
|
313
|
+
raise CliptudeApiError("Give voiceover_path or voiceover_url, not both.")
|
|
314
|
+
if render_only and ((output or "").strip().lower() != "plan" or not (voiceover_path or voiceover_url)):
|
|
315
|
+
raise CliptudeApiError(
|
|
316
|
+
"render_only is a plan job with your own narration: pass output=\"plan\" and a voiceover "
|
|
317
|
+
"(voiceover_path, or voiceover_url for a public link)."
|
|
318
|
+
)
|
|
280
319
|
motion_fields = _motion_control_job_fields(
|
|
281
320
|
disable_animations=disable_animations,
|
|
282
321
|
disable_overlays=disable_overlays,
|
|
@@ -328,12 +367,20 @@ class CliptudeClient:
|
|
|
328
367
|
disable_transitions=disable_transitions,
|
|
329
368
|
excluded_animation_types=excluded_animation_types,
|
|
330
369
|
excluded_transition_kinds=excluded_transition_kinds,
|
|
370
|
+
thumbnail=thumbnail,
|
|
331
371
|
)
|
|
332
372
|
if vo_path:
|
|
333
373
|
extra_data = {
|
|
334
|
-
**_avatar_job_fields(
|
|
374
|
+
**_avatar_job_fields(
|
|
375
|
+
avatar_intro_only, avatar_ai_footage, as_strings=True,
|
|
376
|
+
avatar_profile_id=avatar_profile_id, avatar_engine=avatar_engine,
|
|
377
|
+
),
|
|
335
378
|
**motion_fields_str,
|
|
336
379
|
**({"output": output_kind} if output_kind == "plan" else {}),
|
|
380
|
+
**({"render_only": "true"} if render_only else {}),
|
|
381
|
+
**_thumbnail_job_field(thumbnail, as_string=True),
|
|
382
|
+
**({"vector_character_id": str(vector_character_id)} if vector_character_id else {}),
|
|
383
|
+
**({"vector_reveal_mode": str(vector_reveal_mode)} if vector_reveal_mode else {}),
|
|
337
384
|
}
|
|
338
385
|
return self._create_job_multipart(
|
|
339
386
|
template_id=template_id,
|
|
@@ -353,8 +400,21 @@ class CliptudeClient:
|
|
|
353
400
|
body["duration"] = duration
|
|
354
401
|
if output_kind and output_kind != "video":
|
|
355
402
|
body["output"] = output_kind
|
|
356
|
-
|
|
403
|
+
if voiceover_url:
|
|
404
|
+
# A public link to the narration: Cliptude downloads it (remote hosts cannot upload a file).
|
|
405
|
+
body["voiceover_url"] = str(voiceover_url).strip()
|
|
406
|
+
if render_only:
|
|
407
|
+
body["render_only"] = True
|
|
408
|
+
body.update(_avatar_job_fields(
|
|
409
|
+
avatar_intro_only, avatar_ai_footage,
|
|
410
|
+
avatar_profile_id=avatar_profile_id, avatar_engine=avatar_engine,
|
|
411
|
+
))
|
|
357
412
|
body.update(motion_fields)
|
|
413
|
+
body.update(_thumbnail_job_field(thumbnail))
|
|
414
|
+
if vector_character_id:
|
|
415
|
+
body["vector_character_id"] = str(vector_character_id)
|
|
416
|
+
if vector_reveal_mode:
|
|
417
|
+
body["vector_reveal_mode"] = str(vector_reveal_mode)
|
|
358
418
|
return self.request("POST", "/api/v1/jobs", json_body=body)
|
|
359
419
|
|
|
360
420
|
def _raise_http(self, resp, *, payload=None) -> None:
|
|
@@ -450,6 +510,7 @@ class CliptudeClient:
|
|
|
450
510
|
disable_transitions: bool | None = None,
|
|
451
511
|
excluded_animation_types: list[str] | None = None,
|
|
452
512
|
excluded_transition_kinds: list[str] | None = None,
|
|
513
|
+
thumbnail: dict[str, str] | None = None,
|
|
453
514
|
) -> Any:
|
|
454
515
|
motion_extra = _motion_control_job_fields(
|
|
455
516
|
disable_animations=disable_animations,
|
|
@@ -483,6 +544,7 @@ class CliptudeClient:
|
|
|
483
544
|
extra_data = {
|
|
484
545
|
**_avatar_job_fields(avatar_intro_only, avatar_ai_footage, as_strings=True),
|
|
485
546
|
**motion_extra,
|
|
547
|
+
**_thumbnail_job_field(thumbnail, as_string=True),
|
|
486
548
|
}
|
|
487
549
|
return self._create_job_multipart(
|
|
488
550
|
template_id=template_id,
|
|
@@ -500,6 +562,7 @@ class CliptudeClient:
|
|
|
500
562
|
extra_data = {
|
|
501
563
|
**_avatar_job_fields(avatar_intro_only, avatar_ai_footage, as_strings=True),
|
|
502
564
|
**motion_extra,
|
|
565
|
+
**_thumbnail_job_field(thumbnail, as_string=True),
|
|
503
566
|
}
|
|
504
567
|
return self._create_job_multipart(
|
|
505
568
|
template_id=template_id,
|
|
@@ -527,6 +590,7 @@ class CliptudeClient:
|
|
|
527
590
|
"talking_head_duration": str(duration),
|
|
528
591
|
}
|
|
529
592
|
body.update(_avatar_job_fields(avatar_intro_only, avatar_ai_footage))
|
|
593
|
+
body.update(_thumbnail_job_field(thumbnail))
|
|
530
594
|
body.update(
|
|
531
595
|
_motion_control_job_fields(
|
|
532
596
|
disable_animations=disable_animations,
|
|
@@ -540,23 +604,27 @@ class CliptudeClient:
|
|
|
540
604
|
return self.request("POST", "/api/v1/jobs", json_body=body)
|
|
541
605
|
|
|
542
606
|
def _upload_talking_head_parts(self, path: Path, init: dict[str, Any]) -> None:
|
|
607
|
+
self._upload_parts(path, init, "/api/v1/uploads/talking-head/sign-parts", "talking head")
|
|
608
|
+
|
|
609
|
+
def _upload_parts(self, path: Path, init: dict[str, Any], sign_path: str, label: str) -> None:
|
|
610
|
+
"""PUT the file straight to R2, part by part, on URLs Cliptude signs (no R2 keys here)."""
|
|
543
611
|
key = str(init.get("key") or "").strip()
|
|
544
612
|
upload_id = str(init.get("upload_id") or "").strip()
|
|
545
613
|
part_size = int(init.get("part_size") or 0)
|
|
546
614
|
part_count = int(init.get("part_count") or 0)
|
|
547
615
|
if not key or not upload_id or part_size <= 0 or part_count <= 0:
|
|
548
|
-
raise CliptudeApiError("
|
|
616
|
+
raise CliptudeApiError(f"The {label} upload init returned an incomplete plan.")
|
|
549
617
|
with path.open("rb") as fh:
|
|
550
618
|
for start in range(0, part_count, 50):
|
|
551
619
|
nums = list(range(start + 1, min(start + 50, part_count) + 1))
|
|
552
620
|
signed = self.request(
|
|
553
621
|
"POST",
|
|
554
|
-
|
|
622
|
+
sign_path,
|
|
555
623
|
json_body={"key": key, "upload_id": upload_id, "part_numbers": nums},
|
|
556
624
|
)
|
|
557
625
|
urls = (signed or {}).get("urls") if isinstance(signed, dict) else None
|
|
558
626
|
if not isinstance(urls, dict):
|
|
559
|
-
raise CliptudeApiError("Could not sign
|
|
627
|
+
raise CliptudeApiError(f"Could not sign {label} upload parts.")
|
|
560
628
|
for num in nums:
|
|
561
629
|
url = urls.get(str(num))
|
|
562
630
|
if not url:
|
|
@@ -568,7 +636,7 @@ class CliptudeClient:
|
|
|
568
636
|
raise CliptudeApiError(str(exc)) from exc
|
|
569
637
|
if resp.status_code >= 400:
|
|
570
638
|
raise CliptudeApiError(
|
|
571
|
-
f"Failed to upload
|
|
639
|
+
f"Failed to upload {label} part {num}.",
|
|
572
640
|
status=resp.status_code,
|
|
573
641
|
)
|
|
574
642
|
|
|
@@ -581,6 +649,32 @@ class CliptudeClient:
|
|
|
581
649
|
|
|
582
650
|
# Agent-planned videos -------------------------------------------------------------------------
|
|
583
651
|
|
|
652
|
+
def upload_plan_media(self, job_id: str, path: str | Path) -> Any:
|
|
653
|
+
"""Send a picture or clip you found to a plan job; returns {keep, file, media_type, size} for media.keep."""
|
|
654
|
+
path = Path(path)
|
|
655
|
+
if not path.is_file():
|
|
656
|
+
raise CliptudeApiError(f"File not found: {path}")
|
|
657
|
+
base = f"/api/v1/jobs/{job_id}/media"
|
|
658
|
+
init = self.request(
|
|
659
|
+
"POST",
|
|
660
|
+
f"{base}/init",
|
|
661
|
+
json_body={
|
|
662
|
+
"filename": path.name,
|
|
663
|
+
"size": path.stat().st_size,
|
|
664
|
+
"content_type": mimetypes.guess_type(path.name)[0] or "application/octet-stream",
|
|
665
|
+
},
|
|
666
|
+
)
|
|
667
|
+
body = {"key": (init or {}).get("key"), "upload_id": (init or {}).get("upload_id")}
|
|
668
|
+
try:
|
|
669
|
+
self._upload_parts(path, init, f"{base}/sign-parts", "media")
|
|
670
|
+
return self.request("POST", f"{base}/complete", json_body=body)
|
|
671
|
+
except Exception:
|
|
672
|
+
try:
|
|
673
|
+
self.request("POST", f"{base}/abort", json_body=body)
|
|
674
|
+
except Exception:
|
|
675
|
+
pass
|
|
676
|
+
raise
|
|
677
|
+
|
|
584
678
|
def get_narration(self, job_id: str) -> Any:
|
|
585
679
|
"""Numbered sentences (with word timings), digest, pricing and template flags of a plan job."""
|
|
586
680
|
return self.request("GET", f"/api/v1/jobs/{job_id}/narration")
|
|
@@ -724,3 +818,105 @@ class CliptudeClient:
|
|
|
724
818
|
|
|
725
819
|
def get_account(self) -> Any:
|
|
726
820
|
return self.request("GET", "/api/v1/account")
|
|
821
|
+
|
|
822
|
+
def estimate_credits(
|
|
823
|
+
self,
|
|
824
|
+
*,
|
|
825
|
+
template_id: str,
|
|
826
|
+
prompt: str | None = None,
|
|
827
|
+
script: str | None = None,
|
|
828
|
+
duration: str | None = None,
|
|
829
|
+
voiceover_seconds: float | None = None,
|
|
830
|
+
talking_head_seconds: float | None = None,
|
|
831
|
+
output: str | None = None,
|
|
832
|
+
avatar_intro_only: bool | None = None,
|
|
833
|
+
avatar_ai_footage: bool | None = None,
|
|
834
|
+
avatar_profile_id: int | str | None = None,
|
|
835
|
+
avatar_engine: str | None = None,
|
|
836
|
+
render_only: bool | None = None,
|
|
837
|
+
vector_reveal_mode: str | None = None,
|
|
838
|
+
) -> Any:
|
|
839
|
+
"""Credits a job would need; creates nothing."""
|
|
840
|
+
body: dict[str, Any] = {"template_id": template_id}
|
|
841
|
+
if render_only:
|
|
842
|
+
body["render_only"] = True
|
|
843
|
+
for key, value in (
|
|
844
|
+
("prompt", prompt),
|
|
845
|
+
("script", script),
|
|
846
|
+
("duration", duration),
|
|
847
|
+
("voiceover_seconds", voiceover_seconds),
|
|
848
|
+
("talking_head_seconds", talking_head_seconds),
|
|
849
|
+
("output", output),
|
|
850
|
+
("vector_reveal_mode", vector_reveal_mode),
|
|
851
|
+
):
|
|
852
|
+
if value is not None and value != "":
|
|
853
|
+
body[key] = value
|
|
854
|
+
body.update(_avatar_job_fields(
|
|
855
|
+
avatar_intro_only, avatar_ai_footage,
|
|
856
|
+
avatar_profile_id=avatar_profile_id, avatar_engine=avatar_engine,
|
|
857
|
+
))
|
|
858
|
+
return self.request("POST", "/api/v1/jobs/estimate", json_body=body)
|
|
859
|
+
|
|
860
|
+
def list_vector_characters(self) -> Any:
|
|
861
|
+
"""Vector Explainer characters: the built-in cast and your uploads (ids for vector_character_id)."""
|
|
862
|
+
return self.request("GET", "/api/v1/vector-characters")
|
|
863
|
+
|
|
864
|
+
def upload_vector_character(
|
|
865
|
+
self,
|
|
866
|
+
*,
|
|
867
|
+
image_path: str | Path | None = None,
|
|
868
|
+
image_url: str | None = None,
|
|
869
|
+
name: str = "",
|
|
870
|
+
_retried: bool = False,
|
|
871
|
+
) -> Any:
|
|
872
|
+
"""Add a Vector Explainer character from a local image or a public image URL; returns its id."""
|
|
873
|
+
if bool(image_path) == bool((image_url or "").strip()):
|
|
874
|
+
raise CliptudeApiError("Give image_path or image_url (one of them).")
|
|
875
|
+
if image_url:
|
|
876
|
+
return self.request(
|
|
877
|
+
"POST", "/api/v1/vector-characters", json_body={"image_url": image_url.strip(), "name": name}
|
|
878
|
+
)
|
|
879
|
+
path = Path(image_path)
|
|
880
|
+
if not path.is_file():
|
|
881
|
+
raise CliptudeApiError(f"Character image not found: {path}")
|
|
882
|
+
mime = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
|
|
883
|
+
try:
|
|
884
|
+
with path.open("rb") as fh:
|
|
885
|
+
resp = httpx.post(
|
|
886
|
+
f"{self.base_url}/api/v1/vector-characters",
|
|
887
|
+
headers=self._headers(json_content=False),
|
|
888
|
+
data={"name": name},
|
|
889
|
+
files={"image": (path.name, fh, mime)},
|
|
890
|
+
timeout=max(self.timeout, 120.0),
|
|
891
|
+
)
|
|
892
|
+
except httpx.HTTPError as exc:
|
|
893
|
+
raise CliptudeApiError(str(exc)) from exc
|
|
894
|
+
if resp.status_code == 401 and not _retried and self._maybe_refresh():
|
|
895
|
+
return self.upload_vector_character(image_path=image_path, name=name, _retried=True)
|
|
896
|
+
try:
|
|
897
|
+
payload = resp.json()
|
|
898
|
+
except ValueError:
|
|
899
|
+
payload = {"error": resp.text}
|
|
900
|
+
if resp.status_code >= 400:
|
|
901
|
+
self._raise_http(resp, payload=payload)
|
|
902
|
+
return payload
|
|
903
|
+
|
|
904
|
+
def delete_vector_character(self, character_id: str) -> Any:
|
|
905
|
+
"""Delete one of your uploaded characters (refused while a template uses it)."""
|
|
906
|
+
return self.request("DELETE", f"/api/v1/vector-characters/{character_id}")
|
|
907
|
+
|
|
908
|
+
def list_avatars(
|
|
909
|
+
self,
|
|
910
|
+
*,
|
|
911
|
+
section: str | None = None,
|
|
912
|
+
search: str | None = None,
|
|
913
|
+
gender: str | None = None,
|
|
914
|
+
limit: int = 50,
|
|
915
|
+
offset: int = 0,
|
|
916
|
+
) -> Any:
|
|
917
|
+
"""Avatars for Avatar Video (ids for avatar_profile_id)."""
|
|
918
|
+
params: dict[str, Any] = {"limit": limit, "offset": offset}
|
|
919
|
+
for key, value in (("section", section), ("search", search), ("gender", gender)):
|
|
920
|
+
if value:
|
|
921
|
+
params[key] = value
|
|
922
|
+
return self.request("GET", "/api/v1/avatars", params=params)
|
package/cliptude_mcp/server.py
CHANGED
|
@@ -26,7 +26,17 @@ def _client() -> CliptudeClient:
|
|
|
26
26
|
set_request_token(token)
|
|
27
27
|
except Exception:
|
|
28
28
|
pass
|
|
29
|
-
return CliptudeClient(api_key=token)
|
|
29
|
+
return CliptudeClient(api_key=token, client_kind="mcp")
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def _thumbnail_arg(prompt: str | None, reference_url: str | None) -> dict[str, str] | None:
|
|
33
|
+
"""create_job's thumbnail object from the flat tool arguments (None keeps the template's)."""
|
|
34
|
+
thumbnail = {
|
|
35
|
+
key: value.strip()
|
|
36
|
+
for key, value in (("custom_prompt", prompt), ("reference_url", reference_url))
|
|
37
|
+
if value and value.strip()
|
|
38
|
+
}
|
|
39
|
+
return thumbnail or None
|
|
30
40
|
|
|
31
41
|
|
|
32
42
|
def _err(exc: Exception) -> dict[str, Any]:
|
|
@@ -96,6 +106,8 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
96
106
|
"prompt, script, voiceover_path (uploaded audio, transcribed; skips TTS), "
|
|
97
107
|
"or talking_head_path (presenter video on a Talking Head template). "
|
|
98
108
|
"create_job returns immediately; poll get_job until completed or failed. "
|
|
109
|
+
"To quote a price or check the balance first, call estimate_credits with the same "
|
|
110
|
+
"template and prompt/script (an upload as voiceover_seconds); it creates nothing. "
|
|
99
111
|
"For a script only (no MP4), use create_script. For narration audio only, "
|
|
100
112
|
"use create_voiceover. To turn a completed script or voiceover job into an MP4 "
|
|
101
113
|
"on the same job id, use continue_job (do not create a second job). "
|
|
@@ -105,6 +117,8 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
105
117
|
"If they provide a voiceover file, pass voiceover_path and omit prompt/script. "
|
|
106
118
|
"If they provide a talking-head recording, pass talking_head_path and omit "
|
|
107
119
|
"prompt/script/voiceover_path (template format must be talking_head). "
|
|
120
|
+
"Avatar Video: list_avatars gives avatar ids; put one in create_template settings as "
|
|
121
|
+
"avatar_profile_id (with the voice), or pass avatar_profile_id on create_job to override. "
|
|
108
122
|
"Avatar Video templates may include avatar_intro_only "
|
|
109
123
|
"(Avatar Intro Only) and avatar_ai_footage (AI Image + AI Video); pass those "
|
|
110
124
|
"on create_job to override the template, or omit them to keep the template. "
|
|
@@ -187,7 +201,12 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
187
201
|
description=(
|
|
188
202
|
"Wizard settings: voice_id, voice_name, voice_provider plus any field from "
|
|
189
203
|
"get_template_options (unset fields take the wizard defaults). "
|
|
190
|
-
"
|
|
204
|
+
"Avatar Video: avatar_profile_id from list_avatars (gender must match the voice). "
|
|
205
|
+
"Vector Explainer: vector_character_id from get_template_options (vector_character.choices: "
|
|
206
|
+
"a built-in id such as nova, or one of the user's uploaded figures); omit it for no character. "
|
|
207
|
+
"Optional thumbnail: {reference_url} (a YouTube video link or https image whose style every "
|
|
208
|
+
"thumbnail copies) or {custom_prompt} (a standing brief: people, style, branding; each video "
|
|
209
|
+
"still sets its own subject and text). Omit it and each job picks a reference for its title."
|
|
191
210
|
)
|
|
192
211
|
),
|
|
193
212
|
],
|
|
@@ -198,6 +217,131 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
198
217
|
except Exception as exc:
|
|
199
218
|
return _err(exc)
|
|
200
219
|
|
|
220
|
+
@mcp.tool(
|
|
221
|
+
title="Estimate credits",
|
|
222
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
223
|
+
)
|
|
224
|
+
def estimate_credits(
|
|
225
|
+
template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
|
|
226
|
+
prompt: Annotated[str | None, Field(description="Topic/brief, as you would send to create_job.")] = None,
|
|
227
|
+
script: Annotated[str | None, Field(description="Spoken narration, as you would send to create_job. Its length sets the estimate.")] = None,
|
|
228
|
+
duration: Annotated[
|
|
229
|
+
str | None,
|
|
230
|
+
Field(description="Duration bucket such as 6-8. Omit to use the template (or estimate from script)."),
|
|
231
|
+
] = None,
|
|
232
|
+
voiceover_seconds: Annotated[
|
|
233
|
+
float | None,
|
|
234
|
+
Field(gt=0, description="Length of the voiceover you would upload. Uploaded voiceovers bill at the lowest voice rate. Do not also send prompt or script."),
|
|
235
|
+
] = None,
|
|
236
|
+
talking_head_seconds: Annotated[
|
|
237
|
+
float | None,
|
|
238
|
+
Field(gt=0, description="Length of the talking-head video you would upload (Talking Head templates only)."),
|
|
239
|
+
] = None,
|
|
240
|
+
output: Annotated[
|
|
241
|
+
str | None,
|
|
242
|
+
Field(description='"video" (default), "plan", "script" or "voiceover" — the output you would request.'),
|
|
243
|
+
] = None,
|
|
244
|
+
avatar_intro_only: Annotated[bool | None, Field(description="Avatar Video only, as in create_job.")] = None,
|
|
245
|
+
avatar_ai_footage: Annotated[bool | None, Field(description="Avatar Video only, as in create_job.")] = None,
|
|
246
|
+
avatar_profile_id: Annotated[
|
|
247
|
+
int | None,
|
|
248
|
+
Field(description="Avatar Video only: avatar id from list_avatars. Omit to use the template's avatar."),
|
|
249
|
+
] = None,
|
|
250
|
+
avatar_engine: Annotated[
|
|
251
|
+
str | None,
|
|
252
|
+
Field(description='Avatar Video only: "iii", "iv" or "v" (list_avatars shows which each avatar supports). Omit to keep the template.'),
|
|
253
|
+
] = None,
|
|
254
|
+
render_only: Annotated[
|
|
255
|
+
bool | None,
|
|
256
|
+
Field(description="Render-only plan job: you bring the voiceover (voiceover_path, or voiceover_url on a remote host), every picture and clip (url, or keep from upload_plan_media) and the graphics; Cliptude searches, writes, voices and generates nothing and charges only the render-only rate per minute."),
|
|
257
|
+
] = None,
|
|
258
|
+
vector_reveal_mode: Annotated[
|
|
259
|
+
str | None,
|
|
260
|
+
Field(description='Vector Explainer only: "none" (stills with camera moves) or "video" (AI clips), to price a job that overrides the template.'),
|
|
261
|
+
] = None,
|
|
262
|
+
) -> dict[str, Any]:
|
|
263
|
+
"""Credits a job would need before you create it, with the same pricing as create_job. Creates and charges nothing.
|
|
264
|
+
|
|
265
|
+
Returns credits_required (what is held to start; the final charge after render is usually lower),
|
|
266
|
+
credits_estimate (before the safety buffer), credits_per_minute, estimated_seconds, voice_source for
|
|
267
|
+
voice-priced formats, narration_credits for plan jobs, credits_available and enough_credits.
|
|
268
|
+
Use it to quote the user a price or check the balance before create_job."""
|
|
269
|
+
try:
|
|
270
|
+
return _client().estimate_credits(
|
|
271
|
+
template_id=template_id,
|
|
272
|
+
prompt=prompt,
|
|
273
|
+
script=script,
|
|
274
|
+
duration=duration,
|
|
275
|
+
voiceover_seconds=voiceover_seconds,
|
|
276
|
+
talking_head_seconds=talking_head_seconds,
|
|
277
|
+
output=output,
|
|
278
|
+
avatar_intro_only=avatar_intro_only,
|
|
279
|
+
avatar_ai_footage=avatar_ai_footage,
|
|
280
|
+
avatar_profile_id=avatar_profile_id,
|
|
281
|
+
avatar_engine=avatar_engine,
|
|
282
|
+
render_only=render_only,
|
|
283
|
+
vector_reveal_mode=vector_reveal_mode,
|
|
284
|
+
)
|
|
285
|
+
except Exception as exc:
|
|
286
|
+
return _err(exc)
|
|
287
|
+
|
|
288
|
+
@mcp.tool(
|
|
289
|
+
title="List avatars",
|
|
290
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
291
|
+
)
|
|
292
|
+
def list_avatars(
|
|
293
|
+
section: Annotated[
|
|
294
|
+
str | None,
|
|
295
|
+
Field(description='"mine" (photo avatars the user created), "builtin", "public" or "favorites". Omit for all.'),
|
|
296
|
+
] = None,
|
|
297
|
+
search: Annotated[str | None, Field(description="Part of the avatar's name.")] = None,
|
|
298
|
+
gender: Annotated[str | None, Field(description='"male" or "female" to match the voice. Omit for all.')] = None,
|
|
299
|
+
limit: Annotated[int, Field(ge=1, le=100)] = 50,
|
|
300
|
+
offset: Annotated[int, Field(ge=0)] = 0,
|
|
301
|
+
) -> dict[str, Any]:
|
|
302
|
+
"""Avatars the user can put in an Avatar Video: id, name, section, gender, engines, thumbnail_url. Pass an id as avatar_profile_id to create_template (in settings), create_job, create_plan_job or estimate_credits. The avatar's gender must match the voice."""
|
|
303
|
+
try:
|
|
304
|
+
return _client().list_avatars(section=section, search=search, gender=gender, limit=limit, offset=offset)
|
|
305
|
+
except Exception as exc:
|
|
306
|
+
return _err(exc)
|
|
307
|
+
|
|
308
|
+
@mcp.tool(
|
|
309
|
+
title="List vector characters",
|
|
310
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
311
|
+
)
|
|
312
|
+
def list_vector_characters() -> dict[str, Any]:
|
|
313
|
+
"""Characters for Vector Explainer videos: the built-in cast (id, name, descriptor, description, preview_url) and the user's own uploads (id, name, preview_url). Pass an id as vector_character_id in create_template settings, or on create_job / create_plan_job for one video. Also returns upload_guidance for making a new one."""
|
|
314
|
+
try:
|
|
315
|
+
return _client().list_vector_characters()
|
|
316
|
+
except Exception as exc:
|
|
317
|
+
return _err(exc)
|
|
318
|
+
|
|
319
|
+
@mcp.tool(title="Upload vector character")
|
|
320
|
+
def upload_vector_character(
|
|
321
|
+
name: Annotated[str, Field(min_length=1, max_length=120, description="A short name for the character, e.g. 'Dr. Maya'")],
|
|
322
|
+
image_path: Annotated[str | None, Field(description="Local PNG, JPG or WEBP file. Stdio / local MCP only.")] = None,
|
|
323
|
+
image_url: Annotated[str | None, Field(description="Public https link to the image (use on remote hosts).")] = None,
|
|
324
|
+
) -> dict[str, Any]:
|
|
325
|
+
"""Add the user's own Vector Explainer character and return its id (use it as vector_character_id). Use a picture the user supplied, or one you made for them: in that case show it to the user and upload only after they approve it. Best results: one full-body, front-facing character in flat vector style on a plain or transparent background, at least 1024 px, no text. It appears in the Cliptude wizard too."""
|
|
326
|
+
try:
|
|
327
|
+
path = (image_path or "").strip() or None
|
|
328
|
+
url = (image_url or "").strip() or None
|
|
329
|
+
if bool(path) == bool(url):
|
|
330
|
+
return {"error": "Give image_path or image_url (one of them)."}
|
|
331
|
+
return _client().upload_vector_character(image_path=path, image_url=url, name=name)
|
|
332
|
+
except Exception as exc:
|
|
333
|
+
return _err(exc)
|
|
334
|
+
|
|
335
|
+
@mcp.tool(title="Delete vector character")
|
|
336
|
+
def delete_vector_character(
|
|
337
|
+
character_id: Annotated[str, Field(min_length=8, description="Uploaded character id from list_vector_characters")],
|
|
338
|
+
) -> dict[str, Any]:
|
|
339
|
+
"""Delete one of the user's uploaded characters (built-in ones cannot be deleted). Refused while a saved template uses it. Only when the user asks."""
|
|
340
|
+
try:
|
|
341
|
+
return _client().delete_vector_character(character_id)
|
|
342
|
+
except Exception as exc:
|
|
343
|
+
return _err(exc)
|
|
344
|
+
|
|
201
345
|
@mcp.tool(title="Create video job")
|
|
202
346
|
def create_job(
|
|
203
347
|
template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
|
|
@@ -242,11 +386,19 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
242
386
|
bool | None,
|
|
243
387
|
Field(
|
|
244
388
|
description=(
|
|
245
|
-
"Avatar Video only: AI Image + AI Video instead of stock
|
|
389
|
+
"Avatar Video only: AI Image + AI Video instead of stock and web footage. "
|
|
246
390
|
"Omit to use the saved template. Other formats reject this field."
|
|
247
391
|
),
|
|
248
392
|
),
|
|
249
393
|
] = None,
|
|
394
|
+
avatar_profile_id: Annotated[
|
|
395
|
+
int | None,
|
|
396
|
+
Field(description="Avatar Video only: avatar id from list_avatars. Omit to use the template's avatar."),
|
|
397
|
+
] = None,
|
|
398
|
+
avatar_engine: Annotated[
|
|
399
|
+
str | None,
|
|
400
|
+
Field(description='Avatar Video only: "iii", "iv" or "v" (list_avatars shows which each avatar supports). Omit to keep the template.'),
|
|
401
|
+
] = None,
|
|
250
402
|
disable_animations: Annotated[
|
|
251
403
|
bool | None,
|
|
252
404
|
Field(description="True = no animated text reveals or motion graphics. Omit to use the saved template."),
|
|
@@ -271,14 +423,37 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
271
423
|
list[str] | None,
|
|
272
424
|
Field(description="Transition slugs to exclude from auto-selection, e.g. 'flip-horizontal', 'film-burn'. Omit to use the saved template."),
|
|
273
425
|
] = None,
|
|
426
|
+
voiceover_url: Annotated[
|
|
427
|
+
str | None,
|
|
428
|
+
Field(description="Public https link to the narration audio (MP3, M4A, WAV, OGG, FLAC, WEBM; up to 200 MB). Cliptude downloads it and uses it like an uploaded voiceover. Use this on remote hosts, which cannot send a local file. Omit prompt/script and voiceover_path."),
|
|
429
|
+
] = None,
|
|
430
|
+
thumbnail_prompt: Annotated[
|
|
431
|
+
str | None,
|
|
432
|
+
Field(description="This video's thumbnail brief (subject, people, text, style), up to 2000 characters. Replaces the template's thumbnail for this job. Omit to use the template; omit thumbnail_reference_url too."),
|
|
433
|
+
] = None,
|
|
434
|
+
thumbnail_reference_url: Annotated[
|
|
435
|
+
str | None,
|
|
436
|
+
Field(description="A YouTube video link or https image whose thumbnail style to copy for this job (the content still comes from this video). Omit to use the template's; without one, Cliptude picks a reference for the title. Not with thumbnail_prompt."),
|
|
437
|
+
] = None,
|
|
438
|
+
vector_character_id: Annotated[
|
|
439
|
+
str | None,
|
|
440
|
+
Field(description='Vector Explainer only: a character id from list_vector_characters (built-in or uploaded), or "none", for this video. Omit to use the template\'s.'),
|
|
441
|
+
] = None,
|
|
442
|
+
vector_reveal_mode: Annotated[
|
|
443
|
+
str | None,
|
|
444
|
+
Field(description='Vector Explainer only: "none" = drawn stills with camera moves (Ken Burns), "video" = every picture beat animated as an AI clip (costs more; check estimate_credits). Omit to use the template\'s.'),
|
|
445
|
+
] = None,
|
|
274
446
|
) -> dict[str, Any]:
|
|
275
447
|
"""Start generation and return a job id immediately. Do not wait for the MP4. Poll get_job. Provide prompt, script, voiceover_path, or talking_head_path. Never copy the title into prompt; for a topic-only request write a spoken script after web search and pass script. Uploaded audio or talking-head video is transcribed. Avatar Video: optional avatar_intro_only and avatar_ai_footage override the template. Any format: optional disable_animations/disable_overlays/disable_effects/disable_transitions and excluded_animation_types/excluded_transition_kinds override the template's motion & effects settings."""
|
|
276
448
|
try:
|
|
277
449
|
vo = (voiceover_path or "").strip() or None
|
|
450
|
+
vo_url = (voiceover_url or "").strip() or None
|
|
278
451
|
th = (talking_head_path or "").strip() or None
|
|
279
|
-
if vo and
|
|
452
|
+
if vo and vo_url:
|
|
453
|
+
return {"error": "Give voiceover_path or voiceover_url, not both."}
|
|
454
|
+
if (vo or vo_url) and th:
|
|
280
455
|
return {"error": "Upload either a talking head video or a voiceover — not both."}
|
|
281
|
-
if (vo or th) and ((prompt or "").strip() or (script or "").strip()):
|
|
456
|
+
if (vo or vo_url or th) and ((prompt or "").strip() or (script or "").strip()):
|
|
282
457
|
kind = "talking head video" if th else "voiceover"
|
|
283
458
|
return {
|
|
284
459
|
"error": (
|
|
@@ -293,15 +468,21 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
293
468
|
script=script,
|
|
294
469
|
duration=duration,
|
|
295
470
|
voiceover_path=vo,
|
|
471
|
+
voiceover_url=vo_url,
|
|
296
472
|
talking_head_path=th,
|
|
297
473
|
avatar_intro_only=avatar_intro_only,
|
|
298
474
|
avatar_ai_footage=avatar_ai_footage,
|
|
475
|
+
avatar_profile_id=avatar_profile_id,
|
|
476
|
+
avatar_engine=avatar_engine,
|
|
299
477
|
disable_animations=disable_animations,
|
|
300
478
|
disable_overlays=disable_overlays,
|
|
301
479
|
disable_effects=disable_effects,
|
|
302
480
|
disable_transitions=disable_transitions,
|
|
303
481
|
excluded_animation_types=excluded_animation_types,
|
|
304
482
|
excluded_transition_kinds=excluded_transition_kinds,
|
|
483
|
+
thumbnail=_thumbnail_arg(thumbnail_prompt, thumbnail_reference_url),
|
|
484
|
+
vector_character_id=vector_character_id,
|
|
485
|
+
vector_reveal_mode=vector_reveal_mode,
|
|
305
486
|
)
|
|
306
487
|
except Exception as exc:
|
|
307
488
|
return _err(exc)
|
|
@@ -366,25 +547,64 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
366
547
|
|
|
367
548
|
@mcp.tool(title="Create agent-planned job")
|
|
368
549
|
def create_plan_job(
|
|
369
|
-
template_id: Annotated[str, Field(min_length=8, description="Saved Faceless Documentary, Faceless Top 10
|
|
550
|
+
template_id: Annotated[str, Field(min_length=8, description="Saved Faceless Documentary, Faceless Top 10, Avatar Video or Vector Explainer template UUID")],
|
|
370
551
|
title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
|
|
371
552
|
prompt: Annotated[str | None, Field(description="Topic/brief; Cliptude writes the narration. Never the video title.")] = None,
|
|
372
553
|
script: Annotated[str | None, Field(description="Spoken narration to voice as-is. Omit prompt when you pass this.")] = None,
|
|
373
|
-
voiceover_path: Annotated[str | None, Field(description="Local audio file to use as the narration (aligned, not re-voiced). Omit prompt/script.")] = None,
|
|
554
|
+
voiceover_path: Annotated[str | None, Field(description="Local audio file to use as the narration (aligned, not re-voiced). Omit prompt/script. Stdio / local MCP only.")] = None,
|
|
555
|
+
voiceover_url: Annotated[
|
|
556
|
+
str | None,
|
|
557
|
+
Field(description="Public https link to the narration audio (MP3, M4A, WAV, OGG, FLAC, WEBM; up to 200 MB). Cliptude downloads it and uses it like an uploaded voiceover. Use this on remote hosts, which cannot send a local file. Omit prompt/script and voiceover_path."),
|
|
558
|
+
] = None,
|
|
374
559
|
duration: Annotated[str | None, Field(description="Duration bucket such as 6-8. Omit to use the template.")] = None,
|
|
560
|
+
avatar_profile_id: Annotated[
|
|
561
|
+
int | None,
|
|
562
|
+
Field(description="Avatar Video only: avatar id from list_avatars. Omit to use the template's avatar."),
|
|
563
|
+
] = None,
|
|
564
|
+
avatar_engine: Annotated[
|
|
565
|
+
str | None,
|
|
566
|
+
Field(description='Avatar Video only: "iii", "iv" or "v" (list_avatars shows which each avatar supports). Omit to keep the template.'),
|
|
567
|
+
] = None,
|
|
568
|
+
render_only: Annotated[
|
|
569
|
+
bool | None,
|
|
570
|
+
Field(description="Render-only plan job: you bring the voiceover (voiceover_path, or voiceover_url on a remote host), every picture and clip (url, or keep from upload_plan_media) and the graphics; Cliptude searches, writes, voices and generates nothing and charges only the render-only rate per minute."),
|
|
571
|
+
] = None,
|
|
572
|
+
thumbnail_prompt: Annotated[
|
|
573
|
+
str | None,
|
|
574
|
+
Field(description="This video's thumbnail brief (subject, people, text, style), up to 2000 characters. Replaces the template's thumbnail for this job. Omit to use the template; omit thumbnail_reference_url too."),
|
|
575
|
+
] = None,
|
|
576
|
+
thumbnail_reference_url: Annotated[
|
|
577
|
+
str | None,
|
|
578
|
+
Field(description="A YouTube video link or https image whose thumbnail style to copy for this job (the content still comes from this video). Omit to use the template's; without one, Cliptude picks a reference for the title. Not with thumbnail_prompt."),
|
|
579
|
+
] = None,
|
|
580
|
+
vector_character_id: Annotated[
|
|
581
|
+
str | None,
|
|
582
|
+
Field(description='Vector Explainer only: a character id from list_vector_characters (built-in or uploaded), or "none", for this video. Omit to use the template\'s.'),
|
|
583
|
+
] = None,
|
|
584
|
+
vector_reveal_mode: Annotated[
|
|
585
|
+
str | None,
|
|
586
|
+
Field(description='Vector Explainer only: "none" = drawn stills with camera moves (Ken Burns), "video" = every picture beat animated as an AI clip (costs more; check estimate_credits). Omit to use the template\'s.'),
|
|
587
|
+
] = None,
|
|
375
588
|
) -> dict[str, Any]:
|
|
376
589
|
"""Start a job whose visuals YOU plan. 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."""
|
|
377
590
|
try:
|
|
378
|
-
if not (prompt or "").strip() and not (script or "").strip() and not voiceover_path:
|
|
379
|
-
return {"error": "Provide prompt, script or
|
|
591
|
+
if not (prompt or "").strip() and not (script or "").strip() and not voiceover_path and not voiceover_url:
|
|
592
|
+
return {"error": "Provide prompt, script, voiceover_path or voiceover_url."}
|
|
380
593
|
return _client().create_job(
|
|
381
594
|
template_id=template_id,
|
|
382
595
|
title=title,
|
|
383
596
|
prompt=prompt,
|
|
384
597
|
script=script,
|
|
385
598
|
voiceover_path=voiceover_path,
|
|
599
|
+
voiceover_url=(voiceover_url or "").strip() or None,
|
|
386
600
|
duration=duration,
|
|
387
601
|
output="plan",
|
|
602
|
+
avatar_profile_id=avatar_profile_id,
|
|
603
|
+
avatar_engine=avatar_engine,
|
|
604
|
+
render_only=render_only,
|
|
605
|
+
thumbnail=_thumbnail_arg(thumbnail_prompt, thumbnail_reference_url),
|
|
606
|
+
vector_character_id=vector_character_id,
|
|
607
|
+
vector_reveal_mode=vector_reveal_mode,
|
|
388
608
|
)
|
|
389
609
|
except Exception as exc:
|
|
390
610
|
return _err(exc)
|
|
@@ -407,7 +627,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
407
627
|
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
408
628
|
)
|
|
409
629
|
def get_kind_catalog(
|
|
410
|
-
format: Annotated[str | None, Field(description="faceless_documentary, faceless_top_10 or
|
|
630
|
+
format: Annotated[str | None, Field(description="faceless_documentary, faceless_top_10, avatar_video or vector_explainer")] = None,
|
|
411
631
|
theme: Annotated[str | None, Field(description="Visual theme, to mark graphics the theme does not use")] = None,
|
|
412
632
|
compact: Annotated[bool, Field(description="One summary line per graphic (start here; the full catalog is large)")] = True,
|
|
413
633
|
types: Annotated[list[str] | None, Field(description="Full entries (description, prop_schema, media_slots, durations, preview) for just these animation types / overlay styles")] = None,
|
|
@@ -470,6 +690,23 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
470
690
|
except Exception as exc:
|
|
471
691
|
return _err(exc)
|
|
472
692
|
|
|
693
|
+
@mcp.tool(
|
|
694
|
+
title="Upload plan media",
|
|
695
|
+
annotations=ToolAnnotations(read_only_hint=False, open_world_hint=False),
|
|
696
|
+
)
|
|
697
|
+
def upload_plan_media(
|
|
698
|
+
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID")],
|
|
699
|
+
path: Annotated[
|
|
700
|
+
str,
|
|
701
|
+
Field(description="Local picture (JPG/PNG/WEBP/GIF, up to 15 MB) or clip (MP4/MOV/WEBM/M4V, up to 300 MB). Stdio / local MCP only — remote hosts should use the CLI (cliptude upload-media) or give a public file link as media.url."),
|
|
702
|
+
],
|
|
703
|
+
) -> dict[str, Any]:
|
|
704
|
+
"""Send a picture or clip you found yourself to a plan job. The file goes straight to Cliptude's storage on signed URLs (no storage keys needed) and is checked to be a real picture or video. Returns {keep, file, media_type, size}: put {"keep": "<id>"} as a beat's media or a graphic's picture slot, with start_s/end_s on a beat to play only part of a clip."""
|
|
705
|
+
try:
|
|
706
|
+
return _client().upload_plan_media(job_id, path)
|
|
707
|
+
except Exception as exc:
|
|
708
|
+
return _err(exc)
|
|
709
|
+
|
|
473
710
|
@mcp.tool(
|
|
474
711
|
title="Get plan sourcing report",
|
|
475
712
|
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
package/package.json
CHANGED
package/pyproject.toml
CHANGED