@cliptude/cli 0.1.46 → 0.1.51

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.
@@ -173,6 +173,13 @@ def _uuid_seg(value: Any, label: str = "job_id") -> str:
173
173
  return quote(canonical, safe="")
174
174
 
175
175
 
176
+ def _voice_provider(provider: str) -> str:
177
+ value = str(provider or "").strip().lower()
178
+ if value not in ("elevenlabs", "minimax", "inworld"):
179
+ raise CliptudeApiError("provider must be elevenlabs, minimax or inworld.")
180
+ return value
181
+
182
+
176
183
  def _int_seg(value: Any, label: str = "project_id") -> str:
177
184
  """A positive integer path segment; anything else is refused."""
178
185
  text = str(value).strip() if not isinstance(value, bool) else ""
@@ -298,6 +305,15 @@ def _avatar_job_fields(
298
305
  return fields
299
306
 
300
307
 
308
+ def merge_visual_direction(prompt: str | None, visual_direction: str | None) -> str | None:
309
+ """The prompt with the deprecated visual_direction appended (the server does the same for direct API calls)."""
310
+ notes = (visual_direction or "").strip()
311
+ text = (prompt or "").strip()
312
+ if notes and notes not in text:
313
+ text = f"{text}\n\n{notes}".strip() if text else notes
314
+ return text or None
315
+
316
+
301
317
  def _review_job_fields(review_token: str | None, acknowledge: list[str] | None, review_only: bool | None,
302
318
  *, as_strings: bool = False) -> dict[str, Any]:
303
319
  """The job review: Cliptude answers a job without a review_token with the review (HTTP 428)."""
@@ -476,9 +492,16 @@ class CliptudeClient:
476
492
  return self.request("GET", f"/api/v1/templates/{_uuid_seg(template_id, 'template_id')}")
477
493
 
478
494
  def create_template(self, *, name: str, format: str, settings: dict[str, Any],
479
- brand_kit_id: int | None = None, show_logo: bool | None = None) -> Any:
480
- """Create a ready-to-use template from settings (no create wizard); optional brand kit and logo."""
495
+ brand_kit_id: int | None = None, show_logo: bool | None = None,
496
+ look: str | None = None, captions: bool | None = None) -> Any:
497
+ """Create a ready-to-use template from settings (no create wizard); optional brand kit, logo, Look and
498
+ whole-video captions (off by default)."""
499
+ settings = dict(settings or {})
500
+ if captions is not None:
501
+ settings["captions_enabled"] = bool(captions)
481
502
  body: dict[str, Any] = {"name": name, "format": format, "settings": settings}
503
+ if look:
504
+ body["look"] = look
482
505
  if brand_kit_id is not None:
483
506
  body["brand_kit_id"] = brand_kit_id or None
484
507
  if show_logo is not None:
@@ -486,9 +509,15 @@ class CliptudeClient:
486
509
  return self.request("POST", "/api/v1/templates", json_body=body)
487
510
 
488
511
  def update_template(self, template_id: str, *, name: str | None = None, brand_kit_id: int | None = None,
489
- show_logo: bool | None = None) -> Any:
490
- """Rename a template, set its brand kit (0 = the user's default kit) or turn its logo on or off."""
512
+ show_logo: bool | None = None, look: str | None = None,
513
+ captions: bool | None = None) -> Any:
514
+ """Rename a template, set its brand kit (0 = the user's default kit), its logo switch, its Look
515
+ ('' removes the Look) or its whole-video captions."""
491
516
  body: dict[str, Any] = {}
517
+ if captions is not None:
518
+ body["captions"] = bool(captions)
519
+ if look is not None:
520
+ body["look"] = look
492
521
  if name is not None:
493
522
  body["name"] = name
494
523
  if brand_kit_id is not None:
@@ -497,6 +526,27 @@ class CliptudeClient:
497
526
  body["show_logo"] = bool(show_logo)
498
527
  return self.request("PATCH", f"/api/v1/templates/{_uuid_seg(template_id, 'template_id')}", json_body=body)
499
528
 
