harry0703/MoneyPrinterTurbo · error · ElevenLabsPaidPlanRequiredError

ElevenLabs Music API requires a paid plan; the current accou

Error message

ElevenLabs Music API requires a paid plan; the current account is on the free tier

What it means

ElevenLabsPaidPlanRequiredError (a subclass of ElevenLabsMusicError) raised by test_connection() when the subscription tier is exactly 'free'. Music generation is a paid-only endpoint, so this is a deterministic pre-check: validate_generation_access() runs it before the expensive video pipeline so a free account fails fast instead of after consuming LLM/TTS work. Catching this specific subclass lets callers show an 'upgrade plan' message distinct from generic failures.

Source

Thrown at app/services/elevenlabs_music.py:153

            except ValueError as exc:
                raise ElevenLabsMusicError(
                    "ElevenLabs returned an invalid subscription response"
                ) from exc
    except requests.RequestException as exc:
        raise ElevenLabsMusicError(
            f"failed to connect to ElevenLabs: {exc}"
        ) from exc
    if not isinstance(payload, dict):
        raise ElevenLabsMusicError(
            "ElevenLabs returned an unexpected subscription response"
        )
    tier = str(payload.get("tier") or "").strip().lower()
    if not tier:
        raise ElevenLabsMusicError(
            "ElevenLabs subscription response does not include an account tier"
        )
    if tier == "free":
        raise ElevenLabsPaidPlanRequiredError(
            "ElevenLabs Music API requires a paid plan; "
            "the current account is on the free tier"
        )
    logger.info(f"ElevenLabs account and plan check succeeded: tier={tier}")
    return payload


def validate_generation_access() -> None:
    """
    在昂贵的视频流水线开始前排除确定无法生成配乐的账号。

    免费套餐和无效 Key 都是确定性错误，必须立即终止，避免先消耗 LLM、TTS
    和素材服务额度。订阅接口也可能因 Music-only endpoint scope、IP 限制或
    临时网络问题不可访问；这些结果不能证明 Music API 不可用，因此只记录警告，
    继续让真正的生成请求决定结果，避免把受限但可用的 Key 错误拦截。
    """
    try:
        test_connection()

View on GitHub (pinned to 1f9f19c202)

Solutions

  1. Upgrade the ElevenLabs account to a plan that includes Music, or switch the key to an account that has one.
  2. Re-run test_connection() after upgrading to confirm the tier is no longer 'free'.
  3. In the UI, catch ElevenLabsPaidPlanRequiredError separately and prompt for plan upgrade instead of showing a generic error.

Example fix

# before
try:
    validate_generation_access()
except ElevenLabsMusicError as e:
    abort(500, str(e))  # misleading for free-tier users

# after
try:
    validate_generation_access()
except ElevenLabsPaidPlanRequiredError:
    abort(402, 'Upgrade your ElevenLabs plan to use Music')
except ElevenLabsMusicError as e:
    abort(502, str(e))
Defensive patterns

Strategy: try-catch

Validate before calling

from app.services import elevenlabs_music

def can_generate_music() -> bool:
    if not elevenlabs_music.is_enabled():
        return False
    try:
        elevenlabs_music.validate_generation_access()
        return True
    except ElevenLabsMusicError:
        return False

Try / catch

try:
    generate(video, prompt)
except ElevenLabsPaidPlanRequiredError:
    show_user('Music requires a paid ElevenLabs plan; skipping BGM')
    generate(video, prompt, bgm_type=None)  # degrade gracefully
except ElevenLabsMusicError as e:
    log_and_surface(e)

Prevention

When it happens

Trigger: Calling test_connection() or validate_generation_access() while the configured key belongs to a free-tier account; also when a paid subscription has lapsed and downgraded back to free.

Common situations: Trial subscription expired; using a personal free key in a shared deployment; new team member's key on the free plan.

Related errors

AI-assisted analysis of harry0703/MoneyPrinterTurbo@1f9f19c202 (2026-08-14). Data as JSON: /api/errors/037c9b722769a20b. Report an issue: GitHub.