tts_elevenlabs_voices.py 7.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158
  1. """ElevenLabs voice search behind ``text_to_speech``'s ``find_voices`` argument.
  2. The argument (and ``voice_id``) only exist in the ElevenLabs variant of the ``text_to_speech``
  3. schema, so other providers never see voice search. Two sources share one paginated shape:
  4. ``library`` (``GET /v1/shared-voices``: the public Voice Library, the default) and ``account``
  5. (``GET /v2/voices``: premade + the user's saved, cloned and designed voices). ``next_page`` is
  6. opaque to the model: a page number for the library and a cursor token for the account.
  7. """
  8. from __future__ import annotations
  9. import json
  10. import logging
  11. from typing import Any, Optional
  12. import httpx
  13. from tools.registry import tool_error
  14. logger = logging.getLogger(__name__)
  15. DEFAULT_ELEVENLABS_BASE_URL = "https://api.elevenlabs.io"
  16. SOURCES = ("library", "account")
  17. # GET /v1/shared-voices ``sort`` keys; the default ranks by a year of real usage.
  18. LIBRARY_SORTS = ("usage_character_count_1y", "trending", "cloned_by_count", "created_date")
  19. _DEFAULT_PAGE_SIZE = 20
  20. _MAX_PAGE_SIZE = 100
  21. _DESCRIPTION_MAX_CHARS = 240
  22. _TIMEOUT_SECONDS = 20.0
  23. _FILTERS = ("gender", "age", "accent", "language")
  24. FIND_VOICES_SCHEMA = {
  25. "type": "object",
  26. "description": (
  27. "Search voices instead of speaking (text is then not needed). Returns a page of voices "
  28. "with voice_id, labels, description and preview_url; pass next_page back as page. "
  29. "source 'library' (default) = the public Voice Library, thousands of community voices, "
  30. "most-used first, usable directly by voice_id; 'account' = the user's own voices. The "
  31. "library search matches words in names and descriptions literally: when a role word "
  32. "('dwarf', 'blacksmith') finds nothing, describe the sound instead ('gravelly old', "
  33. "'deep growl') with gender/age and use_case 'characters_animation'. You can't hear "
  34. "voices: choose from labels and description, and give the user preview_url links when "
  35. "the pick matters."),
  36. "properties": {
  37. "query": {"type": "string", "description": "Free-text search, e.g. 'orc' or 'gravelly old'."},
  38. "source": {"type": "string", "enum": list(SOURCES)},
  39. "gender": {"type": "string", "description": "e.g. male, female, neutral."},
  40. "age": {"type": "string", "description": "e.g. young, middle_aged, old."},
  41. "accent": {"type": "string", "description": "e.g. british, american, scottish."},
  42. "language": {"type": "string", "description": "ISO 639-1 code, e.g. en."},
  43. "use_case": {"type": "string", "description": (
  44. "Library only, e.g. characters_animation, narrative_story, conversational.")},
  45. "sort": {"type": "string", "enum": list(LIBRARY_SORTS),
  46. "description": "Library only; default usage_character_count_1y (most used)."},
  47. "page": {"type": "string", "description": "next_page from the previous result."},
  48. "page_size": {"type": "integer", "description": "1-100, default 20."},
  49. },
  50. }
  51. def _clip(text: Any) -> str:
  52. text = " ".join(str(text or "").split())
  53. return text if len(text) <= _DESCRIPTION_MAX_CHARS else text[: _DESCRIPTION_MAX_CHARS - 1] + "…"
  54. def _voice_row(voice: dict[str, Any]) -> dict[str, Any]:
  55. """One compact voice: library rows carry the traits at top level, account rows under ``labels``."""
  56. raw_labels = voice.get("labels")
  57. labels: dict[str, Any] = raw_labels if isinstance(raw_labels, dict) else {}
  58. row = {"voice_id": voice.get("voice_id"), "name": voice.get("name")}
  59. for key in ("gender", "age", "accent", "language", "descriptive", "use_case"):
  60. value = voice.get(key) or labels.get(key) or labels.get(key.replace("_", " "))
  61. if value:
  62. row[key] = value
  63. if voice.get("category"):
  64. row["category"] = voice["category"]
  65. if voice.get("description"):
  66. row["description"] = _clip(voice["description"])
  67. if voice.get("rate") not in (None, 1, 1.0): # library voice billed at a custom credit multiplier
  68. row["credit_rate"] = voice["rate"]
  69. if voice.get("preview_url"):
  70. row["preview_url"] = voice["preview_url"]
  71. return row
  72. def _request_params(source: str, query: str, filters: dict[str, str], use_case: str, sort: str,
  73. page: str, page_size: int) -> tuple[str, dict[str, Any]]:
  74. """``(path, params)`` for one source; raises ValueError on a bad cursor or sort."""
  75. params: dict[str, Any] = {"page_size": page_size, **filters}
  76. if query:
  77. params["search"] = query
  78. if source == "account":
  79. params["include_total_count"] = "false"
  80. if page:
  81. params["next_page_token"] = page
  82. return "/v2/voices", params
  83. if page and not page.isdigit():
  84. raise ValueError(f"Invalid library page {page!r}: pass next_page from the previous result.")
  85. if sort and sort not in LIBRARY_SORTS:
  86. raise ValueError(f"find_voices.sort must be one of {', '.join(LIBRARY_SORTS)}")
  87. params["sort"] = sort or LIBRARY_SORTS[0]
  88. if use_case:
  89. params["use_cases"] = [use_case]
  90. params["page"] = int(page or 0)
  91. return "/v1/shared-voices", params
  92. def _next_page(source: str, body: dict[str, Any], page: str) -> Optional[str]:
  93. if not body.get("has_more"):
  94. return None
  95. if source == "account":
  96. return body.get("next_page_token") or None
  97. return str(int(page or 0) + 1)
  98. def search_voices(find: dict[str, Any], tts_config: dict[str, Any], api_key: str) -> str:
  99. """Search one ElevenLabs voice source and return a compact, paginated JSON page."""
  100. def arg(name: str) -> str:
  101. return str(find.get(name) or "").strip()
  102. source = (arg("source") or SOURCES[0]).lower()
  103. if source not in SOURCES:
  104. return tool_error(f"find_voices.source must be one of {', '.join(SOURCES)}", success=False)
  105. try:
  106. size = max(1, min(_MAX_PAGE_SIZE, int(find.get("page_size") or _DEFAULT_PAGE_SIZE)))
  107. except (TypeError, ValueError):
  108. size = _DEFAULT_PAGE_SIZE
  109. filters = {name: arg(name).lower() for name in _FILTERS if arg(name)}
  110. page = arg("page")
  111. try:
  112. path, params = _request_params(source, arg("query"), filters, arg("use_case").lower(),
  113. arg("sort").lower(), page, size)
  114. except ValueError as exc:
  115. return tool_error(str(exc), success=False)
  116. el_config = tts_config.get("elevenlabs") or {}
  117. base_url = (el_config.get("base_url") or DEFAULT_ELEVENLABS_BASE_URL).rstrip("/")
  118. try:
  119. response = httpx.get(base_url + path, params=params, timeout=_TIMEOUT_SECONDS,
  120. headers={"xi-api-key": api_key, "accept": "application/json"})
  121. except httpx.HTTPError as exc:
  122. return tool_error(f"ElevenLabs voice search failed: {exc}", success=False)
  123. if response.status_code != 200:
  124. logger.warning("ElevenLabs %s returned HTTP %s", path, response.status_code)
  125. return tool_error(f"ElevenLabs voice search failed (HTTP {response.status_code}): "
  126. f"{response.text[:300]}", success=False)
  127. try:
  128. body = response.json()
  129. except ValueError:
  130. return tool_error("ElevenLabs voice search returned a non-JSON body", success=False)
  131. voices = [_voice_row(v) for v in body.get("voices") or [] if isinstance(v, dict)]
  132. result: dict[str, Any] = {
  133. "success": True, "source": source, "count": len(voices), "voices": voices,
  134. "next_page": _next_page(source, body, page),
  135. "configured_voice_id": el_config.get("voice_id") or None,
  136. }
  137. if source == "library" and body.get("total_count"):
  138. result["total"] = body["total_count"]
  139. return json.dumps(result, ensure_ascii=False)