529
+ def list_looks(self, topic: str | None = None, format: str | None = None) -> Any:
530
+ """The prebuilt Looks (colours, captions, footage grade, the boards that carry each), with sample reels.
531
+ With ``topic`` the best fits come first with ``suggested: true`` and a ``reason``; ``format`` limits them."""
532
+ params: dict[str, Any] = {}
533
+ if topic and topic.strip():
534
+ params["topic"] = topic.strip()[:2000]
535
+ if format:
536
+ params["format"] = format
537
+ return self.request("GET", "/api/v1/looks", params=params or None)
538
+
539
+ def save_look_as_template(self, slug: str, *, name: str | None = None, format: str | None = None) -> Any:
540
+ """Copy a Look into one of the user's templates (format: any of the Look's formats); returns the template."""
541
+ body: dict[str, Any] = {}
542
+ if name:
543
+ body["name"] = name
544
+ if format:
545
+ body["format"] = format
546
+ from urllib.parse import quote
547
+
548
+ return self.request("POST", f"/api/v1/looks/{quote(slug.strip(), safe='')}/template", json_body=body)
549
+
500
550
  def list_brand_kits(self) -> Any:
501
551
  """The user's brand kits (one per channel): logo, colours, fonts; one is the default."""
502
552
  return self.request("GET", "/api/v1/brand-kits")
@@ -511,6 +561,53 @@ class CliptudeClient:
511
561
  params["kind"] = kind
512
562
  return self.request("GET", "/api/v1/media", params=params)
513
563
 
564
+ # --- designed voices (ElevenLabs, MiniMax, Inworld; settings, try and remix are ElevenLabs only) -----------
565
+
566
+ def voice_design_options(self) -> Any:
567
+ """Design models, option ranges and defaults, and the voice settings ranges (the web page's)."""
568
+ return self.request("GET", "/api/v1/voice-designs/options")
569
+
570
+ def design_voice_previews(self, provider: str, description: str, *, language: str | None = None,
571
+ options: dict[str, Any] | None = None) -> Any:
572
+ body = {"description": description, **({"language": language} if language else {}),
573
+ **{k: v for k, v in (options or {}).items() if v is not None}}
574
+ return self.request("POST", f"/api/v1/voice-designs/{_voice_provider(provider)}/previews", json_body=body,
575
+ timeout=max(self.timeout, 180.0))
576
+
577
+ def save_designed_voice(self, provider: str, preview_id: str, voice_name: str, *,
578
+ voice_settings: dict[str, Any] | None = None) -> Any:
579
+ body = {"preview_id": preview_id, "voice_name": voice_name,
580
+ **{k: v for k, v in (voice_settings or {}).items() if v is not None}}
581
+ return self.request("POST", f"/api/v1/voice-designs/{_voice_provider(provider)}", json_body=body,
582
+ timeout=max(self.timeout, 120.0))
583
+
584
+ def update_designed_voice_settings(self, design_id: int | str, voice_settings: dict[str, Any]) -> Any:
585
+ body = {k: v for k, v in (voice_settings or {}).items() if v is not None}
586
+ return self.request("POST", f"/api/v1/voice-designs/elevenlabs/{_int_seg(design_id, 'design_id')}/settings",
587
+ json_body=body)
588
+
589
+ def try_designed_voice(self, design_id: int | str, *, text: str | None = None,
590
+ voice_settings: dict[str, Any] | None = None, **extra: Any) -> Any:
591
+ body = {**({"text": text} if text else {}), **{k: v for k, v in (voice_settings or {}).items() if v is not None},
592
+ **{k: v for k, v in extra.items() if v not in (None, "")}}
593
+ return self.request("POST", f"/api/v1/voice-designs/elevenlabs/{_int_seg(design_id, 'design_id')}/try",
594
+ json_body=body)
595
+
596
+ def remix_designed_voice(self, design_id: int | str, description: str, *,
597
+ options: dict[str, Any] | None = None) -> Any:
598
+ body = {"description": description, **{k: v for k, v in (options or {}).items() if v is not None}}
599
+ return self.request("POST", f"/api/v1/voice-designs/elevenlabs/{_int_seg(design_id, 'design_id')}/remix",
600
+ json_body=body, timeout=max(self.timeout, 180.0))
601
+
602
+ def save_remixed_voice(self, design_id: int | str, preview_id: str, *, voice_name: str | None = None) -> Any:
603
+ body = {"preview_id": preview_id, **({"voice_name": voice_name} if voice_name else {})}
604
+ return self.request("POST", f"/api/v1/voice-designs/elevenlabs/{_int_seg(design_id, 'design_id')}/remix/save",
605
+ json_body=body, timeout=max(self.timeout, 120.0))
606
+
607
+ def delete_designed_voice(self, provider: str, design_id: int | str) -> Any:
608
+ return self.request("DELETE", f"/api/v1/voice-designs/{_voice_provider(provider)}/"
609
+ f"{_int_seg(design_id, 'design_id')}")
610
+
514
611
  def template_options(self, format: str) -> Any:
