@cliptude/cli 0.1.5 → 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 +44 -8
- 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 +523 -23
- package/cliptude_mcp/client.py +657 -77
- package/cliptude_mcp/server.py +644 -42
- package/package.json +1 -1
- package/pyproject.toml +1 -1
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]:
|
|
@@ -88,17 +98,35 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
88
98
|
|
|
89
99
|
kwargs: dict[str, Any] = {
|
|
90
100
|
"instructions": (
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
101
|
+
"Generate Cliptude videos from a saved template. "
|
|
102
|
+
"Call list_templates, then create_job with template_id + title plus "
|
|
103
|
+
"(no suitable template? get_template_options + list_voices, then create_template) "
|
|
104
|
+
"To revise a finished video: open_editor_project, run_agent with timeline item ids, "
|
|
105
|
+
"poll get_agent_run, then render_project and get_render. "
|
|
106
|
+
"prompt, script, voiceover_path (uploaded audio, transcribed; skips TTS), "
|
|
107
|
+
"or talking_head_path (presenter video on a Talking Head template). "
|
|
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. "
|
|
111
|
+
"For a script only (no MP4), use create_script. For narration audio only, "
|
|
112
|
+
"use create_voiceover. To turn a completed script or voiceover job into an MP4 "
|
|
113
|
+
"on the same job id, use continue_job (do not create a second job). "
|
|
114
|
+
"Never set prompt to the video title. If the user only named a topic or title, "
|
|
115
|
+
"web-search current facts, write spoken narration, and pass it as script. "
|
|
116
|
+
"If the user pastes a full narration, pass it as script, not prompt. "
|
|
117
|
+
"If they provide a voiceover file, pass voiceover_path and omit prompt/script. "
|
|
118
|
+
"If they provide a talking-head recording, pass talking_head_path and omit "
|
|
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. "
|
|
122
|
+
"Avatar Video templates may include avatar_intro_only "
|
|
123
|
+
"(Avatar Intro Only) and avatar_ai_footage (AI Image + AI Video); pass those "
|
|
124
|
+
"on create_job to override the template, or omit them to keep the template. "
|
|
125
|
+
"AGENT-PLANNED VIDEOS (Faceless Documentary, Top 10, Avatar Video): you plan every visual "
|
|
126
|
+
"and Cliptude only voices, sources and renders. create_plan_job, poll get_job until "
|
|
127
|
+
"plan_ready, get_narration (numbered sentences), get_kind_catalog (compact first), write the "
|
|
128
|
+
"plan, check_plan until valid, lock_plan, continue_job, then get_plan_report. See the "
|
|
129
|
+
"cliptude-plan skill."
|
|
102
130
|
),
|
|
103
131
|
}
|
|
104
132
|
if with_http_auth:
|
|
@@ -117,7 +145,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
117
145
|
limit: Annotated[int, Field(ge=1, le=100, description="Page size")] = 20,
|
|
118
146
|
offset: Annotated[int, Field(ge=0, description="Offset")] = 0,
|
|
119
147
|
) -> dict[str, Any]:
|
|
120
|
-
"""List saved video templates (id, name, format). Empty list means the user has not saved a template in Cliptude yet."""
|
|
148
|
+
"""List saved video templates (id, name, format). Avatar Video rows include avatar_intro_only and avatar_ai_footage. Empty list means the user has not saved a template in Cliptude yet."""
|
|
121
149
|
try:
|
|
122
150
|
return _client().list_templates(limit=limit, offset=offset)
|
|
123
151
|
except Exception as exc:
|
|
@@ -130,12 +158,190 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
130
158
|
def get_template(
|
|
131
159
|
template_id: Annotated[str, Field(min_length=8, description="Template UUID")],
|
|
132
160
|
) -> dict[str, Any]:
|
|
133
|
-
"""Get one saved template summary (not internal JSON)."""
|
|
161
|
+
"""Get one saved template summary (not internal JSON). Avatar Video includes avatar_intro_only and avatar_ai_footage."""
|
|
134
162
|
try:
|
|
135
163
|
return _client().get_template(template_id)
|
|
136
164
|
except Exception as exc:
|
|
137
165
|
return _err(exc)
|
|
138
166
|
|
|
167
|
+
@mcp.tool(
|
|
168
|
+
title="Get template options",
|
|
169
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
170
|
+
)
|
|
171
|
+
def get_template_options(
|
|
172
|
+
format: Annotated[str, Field(description="Video format, e.g. faceless_documentary or vector_explainer")],
|
|
173
|
+
) -> dict[str, Any]:
|
|
174
|
+
"""Fields, choices and defaults that create_template accepts for one format (styles, colours, backgrounds, music, models, durations)."""
|
|
175
|
+
try:
|
|
176
|
+
return _client().template_options(format)
|
|
177
|
+
except Exception as exc:
|
|
178
|
+
return _err(exc)
|
|
179
|
+
|
|
180
|
+
@mcp.tool(
|
|
181
|
+
title="List voices",
|
|
182
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=True),
|
|
183
|
+
)
|
|
184
|
+
def list_voices(
|
|
185
|
+
provider: Annotated[str, Field(description="elevenlabs, minimax, cartesia, inworld or voicetory")] = "elevenlabs",
|
|
186
|
+
language: Annotated[str | None, Field(description="Narration language, e.g. English")] = None,
|
|
187
|
+
) -> dict[str, Any]:
|
|
188
|
+
"""Voice catalog for one TTS provider. Use a voice's voice_id (and name, provider) in create_template."""
|
|
189
|
+
try:
|
|
190
|
+
return _client().list_voices(provider=provider, language=language)
|
|
191
|
+
except Exception as exc:
|
|
192
|
+
return _err(exc)
|
|
193
|
+
|
|
194
|
+
@mcp.tool(title="Create template")
|
|
195
|
+
def create_template(
|
|
196
|
+
name: Annotated[str, Field(min_length=1, max_length=120, description="Template name")],
|
|
197
|
+
format: Annotated[str, Field(description="Video format, e.g. faceless_documentary")],
|
|
198
|
+
settings: Annotated[
|
|
199
|
+
dict[str, Any],
|
|
200
|
+
Field(
|
|
201
|
+
description=(
|
|
202
|
+
"Wizard settings: voice_id, voice_name, voice_provider plus any field from "
|
|
203
|
+
"get_template_options (unset fields take the wizard defaults). "
|
|
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."
|
|
210
|
+
)
|
|
211
|
+
),
|
|
212
|
+
],
|
|
213
|
+
) -> dict[str, Any]:
|
|
214
|
+
"""Create a ready-to-use template without the create wizard. Values are validated like the wizard; returns the template (use its id in create_job)."""
|
|
215
|
+
try:
|
|
216
|
+
return _client().create_template(name=name, format=format, settings=settings)
|
|
217
|
+
except Exception as exc:
|
|
218
|
+
return _err(exc)
|
|
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
|
+
|
|
139
345
|
@mcp.tool(title="Create video job")
|
|
140
346
|
def create_job(
|
|
141
347
|
template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
|
|
@@ -152,27 +358,106 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
152
358
|
),
|
|
153
359
|
),
|
|
154
360
|
] = None,
|
|
155
|
-
|
|
361
|
+
talking_head_path: Annotated[
|
|
156
362
|
str | None,
|
|
157
363
|
Field(
|
|
158
364
|
description=(
|
|
159
|
-
|
|
160
|
-
|
|
365
|
+
"Local path to a talking-head presenter video (MP4, MOV, WEBM, AVI). "
|
|
366
|
+
"Requires a Talking Head template. Cliptude transcribes it and skips TTS. "
|
|
367
|
+
"Do not also send prompt, script, or voiceover_path. "
|
|
368
|
+
"Stdio / local MCP only — remote hosts should use the CLI."
|
|
161
369
|
),
|
|
162
370
|
),
|
|
163
|
-
] =
|
|
371
|
+
] = None,
|
|
164
372
|
duration: Annotated[
|
|
165
373
|
str | None,
|
|
166
|
-
Field(description="Wizard duration bucket such as 3-4 or 6-8. Omit to use the template (or estimate from script). Ignored when voiceover_path is set — duration comes from the
|
|
374
|
+
Field(description="Wizard duration bucket such as 3-4 or 6-8. Omit to use the template (or estimate from script). Ignored when voiceover_path or talking_head_path is set — duration comes from the file."),
|
|
375
|
+
] = None,
|
|
376
|
+
avatar_intro_only: Annotated[
|
|
377
|
+
bool | None,
|
|
378
|
+
Field(
|
|
379
|
+
description=(
|
|
380
|
+
"Avatar Video only: Avatar Intro Only. True = HeyGen in a short opening. "
|
|
381
|
+
"Omit to use the saved template. Other formats reject this field."
|
|
382
|
+
),
|
|
383
|
+
),
|
|
384
|
+
] = None,
|
|
385
|
+
avatar_ai_footage: Annotated[
|
|
386
|
+
bool | None,
|
|
387
|
+
Field(
|
|
388
|
+
description=(
|
|
389
|
+
"Avatar Video only: AI Image + AI Video instead of stock and web footage. "
|
|
390
|
+
"Omit to use the saved template. Other formats reject this field."
|
|
391
|
+
),
|
|
392
|
+
),
|
|
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,
|
|
402
|
+
disable_animations: Annotated[
|
|
403
|
+
bool | None,
|
|
404
|
+
Field(description="True = no animated text reveals or motion graphics. Omit to use the saved template."),
|
|
405
|
+
] = None,
|
|
406
|
+
disable_overlays: Annotated[
|
|
407
|
+
bool | None,
|
|
408
|
+
Field(description="True = no text overlays, stat cards, or graphic elements over footage. Captions are unaffected. Omit to use the saved template."),
|
|
409
|
+
] = None,
|
|
410
|
+
disable_effects: Annotated[
|
|
411
|
+
bool | None,
|
|
412
|
+
Field(description="True = no color grading, film grain, light leaks, or stylized treatments. Ken Burns pan/zoom is unaffected. Omit to use the saved template."),
|
|
413
|
+
] = None,
|
|
414
|
+
disable_transitions: Annotated[
|
|
415
|
+
bool | None,
|
|
416
|
+
Field(description="True = no scene transitions; hard cuts only. Omit to use the saved template."),
|
|
417
|
+
] = None,
|
|
418
|
+
excluded_animation_types: Annotated[
|
|
419
|
+
list[str] | None,
|
|
420
|
+
Field(description="Animation-type strings to exclude from this video (see list_templates/get_template or the app's motion-graphics catalog for valid values). Omit to use the saved template."),
|
|
421
|
+
] = None,
|
|
422
|
+
excluded_transition_kinds: Annotated[
|
|
423
|
+
list[str] | None,
|
|
424
|
+
Field(description="Transition slugs to exclude from auto-selection, e.g. 'flip-horizontal', 'film-burn'. Omit to use the saved template."),
|
|
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.'),
|
|
167
445
|
] = None,
|
|
168
446
|
) -> dict[str, Any]:
|
|
169
|
-
"""Start generation and return a job id immediately. Do not wait for the MP4. Poll get_job. Provide prompt, script, or
|
|
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."""
|
|
170
448
|
try:
|
|
171
449
|
vo = (voiceover_path or "").strip() or None
|
|
172
|
-
|
|
450
|
+
vo_url = (voiceover_url or "").strip() or None
|
|
451
|
+
th = (talking_head_path or "").strip() or None
|
|
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:
|
|
455
|
+
return {"error": "Upload either a talking head video or a voiceover — not both."}
|
|
456
|
+
if (vo or vo_url or th) and ((prompt or "").strip() or (script or "").strip()):
|
|
457
|
+
kind = "talking head video" if th else "voiceover"
|
|
173
458
|
return {
|
|
174
459
|
"error": (
|
|
175
|
-
"Upload a
|
|
460
|
+
f"Upload a {kind}, or send a prompt / custom script — not both. "
|
|
176
461
|
"An uploaded file is transcribed and used as the narration."
|
|
177
462
|
)
|
|
178
463
|
}
|
|
@@ -181,47 +466,270 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
181
466
|
title=title,
|
|
182
467
|
prompt=prompt,
|
|
183
468
|
script=script,
|
|
184
|
-
faceless_coding=faceless_coding,
|
|
185
469
|
duration=duration,
|
|
186
470
|
voiceover_path=vo,
|
|
471
|
+
voiceover_url=vo_url,
|
|
472
|
+
talking_head_path=th,
|
|
473
|
+
avatar_intro_only=avatar_intro_only,
|
|
474
|
+
avatar_ai_footage=avatar_ai_footage,
|
|
475
|
+
avatar_profile_id=avatar_profile_id,
|
|
476
|
+
avatar_engine=avatar_engine,
|
|
477
|
+
disable_animations=disable_animations,
|
|
478
|
+
disable_overlays=disable_overlays,
|
|
479
|
+
disable_effects=disable_effects,
|
|
480
|
+
disable_transitions=disable_transitions,
|
|
481
|
+
excluded_animation_types=excluded_animation_types,
|
|
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,
|
|
486
|
+
)
|
|
487
|
+
except Exception as exc:
|
|
488
|
+
return _err(exc)
|
|
489
|
+
|
|
490
|
+
@mcp.tool(title="Create script job")
|
|
491
|
+
def create_script(
|
|
492
|
+
template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
|
|
493
|
+
title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
|
|
494
|
+
prompt: Annotated[str, Field(min_length=1, description="Topic or brief. Cliptude researches and writes spoken narration. Never the video title.")],
|
|
495
|
+
duration: Annotated[
|
|
496
|
+
str | None,
|
|
497
|
+
Field(description="Wizard duration bucket such as 3-4 or 6-8. Omit to use the template."),
|
|
498
|
+
] = None,
|
|
499
|
+
) -> dict[str, Any]:
|
|
500
|
+
"""Start a script-only job (no MP4). Returns a job id immediately. Poll get_job until completed; read script. Do not use create_job."""
|
|
501
|
+
try:
|
|
502
|
+
return _client().create_job(
|
|
503
|
+
template_id=template_id,
|
|
504
|
+
title=title,
|
|
505
|
+
prompt=prompt,
|
|
506
|
+
duration=duration,
|
|
507
|
+
output="script",
|
|
508
|
+
)
|
|
509
|
+
except Exception as exc:
|
|
510
|
+
return _err(exc)
|
|
511
|
+
|
|
512
|
+
@mcp.tool(title="Create voiceover job")
|
|
513
|
+
def create_voiceover(
|
|
514
|
+
template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
|
|
515
|
+
title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
|
|
516
|
+
prompt: Annotated[str | None, Field(description="Topic/brief. Cliptude writes the narration then voices it. Never the video title.")] = None,
|
|
517
|
+
script: Annotated[str | None, Field(description="Spoken narration to voice as-is. Omit prompt when you pass this.")] = None,
|
|
518
|
+
duration: Annotated[
|
|
519
|
+
str | None,
|
|
520
|
+
Field(description="Wizard duration bucket such as 3-4 or 6-8. Omit to use the template (or estimate from script)."),
|
|
521
|
+
] = None,
|
|
522
|
+
) -> dict[str, Any]:
|
|
523
|
+
"""Start a TTS-only job (no MP4). Returns a job id immediately. Poll get_job until completed; read voiceover.url. Provide prompt or script."""
|
|
524
|
+
try:
|
|
525
|
+
if not (prompt or "").strip() and not (script or "").strip():
|
|
526
|
+
return {"error": "Provide prompt or script."}
|
|
527
|
+
return _client().create_job(
|
|
528
|
+
template_id=template_id,
|
|
529
|
+
title=title,
|
|
530
|
+
prompt=prompt,
|
|
531
|
+
script=script,
|
|
532
|
+
duration=duration,
|
|
533
|
+
output="voiceover",
|
|
534
|
+
)
|
|
535
|
+
except Exception as exc:
|
|
536
|
+
return _err(exc)
|
|
537
|
+
|
|
538
|
+
@mcp.tool(title="Continue job into video")
|
|
539
|
+
def continue_job(
|
|
540
|
+
job_id: Annotated[str, Field(min_length=8, description="Completed script or voiceover job UUID, or a plan job with a locked plan")],
|
|
541
|
+
) -> dict[str, Any]:
|
|
542
|
+
"""Queue a completed script or voiceover job, or a plan job whose plan is locked, as a full video on the same id. Poll get_job until completed. Do not create a second job with the script or audio."""
|
|
543
|
+
try:
|
|
544
|
+
return _client().continue_job(job_id)
|
|
545
|
+
except Exception as exc:
|
|
546
|
+
return _err(exc)
|
|
547
|
+
|
|
548
|
+
@mcp.tool(title="Create agent-planned job")
|
|
549
|
+
def create_plan_job(
|
|
550
|
+
template_id: Annotated[str, Field(min_length=8, description="Saved Faceless Documentary, Faceless Top 10, Avatar Video or Vector Explainer template UUID")],
|
|
551
|
+
title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
|
|
552
|
+
prompt: Annotated[str | None, Field(description="Topic/brief; Cliptude writes the narration. Never the video title.")] = None,
|
|
553
|
+
script: Annotated[str | None, Field(description="Spoken narration to voice as-is. Omit prompt when you pass this.")] = 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,
|
|
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,
|
|
588
|
+
) -> dict[str, Any]:
|
|
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."""
|
|
590
|
+
try:
|
|
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."}
|
|
593
|
+
return _client().create_job(
|
|
594
|
+
template_id=template_id,
|
|
595
|
+
title=title,
|
|
596
|
+
prompt=prompt,
|
|
597
|
+
script=script,
|
|
598
|
+
voiceover_path=voiceover_path,
|
|
599
|
+
voiceover_url=(voiceover_url or "").strip() or None,
|
|
600
|
+
duration=duration,
|
|
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,
|
|
187
608
|
)
|
|
188
609
|
except Exception as exc:
|
|
189
610
|
return _err(exc)
|
|
190
611
|
|
|
191
612
|
@mcp.tool(
|
|
192
|
-
title="Get
|
|
613
|
+
title="Get narration",
|
|
193
614
|
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
194
615
|
)
|
|
195
|
-
def
|
|
196
|
-
job_id: Annotated[str, Field(min_length=8, description="
|
|
616
|
+
def get_narration(
|
|
617
|
+
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
|
|
197
618
|
) -> dict[str, Any]:
|
|
198
|
-
"""
|
|
619
|
+
"""The narration you plan against: numbered sentences with start/end seconds and every word's timing, narration_digest (copy it into the plan), suggested chapters, the template's theme and switched-off graphics, and pricing (website price, already charged, due at continue)."""
|
|
199
620
|
try:
|
|
200
|
-
return _client().
|
|
621
|
+
return _client().get_narration(job_id)
|
|
201
622
|
except Exception as exc:
|
|
202
623
|
return _err(exc)
|
|
203
624
|
|
|
204
625
|
@mcp.tool(
|
|
205
|
-
title="
|
|
626
|
+
title="Get graphics catalog",
|
|
206
627
|
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
207
628
|
)
|
|
208
|
-
def
|
|
209
|
-
|
|
629
|
+
def get_kind_catalog(
|
|
630
|
+
format: Annotated[str | None, Field(description="faceless_documentary, faceless_top_10, avatar_video or vector_explainer")] = None,
|
|
631
|
+
theme: Annotated[str | None, Field(description="Visual theme, to mark graphics the theme does not use")] = None,
|
|
632
|
+
compact: Annotated[bool, Field(description="One summary line per graphic (start here; the full catalog is large)")] = True,
|
|
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,
|
|
634
|
+
premium: Annotated[bool, Field(description="Only the premium boards (marked premium: true)")] = False,
|
|
210
635
|
) -> dict[str, Any]:
|
|
211
|
-
"""
|
|
636
|
+
"""Every motion graphic Cliptude can render: planner kinds, ~360 animation types and 20 overlay text styles. Read compact first, then fetch full entries for the types you intend to use: their props, media slots, hold times, caps and preview video. Entries marked `premium: true` are the premium boards (newest designs, each with its own timed sound cues); premium=true lists only those. Also lists `transitions` (slugs for beats[].transition_in), `reveal_styles` (beats[].reveal_next, with preview videos) and `sounds` (ids for graphic sound, transition_sound, reveal_sound and sfx, with a preview link to each file)."""
|
|
212
637
|
try:
|
|
213
|
-
return _client().
|
|
638
|
+
return _client().get_kind_catalog(format=format, theme=theme, compact=compact and not types, types=types, premium=premium)
|
|
214
639
|
except Exception as exc:
|
|
215
640
|
return _err(exc)
|
|
216
641
|
|
|
217
|
-
@mcp.tool(
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
642
|
+
@mcp.tool(
|
|
643
|
+
title="Check plan",
|
|
644
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
645
|
+
)
|
|
646
|
+
def check_plan(
|
|
647
|
+
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
|
|
648
|
+
plan: Annotated[dict[str, Any], Field(description="The cliptude.plan/v1 plan object (see the cliptude-plan skill)")],
|
|
649
|
+
) -> dict[str, Any]:
|
|
650
|
+
"""Validate a plan without storing it. Free, no LLM, up to 60 a minute. Returns valid, errors (each with path, code, message, hint), warnings, a scorecard against the reference targets, and the cost due at continue. Fix every error and check again; warnings are advice."""
|
|
651
|
+
try:
|
|
652
|
+
return _client().put_plan(job_id, plan, dry_run=True)
|
|
653
|
+
except Exception as exc:
|
|
654
|
+
return _err(exc)
|
|
655
|
+
|
|
656
|
+
@mcp.tool(title="Lock plan")
|
|
657
|
+
def lock_plan(
|
|
658
|
+
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
|
|
659
|
+
plan: Annotated[dict[str, Any], Field(description="The plan that check_plan reported valid")],
|
|
660
|
+
) -> dict[str, Any]:
|
|
661
|
+
"""Validate and store the plan, and apply its look (theme, colours, style, music) to the video. You may lock again to replace it until you call continue_job. Then call continue_job."""
|
|
662
|
+
try:
|
|
663
|
+
return _client().put_plan(job_id, plan, dry_run=False)
|
|
664
|
+
except Exception as exc:
|
|
665
|
+
return _err(exc)
|
|
666
|
+
|
|
667
|
+
@mcp.tool(
|
|
668
|
+
title="Get locked plan",
|
|
669
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
670
|
+
)
|
|
671
|
+
def get_plan(
|
|
672
|
+
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID")],
|
|
673
|
+
) -> dict[str, Any]:
|
|
674
|
+
"""The locked plan, its hash and when it was locked."""
|
|
675
|
+
try:
|
|
676
|
+
return _client().get_plan(job_id)
|
|
677
|
+
except Exception as exc:
|
|
678
|
+
return _err(exc)
|
|
679
|
+
|
|
680
|
+
@mcp.tool(
|
|
681
|
+
title="Review the built video",
|
|
682
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
683
|
+
)
|
|
684
|
+
def get_plan_review(
|
|
685
|
+
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status ready_for_edit)")],
|
|
686
|
+
) -> dict[str, Any]:
|
|
687
|
+
"""What the built design shows, before any render: every picture/clip in order (beat, time, the sentence under it, what you asked for, what was used, a link to the file) and every graphic (time on screen and the props it will be drawn with, or why it is missing). Review this, revise with check_plan/lock_plan + continue_job on the same job if needed, then render_project once."""
|
|
688
|
+
try:
|
|
689
|
+
return _client().get_plan_review(job_id)
|
|
690
|
+
except Exception as exc:
|
|
691
|
+
return _err(exc)
|
|
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
|
+
|
|
710
|
+
@mcp.tool(
|
|
711
|
+
title="Get plan sourcing report",
|
|
712
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
713
|
+
)
|
|
714
|
+
def get_plan_report(
|
|
715
|
+
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (after continue_job)")],
|
|
716
|
+
) -> dict[str, Any]:
|
|
717
|
+
"""For each media request in your plan (beat footage, graphic pictures): what was used (source, query, file) or the fallback and why, plus graphics planned vs rendered. Available once the design is built."""
|
|
718
|
+
try:
|
|
719
|
+
return _client().get_plan_report(job_id)
|
|
720
|
+
except Exception as exc:
|
|
721
|
+
return _err(exc)
|
|
722
|
+
|
|
723
|
+
@mcp.tool(
|
|
724
|
+
title="Get job",
|
|
725
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
726
|
+
)
|
|
727
|
+
def get_job(
|
|
728
|
+
job_id: Annotated[str, Field(min_length=8, description="Job / video UUID")],
|
|
221
729
|
) -> dict[str, Any]:
|
|
222
|
-
"""
|
|
730
|
+
"""Job status, progress, error, output url (SaaS) or path (Desktop), and script / voiceover when this was a partial job. can_continue is true when continue_job can turn it into a video."""
|
|
223
731
|
try:
|
|
224
|
-
return _client().
|
|
732
|
+
return _client().get_job(job_id)
|
|
225
733
|
except Exception as exc:
|
|
226
734
|
return _err(exc)
|
|
227
735
|
|
|
@@ -253,6 +761,98 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
253
761
|
except Exception as exc:
|
|
254
762
|
return _err(exc)
|
|
255
763
|
|
|
764
|
+
@mcp.tool(
|
|
765
|
+
title="Open editor project",
|
|
766
|
+
annotations=ToolAnnotations(read_only_hint=False, open_world_hint=False),
|
|
767
|
+
)
|
|
768
|
+
def open_editor_project(
|
|
769
|
+
job_id: Annotated[str, Field(min_length=8, description="Completed video job id")],
|
|
770
|
+
) -> dict[str, Any]:
|
|
771
|
+
"""Open (or create) the timeline editor project for a completed video job. Returns project id, revision and a compact timeline (item id, type, start_s, end_s, text) to reference in run_agent."""
|
|
772
|
+
try:
|
|
773
|
+
return _client().open_editor_project(job_id)
|
|
774
|
+
except Exception as exc:
|
|
775
|
+
return _err(exc)
|
|
776
|
+
|
|
777
|
+
@mcp.tool(
|
|
778
|
+
title="Get editor project",
|
|
779
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
780
|
+
)
|
|
781
|
+
def get_editor_project(
|
|
782
|
+
project_id: Annotated[int, Field(description="Editor project id")],
|
|
783
|
+
) -> dict[str, Any]:
|
|
784
|
+
"""Current revision, compact timeline and latest render of an editor project."""
|
|
785
|
+
try:
|
|
786
|
+
return _client().get_editor_project(project_id)
|
|
787
|
+
except Exception as exc:
|
|
788
|
+
return _err(exc)
|
|
789
|
+
|
|
790
|
+
@mcp.tool(title="Run Cliptude Agent")
|
|
791
|
+
def run_agent(
|
|
792
|
+
project_id: Annotated[int, Field(description="Editor project id")],
|
|
793
|
+
prompt: Annotated[str, Field(min_length=1, description="Edit request in plain English")],
|
|
794
|
+
referenced_item_ids: Annotated[
|
|
795
|
+
list[str] | None, Field(description="Timeline item ids the request is about (from the timeline listing)")
|
|
796
|
+
] = None,
|
|
797
|
+
tier: Annotated[str, Field(description="fast or smart")] = "fast",
|
|
798
|
+
chat_id: Annotated[str | None, Field(description="Continue an existing agent chat")] = None,
|
|
799
|
+
) -> dict[str, Any]:
|
|
800
|
+
"""Ask Cliptude Agent to edit the timeline (swap footage, regenerate images or voiceover ranges, music, transitions, text). Returns a run; poll get_agent_run. Charges agent credits. Then render_project for a new MP4."""
|
|
801
|
+
try:
|
|
802
|
+
return _client().run_agent(
|
|
803
|
+
project_id, prompt=prompt, tier=tier, referenced_item_ids=referenced_item_ids, chat_id=chat_id
|
|
804
|
+
)
|
|
805
|
+
except Exception as exc:
|
|
806
|
+
return _err(exc)
|
|
807
|
+
|
|
808
|
+
@mcp.tool(
|
|
809
|
+
title="Get agent run",
|
|
810
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
811
|
+
)
|
|
812
|
+
def get_agent_run(
|
|
813
|
+
project_id: Annotated[int, Field(description="Editor project id")],
|
|
814
|
+
run_id: Annotated[str, Field(min_length=8, description="Agent run id")],
|
|
815
|
+
) -> dict[str, Any]:
|
|
816
|
+
"""Status of a Cliptude Agent run plus the agent's messages."""
|
|
817
|
+
try:
|
|
818
|
+
return _client().get_agent_run(project_id, run_id)
|
|
819
|
+
except Exception as exc:
|
|
820
|
+
return _err(exc)
|
|
821
|
+
|
|
822
|
+
@mcp.tool(title="Cancel agent run")
|
|
823
|
+
def cancel_agent_run(
|
|
824
|
+
project_id: Annotated[int, Field(description="Editor project id")],
|
|
825
|
+
run_id: Annotated[str, Field(min_length=8, description="Agent run id")],
|
|
826
|
+
) -> dict[str, Any]:
|
|
827
|
+
"""Cancel a queued or running Cliptude Agent run."""
|
|
828
|
+
try:
|
|
829
|
+
return _client().cancel_agent_run(project_id, run_id)
|
|
830
|
+
except Exception as exc:
|
|
831
|
+
return _err(exc)
|
|
832
|
+
|
|
833
|
+
@mcp.tool(title="Render editor project")
|
|
834
|
+
def render_project(
|
|
835
|
+
project_id: Annotated[int, Field(description="Editor project id")],
|
|
836
|
+
) -> dict[str, Any]:
|
|
837
|
+
"""Render the edited timeline to a new MP4 (charged like an editor export). Poll get_render for output_url."""
|
|
838
|
+
try:
|
|
839
|
+
return _client().render_project(project_id)
|
|
840
|
+
except Exception as exc:
|
|
841
|
+
return _err(exc)
|
|
842
|
+
|
|
843
|
+
@mcp.tool(
|
|
844
|
+
title="Get render",
|
|
845
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
846
|
+
)
|
|
847
|
+
def get_render(
|
|
848
|
+
render_id: Annotated[int, Field(description="Editor render id")],
|
|
849
|
+
) -> dict[str, Any]:
|
|
850
|
+
"""Status of an editor render; output_url when completed."""
|
|
851
|
+
try:
|
|
852
|
+
return _client().get_render(render_id)
|
|
853
|
+
except Exception as exc:
|
|
854
|
+
return _err(exc)
|
|
855
|
+
|
|
256
856
|
@mcp.tool(
|
|
257
857
|
title="Get account",
|
|
258
858
|
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
@@ -285,9 +885,11 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
285
885
|
"""Use a saved Cliptude template to generate a video from a topic or a custom script."""
|
|
286
886
|
return (
|
|
287
887
|
"List my Cliptude templates, pick the one I name, then create_job "
|
|
288
|
-
"with title plus prompt (topic), script (full narration),
|
|
289
|
-
"voiceover_path (local audio file)
|
|
290
|
-
"
|
|
888
|
+
"with title plus prompt (topic), script (full narration), "
|
|
889
|
+
"voiceover_path (local audio file), or talking_head_path "
|
|
890
|
+
"(presenter video on a Talking Head template). Poll get_job. "
|
|
891
|
+
"Avatar Video templates expose avatar_intro_only and avatar_ai_footage; "
|
|
892
|
+
"pass them on create_job to override the template."
|
|
291
893
|
)
|
|
292
894
|
|
|
293
895
|
return mcp
|