{"record":{"id":"037c9b722769a20b","repo":"harry0703/MoneyPrinterTurbo","slug":"elevenlabs-music-api-requires-a-paid-plan-the-cur","errorCode":null,"errorMessage":"ElevenLabs Music API requires a paid plan; the current account is on the free tier","messagePattern":"ElevenLabs Music API requires a paid plan; the current account is on the free tier","errorType":"exception","errorClass":"ElevenLabsPaidPlanRequiredError","httpStatus":null,"severity":"error","filePath":"app/services/elevenlabs_music.py","lineNumber":153,"sourceCode":"            except ValueError as exc:\n                raise ElevenLabsMusicError(\n                    \"ElevenLabs returned an invalid subscription response\"\n                ) from exc\n    except requests.RequestException as exc:\n        raise ElevenLabsMusicError(\n            f\"failed to connect to ElevenLabs: {exc}\"\n        ) from exc\n    if not isinstance(payload, dict):\n        raise ElevenLabsMusicError(\n            \"ElevenLabs returned an unexpected subscription response\"\n        )\n    tier = str(payload.get(\"tier\") or \"\").strip().lower()\n    if not tier:\n        raise ElevenLabsMusicError(\n            \"ElevenLabs subscription response does not include an account tier\"\n        )\n    if tier == \"free\":\n        raise ElevenLabsPaidPlanRequiredError(\n            \"ElevenLabs Music API requires a paid plan; \"\n            \"the current account is on the free tier\"\n        )\n    logger.info(f\"ElevenLabs account and plan check succeeded: tier={tier}\")\n    return payload\n\n\ndef validate_generation_access() -> None:\n    \"\"\"\n    在昂贵的视频流水线开始前排除确定无法生成配乐的账号。\n\n    免费套餐和无效 Key 都是确定性错误，必须立即终止，避免先消耗 LLM、TTS\n    和素材服务额度。订阅接口也可能因 Music-only endpoint scope、IP 限制或\n    临时网络问题不可访问；这些结果不能证明 Music API 不可用，因此只记录警告，\n    继续让真正的生成请求决定结果，避免把受限但可用的 Key 错误拦截。\n    \"\"\"\n    try:\n        test_connection()","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/harry0703/MoneyPrinterTurbo/blob/1f9f19c2021a68d04df228f33e9099a0c947f6f8/app/services/elevenlabs_music.py#L135-L171","documentation":"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.","triggerScenarios":"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.","commonSituations":"Trial subscription expired; using a personal free key in a shared deployment; new team member's key on the free plan.","solutions":["Upgrade the ElevenLabs account to a plan that includes Music, or switch the key to an account that has one.","Re-run test_connection() after upgrading to confirm the tier is no longer 'free'.","In the UI, catch ElevenLabsPaidPlanRequiredError separately and prompt for plan upgrade instead of showing a generic error."],"exampleFix":"# before\ntry:\n    validate_generation_access()\nexcept ElevenLabsMusicError as e:\n    abort(500, str(e))  # misleading for free-tier users\n\n# after\ntry:\n    validate_generation_access()\nexcept ElevenLabsPaidPlanRequiredError:\n    abort(402, 'Upgrade your ElevenLabs plan to use Music')\nexcept ElevenLabsMusicError as e:\n    abort(502, str(e))","handlingStrategy":"try-catch","validationCode":"from app.services import elevenlabs_music\n\ndef can_generate_music() -> bool:\n    if not elevenlabs_music.is_enabled():\n        return False\n    try:\n        elevenlabs_music.validate_generation_access()\n        return True\n    except ElevenLabsMusicError:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    generate(video, prompt)\nexcept ElevenLabsPaidPlanRequiredError:\n    show_user('Music requires a paid ElevenLabs plan; skipping BGM')\n    generate(video, prompt, bgm_type=None)  # degrade gracefully\nexcept ElevenLabsMusicError as e:\n    log_and_surface(e)","preventionTips":["Run validate_generation_access() before the expensive video pipeline so free accounts fail fast.","Catch ElevenLabsPaidPlanRequiredError separately from ElevenLabsMusicError to offer a plan upgrade prompt.","Degrade to no-BGM instead of failing the whole generation when the tier check fails."],"tags":["elevenlabs","billing","plan-limit","precondition"],"backgroundTag":null,"analyzedSha":"1f9f19c2021a68d04df228f33e9099a0c947f6f8","analyzedAt":"2026-08-14T19:41:05.568Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}