515
612
  return self.request("GET", "/api/v1/templates/options", params={"format": format})
516
613
 
@@ -548,12 +645,19 @@ class CliptudeClient:
548
645
  vector_character_id: str | None = None,
549
646
  vector_reveal_mode: str | None = None,
550
647
  pronunciations: list[dict[str, str]] | None = None,
648
+ visual_direction: str | None = None,
649
+ captions: bool | None = None,
650
+ look: str | None = None,
551
651
  review_token: str | None = None,
552
652
  acknowledge: list[str] | None = None,
553
653
  review_only: bool | None = None,
554
654
  ) -> Any:
555
655
  if voiceover_path and voiceover_url:
556
656
  raise CliptudeApiError("Give voiceover_path or voiceover_url, not both.")
657
+ # visual_direction is deprecated: the description (prompt) carries the visual direction. Older callers still
658
+ # send it, so it is appended to the prompt here, the same on every path (JSON, voiceover upload, talking head).
659
+ prompt = merge_visual_direction(prompt, visual_direction)
660
+ visual_direction = None
557
661
  if render_only and ((output or "").strip().lower() != "plan" or not (voiceover_path or voiceover_url)):
558
662
  raise CliptudeApiError(
559
663
  "render_only is a plan job with your own narration: pass output=\"plan\" and a voiceover "
@@ -592,21 +696,23 @@ class CliptudeClient:
592
696
  )
593
697
  if th_path and vo_path:
594
698
  raise CliptudeApiError("Upload either a talking head video or a voiceover — not both.")
595
- if th_path and (prompt or script):
699
+ # A prompt may come with any narration as direction for the visuals; two narrations may not.
700
+ if th_path and script:
596
701
  raise CliptudeApiError(
597
- "Upload a talking head video, or send a prompt / custom script — not both. "
598
- "An uploaded talking head is transcribed and used as the narration."
702
+ "Upload a talking head video, or send a custom script — not both. "
703
+ "An uploaded talking head is transcribed and used as the narration; a prompt is fine as direction."
599
704
  )
600
- if vo_path and (prompt or script):
705
+ if (vo_path or voiceover_url) and script:
601
706
  raise CliptudeApiError(
602
- "Upload a voiceover, or send a prompt / custom script — not both. "
603
- "An uploaded file is transcribed and used as the narration."
707
+ "Upload a voiceover, or send a custom script — not both. "
708
+ "An uploaded file is transcribed and used as the narration; a prompt is fine as direction."
604
709
  )
605
710
  if th_path:
606
711
  return self._create_job_talking_head(
607
712
  template_id=template_id,
608
713
  title=title,
609
714
  talking_head_path=th_path,
715
+ prompt=prompt,
610
716
  avatar_intro_only=avatar_intro_only,
611
717
  avatar_ai_footage=avatar_ai_footage,
612
718
  disable_animations=disable_animations,
@@ -617,6 +723,8 @@ class CliptudeClient:
617
723
  excluded_animation_types=excluded_animation_types,
618
724
  excluded_transition_kinds=excluded_transition_kinds,
619
725
  thumbnail=thumbnail,
726
+ captions=captions,
727
+ look=look,
620
728
  review=_review_job_fields(review_token, acknowledge, review_only),
621
729
  )
622
730
  if vo_path:
@@ -632,6 +740,10 @@ class CliptudeClient:
632
740
  **({"vector_character_id": str(vector_character_id)} if vector_character_id else {}),
633
741
  **({"vector_reveal_mode": str(vector_reveal_mode)} if vector_reveal_mode else {}),
634
742
  **({"pronunciations": json.dumps(pronunciations)} if pronunciations is not None else {}),
743
+ **({"visual_direction": visual_direction} if visual_direction else {}),
744
+ **({"captions": "true" if captions else "false"} if captions is not None else {}),
745
+ **({"look": str(look).strip() or "none"} if look is not None else {}),
746
+ **({"prompt": prompt} if prompt else {}),
635
747
  **_review_job_fields(review_token, acknowledge, review_only, as_strings=True),
636
748
  }
637
749
  return self._create_job_multipart(
@@ -669,6 +781,12 @@ class CliptudeClient:
669
781
  body["vector_reveal_mode"] = str(vector_reveal_mode)
670
782
  if pronunciations is not None:
671
783
  body["pronunciations"] = pronunciations
784
+ if visual_direction:
785
+ body["visual_direction"] = visual_direction
786
+ if captions is not None:
787
+ body["captions"] = bool(captions)
788
+ if look is not None:
789
+ body["look"] = str(look).strip()
672
790
  body.update(_review_job_fields(review_token, acknowledge, review_only))
673
791
  return self.request("POST", "/api/v1/jobs", json_body=body)
674
792
 
@@ -757,6 +875,7 @@ class CliptudeClient:
757
875
  template_id: str,
758
876
  title: str,
759
877
  talking_head_path: str | Path,
878
+ prompt: str | None = None,
760
879
  avatar_intro_only: bool | None = None,
761
880
  avatar_ai_footage: bool | None = None,
762
881
  disable_animations: bool | None = None,
@@ -767,9 +886,17 @@ class CliptudeClient:
767
886
  excluded_animation_types: list[str] | None = None,
768
887
  excluded_transition_kinds: list[str] | None = None,
769
888
  thumbnail: dict[str, str] | None = None,
889
+ captions: bool | None = None,
890
+ look: str | None = None,
770
891
  review: dict[str, Any] | None = None,
771
892
  ) -> Any:
772
893
  review = review or {}
894
+ captions_field = {"captions": bool(captions)} if captions is not None else {}
895
+ captions_str = {"captions": "true" if captions else "false"} if captions is not None else {}
896
+ # The job's Look rides with captions on every talking-head path ("none" = no Look; multipart drops "").
897
+ if look is not None:
898
+ captions_field["look"] = str(look).strip()
899
+ captions_str["look"] = str(look).strip() or "none"
773
900
  review_strings = {k: (",".join(v) if isinstance(v, list) else ("true" if v is True else v))
774
901
  for k, v in review.items()}
775
902
  motion_extra = _motion_control_job_fields(
@@ -806,6 +933,8 @@ class CliptudeClient:
806
933
  **_avatar_job_fields(avatar_intro_only, avatar_ai_footage, as_strings=True),
807
934
  **motion_extra,
808
935
  **_thumbnail_job_field(thumbnail, as_string=True),
936
+ **({"prompt": prompt} if prompt else {}),
937
+ **captions_str,
809
938
  **review_strings,
810
939
  }
811
940
  return self._create_job_multipart(
@@ -825,6 +954,8 @@ class CliptudeClient:
825
954
  **_avatar_job_fields(avatar_intro_only, avatar_ai_footage, as_strings=True),
826
955
  **motion_extra,
827
956
  **_thumbnail_job_field(thumbnail, as_string=True),
957
+ **({"prompt": prompt} if prompt else {}),
958
+ **captions_str,
828
959
  **review_strings,
829
960
  }
830
961
  return self._create_job_multipart(
@@ -851,9 +982,11 @@ class CliptudeClient:
851
982
  "title": title,
852
983
  "talking_head_r2_key": key,
853
984
  "talking_head_duration": str(duration),
985
+ **({"prompt": prompt} if prompt else {}),
854
986
  }
855
987
  body.update(_avatar_job_fields(avatar_intro_only, avatar_ai_footage))
856
988
  body.update(_thumbnail_job_field(thumbnail))
989
+ body.update(captions_field)
857
990
  body.update(
858
991
  _motion_control_job_fields(
859
992
  disable_animations=disable_animations,
@@ -1314,9 +1447,15 @@ class CliptudeClient:
1314
1447
  avatar_engine: str | None = None,
1315
1448
  render_only: bool | None = None,
1316
1449
  vector_reveal_mode: str | None = None,
1450
+ captions: bool | None = None,
1451
+ look: str | None = None,
1317
1452
  ) -> Any:
1318
1453
  """Credits a job would need; creates nothing."""
1319
1454
  body: dict[str, Any] = {"template_id": template_id}
1455
+ if captions is not None:
1456
+ body["captions"] = bool(captions)
1457
+ if look is not None:
1458
+ body["look"] = str(look).strip()
1320
1459
  if render_only:
1321
1460
  body["render_only"] = True
1322
1461
  for key, value in (
@@ -1,5 +1,6 @@
1
1
  """MCP tools that make the user's own avatar and voices: create_avatar, design_voice_previews, save_designed_voice,
2
- clone_voice. The avatar and voice picker widgets call them with `tools/call`; the model can call them too.
2
+ voice_design_options, update_designed_voice_settings, try_designed_voice, remix_designed_voice, save_remixed_voice,
3
+ delete_designed_voice, clone_voice. The avatar and voice picker widgets call them with `tools/call`; the model can call them too.
3
4
 
4
5
  Files travel as base64 in the tool call (the widget reads the file the user picked, or a recording), never as a
5
6
  path on the hosted server: a local path is accepted only by the stdio server, which runs on the user's computer.
@@ -18,7 +19,7 @@ from pathlib import Path
18
19
  from typing import Annotated, Any
19
20
 
20
21
  import httpx
21
- from mcp.types import CallToolResult, TextContent, ToolAnnotations
22
+ from mcp.types import AudioContent, CallToolResult, TextContent, ToolAnnotations
22
23
  from pydantic import Field
23
24
 
24
25
  from cliptude_mcp.client import CliptudeApiError
@@ -95,6 +96,16 @@ def post_form(client: Any, path: str, data: dict[str, Any], files: dict[str, tup
95
96
  return payload
96
97
 
97
98
 
99
+ def _voice_settings(stability, similarity_boost, style, use_speaker_boost, speed) -> dict[str, Any]:
100
+ values = {"stability": stability, "similarity_boost": similarity_boost, "style": style,
101
+ "use_speaker_boost": use_speaker_boost, "speed": speed}
102
+ return {k: v for k, v in values.items() if v is not None}
103
+
104
+
105
+ def _form_values(values: dict[str, Any]) -> dict[str, Any]:
106
+ return {k: (("true" if v else "false") if isinstance(v, bool) else v) for k, v in values.items()}
107
+
108
+
98
109
  def register_creation_tools(
99
110
  mcp: Any, client: Callable[[], Any], err: Callable[[Exception], dict[str, Any]], *, local: bool
100
111
  ) -> None:
@@ -135,11 +146,24 @@ def register_creation_tools(
135
146
  provider: Annotated[str, Field(description="elevenlabs, minimax or inworld")],
136
147
  description: Annotated[str, Field(min_length=10, max_length=1000, description="The voice to design: age, gender, accent, tone, pace")],
137
148
  language: Annotated[str | None, Field(description="Narration language, e.g. English")] = None,
149
+ model_id: Annotated[str | None, Field(description="ElevenLabs only: eleven_multilingual_ttv_v2 (default) or eleven_ttv_v3 (voice_design_options lists them)")] = None,
150
+ should_enhance: Annotated[bool | None, Field(description="ElevenLabs only: let ElevenLabs expand the description")] = None,
151
+ text: Annotated[str | None, Field(description="ElevenLabs only: the preview line, 100-1000 characters")] = None,
152
+ auto_generate_text: Annotated[bool | None, Field(description="ElevenLabs only: ElevenLabs writes the preview line")] = None,
153
+ loudness: Annotated[float | None, Field(description="ElevenLabs only: -1 to 1 (default 0.5)")] = None,
154
+ guidance_scale: Annotated[float | None, Field(description="ElevenLabs only: how closely to follow the description, 0 to 20 (default 5)")] = None,
155
+ quality: Annotated[float | None, Field(description="ElevenLabs v2 only: -1 to 1, higher = better, less variety")] = None,
156
+ seed: Annotated[int | None, Field(description="ElevenLabs only: a whole number for repeatable previews")] = None,
157
+ prompt_strength: Annotated[float | None, Field(description="ElevenLabs v3 with reference audio only: 0 to 1")] = None,
138
158
  ) -> CallToolResult:
139
- """Design a new narration voice from a description: returns a few previews (preview_id) to listen to. Keep one with save_designed_voice. Paid plans; a user keeps one designed voice per provider. The audio goes to the voice picker widget only; the text result lists the preview ids."""
159
+ """Design a new narration voice from a description: returns a few previews (preview_id) to listen to. Keep one with save_designed_voice. Paid plans; a user keeps one designed voice per provider. ElevenLabs takes the web page's design options (model_id, guidance_scale, loudness, ...; voice_design_options lists ranges and defaults; numbers outside a range are clamped). The audio goes to the voice picker widget only; the text result lists the preview ids."""
160
+ options = {"model_id": model_id, "should_enhance": should_enhance, "text": text,
161
+ "auto_generate_text": auto_generate_text, "loudness": loudness, "guidance_scale": guidance_scale,
162
+ "quality": quality, "seed": seed, "prompt_strength": prompt_strength}
163
+ form = {k: (("true" if v else "false") if isinstance(v, bool) else v) for k, v in options.items() if v is not None}
140
164
  try:
141
165
  payload = post_form(client(), f"/api/v1/voice-designs/{provider.strip().lower()}/previews",
142
- {"description": description, "language": language})
166
+ {"description": description, "language": language, **form})
143
167
  except Exception as exc:
144
168
  failure = err(exc)
145
169
  return CallToolResult(content=[TextContent(type="text", text=json.dumps(failure, default=str))],
@@ -166,11 +190,140 @@ def register_creation_tools(
166
190
  provider: Annotated[str, Field(description="Same provider as the previews")],
167
191
  preview_id: Annotated[str, Field(min_length=1, description="The preview the user picked")],
168
192
  voice_name: Annotated[str, Field(min_length=1, max_length=100, description="Name for the voice")],
193
+ stability: Annotated[float | None, Field(description="ElevenLabs voice setting, 0 to 1 (default 0.5)")] = None,
194
+ similarity_boost: Annotated[float | None, Field(description="ElevenLabs voice setting, 0 to 1 (default 0.75)")] = None,
195
+ style: Annotated[float | None, Field(description="ElevenLabs voice setting, 0 to 1 (default 0)")] = None,
196
+ use_speaker_boost: Annotated[bool | None, Field(description="ElevenLabs voice setting (default true)")] = None,
197
+ speed: Annotated[float | None, Field(description="ElevenLabs voice setting, 0.7 to 1.2 (default 1)")] = None,
169
198
  ) -> dict[str, Any]:
170
- """Keep one designed preview as the user's own private voice. It then appears in list_voices under my_voices and can be used as voice_id (with voice_provider) in create_template."""
199
+ """Keep one designed preview as the user's own private voice. It then appears in list_voices under my_voices (with design_id and voice_settings) and can be used as voice_id (with voice_provider) in create_template. ElevenLabs voices may get their voice settings now (or later with update_designed_voice_settings); settings left out keep the ElevenLabs default."""
200
+ settings = _voice_settings(stability, similarity_boost, style, use_speaker_boost, speed)
171
201
  try:
172
202
  return post_form(client(), f"/api/v1/voice-designs/{provider.strip().lower()}",
173
- {"preview_id": preview_id, "voice_name": voice_name})
203
+ {"preview_id": preview_id, "voice_name": voice_name, **_form_values(settings)})
204
+ except Exception as exc:
205
+ return err(exc)
206
+
207
+ @mcp.tool(
208
+ title="Voice design options",
209
+ annotations=ToolAnnotations(title="Voice design options", read_only_hint=True, open_world_hint=False),
210
+ )
211
+ def voice_design_options() -> dict[str, Any]:
212
+ """What design_voice_previews, remix_designed_voice and the voice settings accept: ElevenLabs design models, every option's range and default, and the voice settings ranges (the same as the Design a voice page; out-of-range numbers are clamped)."""
213
+ try:
214
+ return client().voice_design_options()
215
+ except Exception as exc:
216
+ return err(exc)
217
+
218
+ @mcp.tool(
219
+ title="Update designed voice settings",
220
+ annotations=ToolAnnotations(title="Update designed voice settings", read_only_hint=False,
221
+ destructive_hint=False, idempotent_hint=True, open_world_hint=True),
222
+ )
223
+ def update_designed_voice_settings(
224
+ design_id: Annotated[int, Field(description="design_id of the user's designed ElevenLabs voice (list_voices my_voices)")],
225
+ stability: Annotated[float | None, Field(description="0 to 1")] = None,
226
+ similarity_boost: Annotated[float | None, Field(description="0 to 1")] = None,
227
+ style: Annotated[float | None, Field(description="0 to 1")] = None,
228
+ use_speaker_boost: Annotated[bool | None, Field(description="true or false")] = None,
229
+ speed: Annotated[float | None, Field(description="0.7 to 1.2")] = None,
230
+ ) -> dict[str, Any]:
231
+ """Change the voice settings of the user's designed ElevenLabs voice; settings left out keep their saved value. Every video voiced with it uses them. Returns voice_settings."""
232
+ try:
233
+ return client().update_designed_voice_settings(
234
+ design_id, _voice_settings(stability, similarity_boost, style, use_speaker_boost, speed))
235
+ except Exception as exc:
236
+ return err(exc)
237
+
238
+ @mcp.tool(
239
+ title="Try designed voice",
240
+ annotations=ToolAnnotations(title="Try designed voice", read_only_hint=True, open_world_hint=True),
241
+ )
242
+ def try_designed_voice(
243
+ design_id: Annotated[int, Field(description="design_id of the user's designed ElevenLabs voice")],
244
+ text: Annotated[str | None, Field(max_length=300, description="A short line to speak (default: a sample line)")] = None,
245
+ stability: Annotated[float | None, Field(description="0 to 1; omit to use the saved setting")] = None,
246
+ similarity_boost: Annotated[float | None, Field(description="0 to 1")] = None,
247
+ style: Annotated[float | None, Field(description="0 to 1")] = None,
248
+ use_speaker_boost: Annotated[bool | None, Field(description="true or false")] = None,
249
+ speed: Annotated[float | None, Field(description="0.7 to 1.2")] = None,
250
+ model_id: Annotated[str | None, Field(description="ElevenLabs TTS model id; omit for the default")] = None,
251
+ language_code: Annotated[str | None, Field(description="Two-letter language code, e.g. en")] = None,
252
+ ) -> CallToolResult:
253
+ """Speak a short test line in the user's designed ElevenLabs voice with these settings (nothing is saved; daily limit). The result carries the audio for the user to play; the text part says how many tries are left."""
254
+ try:
255
+ payload = client().try_designed_voice(
256
+ design_id, text=text,
257
+ voice_settings=_voice_settings(stability, similarity_boost, style, use_speaker_boost, speed),
258
+ model_id=model_id, language_code=language_code)
259
+ except Exception as exc:
260
+ failure = err(exc)
261
+ return CallToolResult(content=[TextContent(type="text", text=json.dumps(failure, default=str))],
262
+ structured_content=failure)
263
+ payload = payload if isinstance(payload, dict) else {}
264
+ audio_url = str(payload.get("audio_url") or "")
265
+ summary = {"tries_left_today": payload.get("tries_left_today"),
266
+ "next": "Let the user listen; when they like the settings, update_designed_voice_settings."}
267
+ content: list[Any] = [TextContent(type="text", text=json.dumps(summary))]
268
+ if audio_url.startswith("data:") and ";base64," in audio_url:
269
+ mime, data = audio_url[5:].split(";base64,", 1)
270
+ content.append(AudioContent(type="audio", data=data, mime_type=mime or "audio/mpeg"))
271
+ return CallToolResult(content=content, structured_content=summary)
272
+
273
+ @mcp.tool(
274
+ title="Remix designed voice",
275
+ annotations=ToolAnnotations(title="Remix designed voice", read_only_hint=False, destructive_hint=False,
276
+ open_world_hint=True),
277
+ )
278
+ def remix_designed_voice(
279
+ design_id: Annotated[int, Field(description="design_id of the user's designed ElevenLabs voice")],
280
+ description: Annotated[str, Field(min_length=5, max_length=1000, description="The change, e.g. 'a little warmer and slower'")],
281
+ guidance_scale: Annotated[float | None, Field(description="0 to 20 (default 2)")] = None,
282
+ loudness: Annotated[float | None, Field(description="-1 to 1 (default 0.5)")] = None,
283
+ text: Annotated[str | None, Field(description="Preview line, 100-1000 characters")] = None,
284
+ seed: Annotated[int | None, Field(description="A whole number for repeatable previews")] = None,
285
+ ) -> dict[str, Any]:
286
+ """Previews of the user's designed ElevenLabs voice with a change. Keep one with save_remixed_voice (it replaces the voice and keeps its settings). Shares the daily design-round limit."""
287
+ try:
288
+ payload = client().remix_designed_voice(design_id, description, options={
289
+ "guidance_scale": guidance_scale, "loudness": loudness, "text": text, "seed": seed})
290
+ except Exception as exc:
291
+ return err(exc)
292
+ if isinstance(payload, dict):
293
+ return {**payload, "previews": [{"preview_id": p.get("preview_id"), "duration_secs": p.get("duration_secs")}
294
+ for p in payload.get("previews") or []],
295
+ "next": "Describe the previews to the user (or let them listen in the voice picker), then "
296
+ "save_remixed_voice with the preview_id they pick."}
297
+ return payload
298
+
299
+ @mcp.tool(
300
+ title="Save remixed voice",
301
+ annotations=ToolAnnotations(title="Save remixed voice", read_only_hint=False, destructive_hint=True,
302
+ open_world_hint=True),
303
+ )
304
+ def save_remixed_voice(
305
+ design_id: Annotated[int, Field(description="design_id of the voice that was remixed")],
306
+ preview_id: Annotated[str, Field(min_length=1, description="The remix preview the user picked")],
307
+ voice_name: Annotated[str | None, Field(max_length=100, description="New name; omit to keep the old one")] = None,
308
+ ) -> dict[str, Any]:
309
+ """Replace the user's designed voice with the remix preview they picked (only after they choose it): the old voice is deleted at ElevenLabs and its voice_id changes; templates that used the old voice_id need the new one."""
310
+ try:
311
+ return client().save_remixed_voice(design_id, preview_id, voice_name=voice_name)
312
+ except Exception as exc:
313
+ return err(exc)
314
+
315
+ @mcp.tool(
316
+ title="Delete designed voice",
317
+ annotations=ToolAnnotations(title="Delete designed voice", read_only_hint=False, destructive_hint=True,
318
+ idempotent_hint=True, open_world_hint=True),
319
+ )
320
+ def delete_designed_voice(
321
+ provider: Annotated[str, Field(description="elevenlabs, minimax or inworld")],
322
+ design_id: Annotated[int, Field(description="design_id from list_voices my_voices")],
323
+ ) -> dict[str, Any]:
324
+ """Delete the user's designed voice here and at the provider (only when the user asks). They can then design another for that provider."""
325
+ try:
326
+ return client().delete_designed_voice(provider, design_id)
174
327
  except Exception as exc:
175
328
  return err(exc)
176
329